Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 38 ยท Testing and Tooling

Testing Basics for Lit and Web Components

Learn how to test Lit components in a real browser: create a fixture, wait for updateComplete, query the shadow DOM, assert and clean up. Includes a tiny test runner you can run here.

Web components are real DOM elements, so the most trustworthy way to test them is in a real browser, not in a simulated DOM. A fake DOM can miss shadow DOM, custom element upgrades and focus behavior, which are exactly the things components are made of.

Every component test follows the same four steps: create the element, wait for it to render, act and assert, then clean up. This lesson explains each step and lets you run a tiny test runner right on the page. The production tools (Web Test Runner, Vitest browser mode, Playwright) are shown read-only because they need Node and a project.

The test loop

flowchart LR
    A["Create fixture<br/>(add element to page)"] --> B["await updateComplete"]
    B --> C["Query shadowRoot"]
    C --> D["Act (click, set property)"]
    D --> E["await updateComplete again"]
    E --> F["Assert"]
    F --> G["Remove fixture"]

Forgetting the second wait is the most common cause of flaky component tests.

Why updateComplete matters

Lit updates are asynchronous: when you set a property, the DOM changes in a microtask, not immediately. Test code that checks the DOM right after setting a property sees the old output. Awaiting element.updateComplete resolves after the render finished.

A mini test runner you can run

The block below defines fixture, describe, it and expect in about 30 lines, then tests a counter component. Real runners such as @open-wc/testing provide the same ideas with more polish.

Testing a counter

The last test fails on purpose so you can see what a failure message looks like. A good message names both the expected and the actual value.

Query the shadow DOM correctly

document.querySelector("button") will not find a button inside a shadow root. Go through the host:

JavaScript
const button = el.shadowRoot.querySelector("button");

If your component has slotted content, query the host's own children instead: they live in the light DOM, and only the slot element lives in the shadow tree.

Test what users can observe

Prefer assertions about rendered text, attributes, events and accessible roles. Avoid asserting on private fields like _status, because refactoring should not break tests. Compare:

Brittle Better
expect(el._open).toBe(true) check aria-expanded="true" on the toggle
expect(el.shadowRoot.innerHTML).toBe(...) check the visible text of a heading
call el._handleClick() dispatch a real click

Testing events

Components talk to the outside with events (see dispatching events). Listen before you act, then assert on what arrived.

Asserting a custom event

Real tools, read-only

In a project you install a runner that launches real browsers. A typical web-test-runner.config.mjs:

JavaScript
import { playwrightLauncher } from "@web/test-runner-playwright";

export default {
  files: "test/**/*.test.js",
  nodeResolve: true,
  browsers: [
    playwrightLauncher({ product: "chromium" }),
    playwrightLauncher({ product: "firefox" }),
    playwrightLauncher({ product: "webkit" }),
  ],
};

And a test using @open-wc/testing, which provides fixture, html, expect and oneEvent:

JavaScript
import { fixture, html, expect } from "@open-wc/testing";
import "../src/click-counter.js";

it("counts clicks", async () => {
  const el = await fixture(html`<click-counter></click-counter>`);
  el.shadowRoot.querySelector("button").click();
  await el.updateComplete;
  expect(el.count).to.equal(1);
});

Running the same suite in Chromium, Firefox and WebKit is cheap and catches browser-specific differences before your users do. The next lesson covers controllers, slots and keyboard behavior.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do component tests await element.updateComplete after changing a property?

    Lit batches updates into a microtask. updateComplete resolves after the new render, so assertions see current output.
  2. 2. How do you find a button that lives inside a component's shadow DOM?

    The shadow root encapsulates its tree, so you query through the host's shadowRoot.
  3. 3. Which assertion is least likely to break during a harmless refactor?

    Observable output (text, attributes, events) is the contract; private fields and markup details are implementation.
  4. 4. Why run component tests in real browsers?

    Simulated DOMs can differ in encapsulation, upgrade timing and focus handling, which are central to components.

Summary

  • Create, wait, act, wait again, assert, clean up.
  • Lit renders asynchronously: always await el.updateComplete.
  • Query through shadowRoot and assert on observable output.
  • Test events by listening first, then acting.
  • Real runners (Web Test Runner, Vitest browser mode) run your suite in real browsers.

Next: Testing Events, Slots and Controllers