Test Your Components

Before you test components, make sure you've reviewed the best practices for portable components.

You can test your components for SSR with the SSR playground, SSR test runner, and unit tests with Jest.

The SSR playground enables you to render, debug, and experiment with individual components and their children in both CSR and SSR modes.

Run the playground commands from a directory that contains one of these files:

  • lwc.config.json file
  • package.json file containing an lwc field
  • sfdx-project.json file that points to a project directory containing LWCs

To open the playground in Chrome, run this command:

To open the playground in Chrome with DevTools:

Start at the "leaves" of your component tree, or components that don't contain other components.

  1. Open the component in the SSR playground.
    1. Modify the component props to test important use cases.
    2. Address errors that are reported during the three phases of hydration—SSR, DOM insertion, and rehydration.
    3. Look for and address any visual bugs in your component.
  2. Enable the CSR toggle to render your component with SSR and CSR side by side.
  3. Use the playground’s comparison tool to ensure the SSR and CSR component instances are visually identical.

The SSR playground's comparison tool.

By default, the SSR playground takes your component through three stages of its SSR lifecycle:

  • Render the component to HTML markup on the server.
  • Insert the markup into the DOM on the client.
  • Hydrate the DOM subtree and associate it with an instance of your component class.

We recommend that you write tests using the SSR test runner to ensure that your components don't regress as you make changes.

Just like you can use Jest to write unit tests for your LWCs, you can use the SSR test runner to make assertions about your LWCs in SSR-related scenarios.

By default, the SSR tests run in headless Chrome. Unlike Jest tests, the SSR tests run in a full-featured web browser.

Use these functions from @lwc/uplift-toolkit/test.js.

  • renderToMarkup is an async function that takes the path to your component and the props you use for rendering. It returns Promise<String> where the String is HTML markup.
  • insertMarkupIntoDom is an async function that takes SSR markup (like that returned from renderToMarkup) as its single argument. It returns Promise<HtmlElement>, which is a handle to the root element of your SSR-rendered DOM subtree.
  • hydrateElement is an async function that takes a root element (like that returned from insertMarkupIntoDom) and component props (which should probably be the same as what was passed to renderToMarkup). It returns a Promise<Boolean>, where the Boolean indicates whether hydration completed without validation errors. In most cases, you'll want this Boolean value to be true. If hydration failed, review the errors in the console.

To invoke the test runner, run this command:

If you use ZSH, surround SPEC_FILE_PATTERN in single quotes.

To distinguish the SSR tests from Jest tests, use unique file extensions. For example, if your Jest tests follow the format COMPONENT_NAME.spec.js, you can follow the format COMPONENT_NAME.spec-ssr.js for your SSR test files. If you follow this filename format, run your tests like this:

Tests run in parallel in separate headless Chrome tabs. The tests run fast, and as much as ten thousand tests can complete in under six seconds, depending on your hardware.

Here's an example of an SSR test.

Once you've configured your components for SSR and aligned them with the SSR best practices, you can opt-into SSR by following the instructions in Enable SSR for LWR Apps.