# lightning-components-stubs

Package to provide stubs for the Lightning base components. The stubs are generated from a component metadata file published by the base component team. This helps ensure stubs are kept up to date.

There are two sets of stubs in this project. The `modules/lightning-stubs/core` folder contains stubs for all base components that are available to developers in SFDC core. `modules/lightning-stubs/platform` contains stubs for the components available to external (aka platform) developers. This access is determined by the contents of the `<component>.js-meta.xml` file.

## Usage

1. In the consuming project:

```bash
yarn add -D lightning-components-stubs
```

2. Update the Jest config to point to these stubs. The below code maps all `lightning` namespaced imports to the stubs, but you have the freedom to choose exactly what kind of mapping you want to use. You could, for example, map a subset of components to custom stubs in your project and map the rest to this project.

```json
{
    "moduleNameMapper": {
        "^lightning/(.+)$": "<rootDir>/node_modules/lightning-components-stubs/modules/lightning-stubs/core/$1/$1"
    }
}
```

3. Update the Jest config to run these components through the transformer. By default, Jest will not send files inside node_modules through the transformer.

```json
{
    "transformIgnorePatterns": ["node_modules/(?!(lightning-components-stubs/modules)/)"]
}
```

4. Run your Jest tests as normal!

## Updating stubs

1. Update the `lwc-components-lightning` depenedency to the latest (or desired version).
2. Pull down updated dependency.

```bash
$ yarn
```

3. Regenerate stubs into the `modules/lightning-stubs` folder.

```bash
$ yarn generate-mocks
```

4. Double check stubs that are ignored from the auto-generation script. Stubs are ignored either because they leverage class inheritance which the metadata file does not account for, or because they are javascript only libraries where the metadata file does not track API shape or return values.
    1. Open `./scripts/generate-lightning-mocks.js` and note modules in `ignoreList`, `customMocks`, and `customMocksCore`.
    1. Find the [source](https://github.com/salesforce/lightning-components/tree/master/ui-lightning-components/src/main/modules) for the components in the the Base Components repo.
    1. For modules in the `ignoreList`, add any missing `@api` methods or properties to `modules/lightning-stubs/core` and `modules/lightnings-stubs/platform` where applicable. For modules or libraries in `customMocks` and `customMocksCore`, add changes to the `./customMocks` folder.
    1. For new library methods, make sure the return value is something reasonable. For example, if the library method returns a Promise, set that method to `jest.fn().mockResolvedValue()` to emulate how the real API behaves.

## Manually managed stubs

The metadata file (lwc-components-lightning/metadata/raptor.json) Lightning components provides is for the API shape of it's components, but does not account for exposed libraries. Because of this, some stubs must be manually managed and should be reviewed at least once per release.

For the list of libraries that much be manually managed, see the `customMocks` and `customMocksCore` lists in [generate-lightning-mocks.js](./scripts/generate-lightning-mocks.js);

## Resetting

To regenerate the stubs, run `yarn build`. If things got really weird and you want a fresh start, run `yarn clean && yarn && yarn build`.

## Update Lightning component version

Stubs and components are based on the what the lightning-components project publishes to NPM. As of this writing, that is still a manual process and the NPM packages are not updated at the same cadance the rest of the project is updated and released.

For documentation on their NPM release process, see [this](https://github.com/salesforce/lightning-components/blob/master/docs/NPM_PUBLISH.md).
