# Jest mocks for `lightning/*` modules

Target: `@salesforce/sfdx-lwc-jest` (Spring '26). Sources: [Test Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/unit-testing.html), [`salesforce/sfdx-lwc-jest` stubs](https://github.com/salesforce/sfdx-lwc-jest/tree/master/src/lightning-stubs), [`trailheadapps/lwc-recipes` jest-mocks](https://github.com/trailheadapps/lwc-recipes/tree/main/force-app/test/jest-mocks).

`sfdx-lwc-jest` already stubs every `lightning/*` module through its resolver. Write a mock only when the test needs to **observe** what the component did with it, and then map that one module in `jest.config.js`.

## 1. `lightning/navigation`

`force-app/test/jest-mocks/lightning/navigation.js`:

```js
import { createTestWireAdapter } from '@salesforce/wire-service-jest-util';

export const CurrentPageReference = createTestWireAdapter(jest.fn());

const Navigate = Symbol('Navigate');
const GenerateUrl = Symbol('GenerateUrl');

export const mockNavigate = jest.fn();
export const mockGenerate = jest.fn();

export const NavigationMixin = (Base) =>
    class extends Base {
        [Navigate](pageReference, replace) {
            mockNavigate({ pageReference, replace });
        }
        [GenerateUrl](pageReference) {
            mockGenerate({ pageReference });
            return Promise.resolve('https://www.example.com');
        }
    };
NavigationMixin.Navigate = Navigate;
NavigationMixin.GenerateUrl = GenerateUrl;

export const getNavigateCalledWith = () =>
    mockNavigate.mock.calls.length === 0
        ? { pageReference: undefined, replace: undefined }
        : mockNavigate.mock.lastCall[0];
```

In the test:

```js
import { getNavigateCalledWith } from 'lightning/navigation';

element.shadowRoot.querySelector('a.order-link').click();
await flushPromises();

const { pageReference } = getNavigateCalledWith();
expect(pageReference.type).toBe('standard__recordPage');
expect(pageReference.attributes.recordId).toBe('0011x00000abcDEF');
```

## 2. `lightning/messageService`

`force-app/test/jest-mocks/lightning/messageService.js`:

```js
export const APPLICATION_SCOPE = Symbol('APPLICATION_SCOPE');
export const createMessageContext = jest.fn();
export const releaseMessageContext = jest.fn();
export const publish = jest.fn();
export const subscribe = jest.fn();
export const unsubscribe = jest.fn();
export const MessageContext = jest.fn();
```

Publisher test: assert `publish` was called with the channel and payload. Subscriber test: pull the handler out of the mock and call it directly.

```js
import { subscribe, publish } from 'lightning/messageService';
import ORDER_SELECTED from '@salesforce/messageChannel/Order_Selected__c';

it('updates when a message arrives', async () => {
    const element = createElement('c-order-detail', { is: OrderDetail });
    document.body.appendChild(element);

    const handler = subscribe.mock.calls[0][2];      // (context, channel, handler, config)
    handler({ orderId: '801xx0000000001' });
    await flushPromises();

    expect(element.shadowRoot.querySelector('h2').textContent).toContain('801xx0000000001');
});
```

Note: a message channel import (`@salesforce/messageChannel/…`) needs no `jest.mock`; the resolver stubs it.

## 3. Toasts, modals and refresh

```js
// force-app/test/jest-mocks/lightning/platformShowToastEvent.js
export const ShowToastEventName = 'lightning__showtoast';
export class ShowToastEvent extends CustomEvent {
    constructor(config) {
        super(ShowToastEventName, { composed: true, cancelable: true, bubbles: true, detail: config });
    }
}
```

```js
// asserting a toast
const handler = jest.fn();
element.addEventListener(ShowToastEventName, handler);
// …trigger the action…
expect(handler).toHaveBeenCalled();
expect(handler.mock.calls[0][0].detail.variant).toBe('error');
```

For `lightning/modal`, mock the module's `open` as a `jest.fn()` returning the result the component expects (`Promise.resolve('ok')`), and assert both the call and what the component did with the result. For `lightning/refresh`, mock `RefreshEvent` the same way as `ShowToastEvent` and listen for `'lightning__refreshview'`.

## 4. LDS adapters need no mock

```js
import { getRecord } from 'lightning/uiRecordApi';
const mockGetRecord = require('./data/getRecord.json');   // a UI API snapshot

const element = createElement('c-order-summary', { is: OrderSummary });
element.recordId = '801xx0000000001';
document.body.appendChild(element);
getRecord.emit(mockGetRecord);
await flushPromises();
```

Take the JSON from a real `/ui-api/records/{id}` response rather than writing it by hand — hand-written LDS payloads miss the `fields.X.value` / `displayValue` shape and produce tests that pass against fiction.

`updateRecord` and friends are plain mocks on the stub: `import { updateRecord } from 'lightning/uiRecordApi'` and assert `toHaveBeenCalledWith({ fields: { Id: …, Status__c: 'Approved' } })`.

## 5. GraphQL wires

```js
import { graphql } from 'lightning/uiGraphQLApi';
const mockGraphQL = require('./data/openOrders.json');

graphql.emit(mockGraphQL);            // graphql is an LDS-style test wire adapter
await flushPromises();
```

The emitted shape must match the real envelope (`{ data: { uiapi: { query: { … } } }, errors: [] }`), so snapshot it from an org rather than inventing it.

## 6. `refreshApex` and refresh assertions

```js
jest.mock('@salesforce/apex', () => ({ refreshApex: jest.fn(() => Promise.resolve()) }), { virtual: true });
```

```js
import { refreshApex } from '@salesforce/apex';
// …trigger the mutation…
expect(refreshApex).toHaveBeenCalled();
```

`notifyRecordUpdateAvailable` is on the `lightning/uiRecordApi` stub and can be asserted directly:

```js
import { notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';
expect(notifyRecordUpdateAvailable).toHaveBeenCalledWith([{ recordId: '801xx0000000001' }]);
```

## 7. Common failures and their cause

| Symptom | Cause |
|---|---|
| `getOrders.emit is not a function` | Wired Apex mocked as a bare `jest.fn()` — use `createApexTestWireAdapter` |
| `expect(...).toBeAccessible is not a function` | sa11y setup file not registered, usually `setupFilesAfterEach` instead of `setupFilesAfterEnv` |
| `Cannot find module 'lightning/…'` | A wildcard `moduleNameMapper` pointing at a mocks folder that has no file for that module |
| Assertions see the old DOM | Missing `await flushPromises()` (one microtask tick is enough after `emit`) |
| Wire emits but nothing renders | `emit` called before `document.body.appendChild(element)` |
| State leaks between tests | No DOM reset and no `jest.clearAllMocks()` in `afterEach` |
