The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

Write Jest Tests for Lightning Web Components That Use the Wire Service

Components use the wire service to get data from Salesforce. To test how these components handle data and errors from the wire service, use the @salesforce/sfdx-lwc-jest test utility.

The input that your test consumes shouldn't depend on outside code or data—you must have full control over it. Import the test utility API from sfdx-lwc-jest to mock the data so your test isn’t dependent on unpredictable factors like remote invocation or server latency.

The sfdx-lwc-jest utility has three adapters for mocking wire service data: a generic wire adapter, a Lightning Data Service (LDS) wire adapter, and an Apex wire adapter.

  • The generic adapter emits data on demand when you call the emit() API. It does not include any extra information about the data itself.
  • The LDS adapter mimics Lightning Data Service behavior and includes information about the data’s properties.
  • The Apex wire adapter mimics calls to an Apex method and includes any error status.

If you’re not using the sfdx-lwc-jest utility for working with Salesforce DX, you can import adapters using the @salesforce/wire-service-jest-util test utility. However, we recommend using sfdx-lwc-jest for an integrated development experience.

To control the test, instead of getting data from Salesforce, create a JSON file that defines the data that the component expects.

To use the wire service test utility, follow these high-level steps.

  1. In your component bundle, create a folder called __tests__ and a JavaScript class called componentName.test.js. It’s a best practice to name the file after the component, followed by .test.js.
  2. In the __tests__ folder, create a data folder, and a JSON file called _wireAdapter_.json.
    1. In the JSON file, mock the data that the wire adapter emits.
    2. If the wire adapter is an LDS wire adapter, grab a snapshot of data using a REST client that accesses the UI API that the wire adapter is based on. This approach is more accurate than writing JSON by hand.
  3. In the componentName.test.js file:
    1. Import the component under test and its wire adapter. The test must reference the same wire adapter as the component under test.
    2. Import the mock data from the JSON file.
    3. Emit the mock data.
    4. Verify that the component received the mock data.

Our sample component is a product card component.

The product card component displays a product and its name.

In the component's JavaScript file, the @wire decorator tells the wire service to use the getRecord wire adapter to provision record data. It decorates the wiredRecord function, which receives an object with error or data properties.

The lwc-recipes repo has examples of several components using the wire service that include Jest tests.

In your __tests__ folder, create a folder called data. Within the data folder, make a file called getRecord.json, the same name as the wire adapter. Define the data that the component expects from the server. You can author the JSON yourself, but that can get difficult and error prone. The best practice is to grab a snapshot of data using a REST client that accesses the UI API. For example, this data is a response from /ui-api/records/{recordId}, which is the resource that backs the getRecord wire adapter.

Our mocked data defines only the Name field on the record. In a real test, mock all the data that your component expects.

The unit test checks that the product card displays the product name.

The test must import the wire adapter used in the component under test. Here, that's the getRecord wire adapter from the lightning/uiRecordApi module. The test must also import the mock data to send through the wire adapter.

The test creates the component and appends it to the DOM. The component receives updates about data only when the component is connected to the DOM. After the component connects, pass the mocked data to the emit function on the wire adapter.

After emitting the mocked data, if product or name change, the component rerenders. Resolve a promise to ensure that the test code runs after the DOM has been updated with the new data. The code verifies that the product name field from the mock data is properly output in the DOM.

In Spring ’21 and earlier releases, you had to register the wire adapter under test. That code still works, but it isn’t recommended.

See Also