Testing the DOM & end to end

Test what users do, not what components hide

You have already met three kinds of tests:

• Unit testing checks small pieces of logic, such as one function.
• Mocks, spies & fakes replace time, the network, and random numbers with things your test controls.
• Testing async code makes tests wait for promises, timers, and events.

The UI (user interface) is the part of the app people see and use: text, buttons, and form fields. UI tests ask a new question. Can a person see the right thing, use the right control, and get the right result?

This lesson uses ideas from earlier lessons: DOM tree, modifying the DOM, events, form elements, keyboard and focus, and form validation.

The table below compares three ways to check a UI. Each row is one way. Read across to see what it is good at and what it cannot check.

A test runner is the program that runs your tests and reports which pass. Jest and Vitest are two popular ones. They run in Node.js, which has no browser page. So for DOM tests they often use jsdom.

jsdom is a pretend browser page written in JavaScript. It runs inside Node.js. It can:

• read HTML and build elements from it,
• send events such as clicks,
• let your test look at the page that results.

It does all this without opening a real browser, so it is fast.

// Non-runnable here: install jsdom in your test project first.
import { JSDOM } from "jsdom";

const dom = new JSDOM(`<!doctype html><button>Save</button>`, {
  url: "https://example.test/form",
});

const { document } = dom.window;
console.log(document.querySelector("button").textContent);

Line 4 builds a page from a string of HTML. Line 8 takes the document out of it. Line 9 reads the button's text, so it would print Save.

Now look at a link that every page has: a label and its input. The label's for value is the same as the input's id. That match connects them. A DOM test can check this link without looking at any CSS class.

document.querySelector("#app").innerHTML =
  '<label for="email">Email</label><input id="email">';
const input = document.querySelector("#email");
console.log(input.labels[0].textContent);

Lines 1 and 2 add a label and an input to the page. Line 3 finds the input. Line 4 reads the input's label through input.labels, so it prints Email.

This project does not install jsdom, so you cannot run its setup example here. The lesson runs its other examples in your real browser instead.

jsdom has limits. Its own docs say it does not do layout (working out where each box sits on the screen) or navigation (loading a new page). So:

• elements have no real size or position on the screen,
• measurements such as offsetTop (how far an element is from the top) are not real,
• clicking a link does not load a new page.

Testing Library is a popular set of tools for DOM tests. Its main rule is: "the more your tests resemble the way your software is used, the more confidence they can give you." In other words, a test should find things the way a person finds them.

A person does not look for a CSS class. They look for:

• a role: what kind of thing it is, such as a button or a text box (textbox),
• a name: what it is called, such as the text on a button or the label of a field (this is called the accessible name, because screen readers read it aloud),
• visible text, such as a message.

Testing Library has a function for each: getByRole, getByLabelText, and getByText. It also has two other families. findBy* waits for something to appear. queryBy* is for checking that something is not there. (The * means "any ending", such as queryByText.)

The table below lists the main queries. Read each row as: this query, use it for this, and this is why it is better than a CSS class or a test ID.

This project does not install Testing Library or its partner user-event (which acts out clicks and typing). So this lesson writes a tiny copy of a few of its functions that you can run. The copy knows only the roles and names that the small form below uses. It still works the same way as the real thing.

First, here is what a test looks like with the real Testing Library:

// Non-runnable here: @testing-library/* is not installed in this lesson.
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("submits a greeting", async () => {
  const user = userEvent.setup();
  render(<GreetingForm />);

  await user.type(screen.getByRole("textbox", { name: /name/i }), "Ava");
  await user.click(screen.getByRole("button", { name: /submit/i }));

  expect(await screen.findByText("Thanks, Ava!")).toBeVisible();
});

Line 9 types Ava into the text box named "name". Line 10 clicks the Submit button. Line 12 waits for the message Thanks, Ava! to show up.

Next is the tiny copy that this lesson runs. You do not need to read every line.

1function normalizeText(value) {2  return (value ?? "").replace(/\s+/g, " ").trim();3}4function matchesText(value, matcher) {5  const text = normalizeText(value);6  return typeof matcher === "string" ? text === matcher : matcher.test(text);7}8function accessibleName(element) {9  const aria = normalizeText(element.getAttribute("aria-label"));10  if (aria) return aria;11  const tag = element.tagName.toLowerCase();12  if (["input", "textarea", "select"].includes(tag)) {13    const labels = element.labels ? Array.from(element.labels) : [];14    const labelText = normalizeText(labels.map((label) => label.textContent).join(" "));15    if (labelText) return labelText;16  }17  if (tag === "img") return normalizeText(element.getAttribute("alt"));18  return normalizeText(element.textContent);19}20function implicitRole(element) {21  const role = normalizeText(element.getAttribute("role"));22  if (role) return role.split(" ")[0];23  const tag = element.tagName.toLowerCase();24  if (tag === "button") return "button";25  if (tag === "textarea") return "textbox";26  if (tag === "input" && ["email", "search", "tel", "text", "url"].includes(element.type)) return "textbox";27  if (tag === "input" && ["button", "submit", "reset"].includes(element.type)) return "button";28  if (tag === "a" && element.hasAttribute("href")) return "link";29  return "";30}31function allElements(root) {32  return root.documentElement ? Array.from(root.querySelectorAll("*")) : [root, ...root.querySelectorAll("*")];33}34function getByRole(root, role, options = {}) {35  const matches = allElements(root).filter((element) => implicitRole(element) === role && (options.name === undefined || matchesText(accessibleName(element), options.name)));36  if (matches.length === 1) return matches[0];37  if (matches.length === 0) throw new Error('No element found with role "' + role + '"' + (options.name ? ' and name "' + options.name + '"' : '') + ".");38  throw new Error('Found ' + matches.length + ' elements with role "' + role + '".');39}40function getByText(root, text) {41  const matches = allElements(root).filter((element) => matchesText(element.textContent, text) && !Array.from(element.children).some((child) => matchesText(child.textContent, text)));42  if (matches.length === 1) return matches[0];43  if (matches.length === 0) throw new Error('No element found with text "' + text + '".');44  throw new Error('Found ' + matches.length + ' elements with text "' + text + '".');45}46const user = {47  click(element) {48    element.focus?.();49    for (const type of ["mouseover", "mousemove", "mousedown", "mouseup", "click"]) {50      element.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));51    }52  },53  type(element, value) {54    element.focus();55    for (const char of value) {56      element.dispatchEvent(new KeyboardEvent("keydown", { key: char, bubbles: true }));57      element.value += char;58      element.dispatchEvent(new InputEvent("input", { data: char, bubbles: true, inputType: "insertText" }));59      element.dispatchEvent(new KeyboardEvent("keyup", { key: char, bubbles: true }));60    }61  },62};

The highlighted lines are the important parts:

• Line 8: accessibleName works out an element's name.
• Line 12: for a form field, the name comes from its label.
• Line 20: implicitRole works out the role from the tag, so a button tag has the role button.
• Line 34: getByRole keeps only the elements with the right role and name.
• Lines 47 and 53: user.click and user.type send the same events a real click or key press sends.

This is the small form that the tests use:

1function installGreetingApp(root, options = {}) {2  const labelMarkup = options.withLabel === false3    ? ""4    : '<label for="visitor-name">Name</label>';5  root.innerHTML = '<form id="greeting-form">'6    + labelMarkup7    + '<input id="visitor-name" type="text">'8    + '<button type="submit">Submit</button>'9    + '<p role="status" aria-live="polite"></p>'10    + '</form>';11 12  const form = root.querySelector("form");13  const input = root.querySelector("#visitor-name");14  const status = root.querySelector('[role="status"]');15  form.addEventListener("submit", (event) => {16    event.preventDefault();17    const name = input.value.trim() || "friend";18    status.textContent = "Thanks, " + name + "!";19  });20}

Line 4 adds the label Name. Line 8 adds the Submit button. Line 14 finds the status line, the paragraph that shows messages. When you submit, line 17 uses the typed name, or friend if the box is empty. Line 18 shows the message.

A query that should find one element must fail when it finds two. Two buttons both named Save are not one clear target. Either search inside one part of the page, or give the buttons different names.

document.querySelector("#app").innerHTML =
  '<button>Save</button><button>Save</button>';
try {
  getByRole(document, "button", { name: "Save" });
} catch (error) {
  console.log(error.message);
}

Lines 1 and 2 add two Save buttons. Line 4 asks for one button named Save. The helper finds two, so it throws. The catch prints Found 2 elements with role "button". The real Testing Library also throws when a one-element query finds more than one.

Now step through a full DOM test. It finds the text box, types a name, clicks Submit, and checks the message.

1installGreetingApp(document.querySelector("#app"));Run2const nameInput = getByRole(document, "textbox", { name: "Name" });3user.type(nameInput, "Ava");4const submit = getByRole(document, "button", { name: "Submit" });5user.click(submit);6console.log(getByText(document, "Thanks, Ava!").textContent);

Compare this with a CSS selector such as .signup input.primary. That selector still finds the input after its label is gone, so the test stays green. A role-and-name query fails as soon as the field loses its name. That failure is useful: the field has also lost its name for screen-reader users. One test now checks both behavior and accessibility.

Run the test while the label is there. Then remove the label and run it again. The input is still on the page, but the test can no longer find a text box named Name. A real user has the same problem: the field has lost its name.

1installGreetingApp(document.querySelector("#app"));2const nameInput = getByRole(document, "textbox", { name: "Name" });3user.type(nameInput, "Ava");4const submit = getByRole(document, "button", { name: "Submit" });5user.click(submit);6console.log(getByText(document, "Thanks, Ava!").textContent);

Before you submit, the status line is on the page but holds no message. The check below prints true.

installGreetingApp(document.querySelector("#app"));
const status = document.querySelector('[role="status"]');
console.log(status.textContent === "");

Line 1 builds the form. Line 2 finds its status line. Line 3 checks that its text is empty.

Two notes about messages that change later:

• If a message appears after some waiting, use Testing Library's findByRole or Playwright's toHaveText. Do not pause for a fixed time and hope.
• queryBy* checks only this moment. If a message must disappear later, use Testing Library's waitForElementToBeRemoved, which waits until it is gone.

installGreetingApp(document.querySelector("#app"));
user.click(getByRole(document, "button", { name: "Submit" }));
console.log(getByText(document, "Thanks, friend!").textContent);

Line 2 clicks Submit without typing. The form uses friend when the box is empty, so line 3 prints Thanks, friend!. This checks a different path from the step-through, where the user typed Ava.

installGreetingApp(document.querySelector("#app"));
document.querySelector("label").remove();
getByRole(document, "textbox", { name: "Name" });

Line 2 removes the label. Line 3 looks for a text box named Name. There is none, so it throws No element found with role "textbox" and name "Name".

installGreetingApp(document.querySelector("#app"), { withLabel: false });
document.querySelector("#visitor-name").setAttribute("aria-label", "Name");
console.log(getByRole(document, "textbox", { name: "Name" }).id);

Line 1 builds the form without a label. Line 2 gives the input a name with aria-label, an attribute that names an element for screen readers. Line 3 uses the same query as before and prints visitor-name.

A visible label is usually better than aria-label here. People who can see the page also need to know what the field is for.

Our tiny user helper is much simpler than the real user-event. Here is how the real tools differ:

• user-event acts out a whole action, the way a person does it. It also checks that the element can really be used, for example that it is not disabled.
• fireEvent sends exactly one event, such as one click event, and nothing else.

Use user-event first. Use fireEvent only when you need to test what happens for one exact event.

Playwright is a tool that controls a real browser from your code. It can open pages, type, click, and read what is on the screen.

It has three main ideas:

• A locator, such as page.getByRole("button"), describes how to find an element. Playwright looks for the element each time you use the locator. So it still works after the page redraws that element.
• An action, such as click(), waits until the element is visible and turned on before it acts.
• An assertion checks a result. A web-first assertion such as toHaveText checks again and again until the text matches, or until time runs out.

A locator on its own checks nothing. Only an assertion makes the test pass or fail.

// Node script. This repository has playwright-core, not @playwright/test.
import { chromium } from "playwright-core";

const browser = await chromium.launch({ channel: "chrome", headless: true });
const page = await browser.newPage();
await page.setContent(`<form>
  <label for="city">City</label>
  <input id="city">
  <button type="submit">Search</button>
  <p role="status"></p>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (event) => {
    event.preventDefault();
    document.querySelector("[role=status]").textContent =
      "Searching for " + document.querySelector("#city").value;
  });
</script>`);

await page.getByRole("textbox", { name: "City" }).fill("Pune");
await page.getByRole("button", { name: "Search" }).click();
console.log(await page.getByRole("status").textContent());
await browser.close();

Here is what the script does:

• Line 4 starts Chrome without a visible window.
• Line 5 opens a new page.
• Line 6 fills the page with a small search form. The setContent method puts this HTML into the page directly.
• Line 20 finds the text box named City and types Pune.
• Line 21 finds the Search button and clicks it.
• Line 22 reads the status line and prints Searching for Pune.

This project installs playwright-core, the part of Playwright that controls browsers. So the lesson test runs this exact script in Chrome. It does not install @playwright/test, Playwright's own test runner. So the runner example below is for reading only.

In a real app, open your page with page.goto instead of setContent. That also tests your page addresses and your server. The runner gives each test a fresh browser context, a clean set of cookies and storage. Data saved on your server is not reset for you, so reset it yourself or give each test its own data.

// Non-runnable here: @playwright/test is not installed in this lesson.
import { test, expect } from "@playwright/test";

test("searches by city", async ({ page }) => {
  await page.goto("/search");
  await page.getByRole("textbox", { name: "City" }).fill("Pune");
  await page.getByRole("button", { name: "Search" }).click();

  await expect(page.getByRole("status")).toHaveText("Searching for Pune");
});

Line 5 opens the search page. Lines 6 and 7 type and click, as before. Line 9 checks that the status line says Searching for Pune, and it keeps checking until it does.

CI (continuous integration) is a server that runs your tests every time code changes. This is a typical command for running Playwright tests there:

# Typical CI command when @playwright/test is installed
npx playwright test --trace on-first-retry

Tools such as axe-core and Lighthouse check a page against a list of rules. You can also run axe inside Playwright tests. These tools find many problems that follow a clear rule, such as an image with no description.

They cannot tell you:

• whether a task is easy to understand,
• whether the keyboard focus moves in a sensible order,
• whether a screen reader says the right thing at the right time.

No single score covers every app. Use the tools as an early warning. Then still try the page with a keyboard yourself.

Here is a tiny checker with three rules. It returns a list of issues, one sentence per problem.

1function checkBasicA11y(root) {2  const issues = [];3  for (const image of root.querySelectorAll("img")) {4    if (!image.hasAttribute("alt")) issues.push("Image is missing an alt attribute.");5  }6  for (const button of root.querySelectorAll("button")) {7    if (!accessibleName(button)) issues.push("Button has no accessible name.");8  }9  for (const input of root.querySelectorAll("input, textarea, select")) {10    if (["hidden", "button", "submit", "reset"].includes(input.type)) continue;11    if (!accessibleName(input)) issues.push("Input has no label or accessible name.");12  }13  return issues;14}

• Line 3 checks every image. An image needs an alt attribute, a short text that describes it.
• Line 6 checks every button. A button needs a name.
• Line 9 checks every form field. Line 11 adds an issue when the field has no label or other name.

1document.querySelector("#audit-fixture").innerHTML =Run2  '<img src="data:,"><button></button><input id="email">';3const issues = checkBasicA11y(document.querySelector("#audit-fixture"));4for (const issue of issues) console.log(issue);

1document.querySelector("#audit-fixture").innerHTML =2  '<img src="data:,"><button></button><input id="email">';3const issues = checkBasicA11y(document.querySelector("#audit-fixture"));4for (const issue of issues) console.log(issue);

document.querySelector("#audit-fixture").innerHTML =
  '<img src="data:," alt="Chart"><button aria-label="Close"></button><label for="email">Email</label><input id="email">';
console.log(checkBasicA11y(document.querySelector("#audit-fixture")).length);

Line 2 gives the image alt text, gives the button a name, and adds a label for the input. Line 3 counts the issues and prints 0.

0 means only that these three rules pass. It does not check color contrast, focus order, or whether Chart describes the image well.

People often draw the mix of tests as a shape:

• The testing pyramid has many cheap unit tests at the bottom and only a few slow E2E tests at the top.
• The testing trophy puts more weight on the middle: tests where several pieces work together, such as DOM tests. Users care that the pieces work together.

Neither shape tells you an exact number of tests. A DOM test may catch a broken label sooner than an E2E test. But only a browser test can show that moving between pages or real layout works. Choose by what could go wrong and by how slow the test is.

1. Unit tests: fastest. They tell you least about the real browser.
2. DOM tests: fairly fast. They tell you a lot about how one part of the page behaves.
3. E2E tests: slowest. They tell you most about a whole task.
4. Accessibility checks by hand: slow, but you need a person to judge some things.

A flaky test passes on some runs and fails on others, even though the code did not change. The table below lists common causes in E2E tests. Read each row as: the cause, what goes wrong, and what to do instead.

Running a test again, or waiting longer, can hide a timing problem without fixing it. Here is a better plan for a checkout test that talks to a server:

• Wait until the receipt shows on the screen.
• Reset the test order before each run.
• To test one screen state, you can fake the server's reply.
• Keep at least one test that uses the real server. Otherwise an old fake reply can hide a server that has changed or broken.

Common misconceptions

• "If all E2E tests pass, the page is accessible." Passing tests show only that the steps and checks you wrote work. You still need to try the page with a keyboard and a screen reader.
• "jsdom is a browser." It is a pretend page that runs in Node.js. It does not work out layout or load new pages.
• "CSS selectors are more exact." They depend on how the page is built inside. Role and label queries check what users rely on, so they break only when users would notice.
• "Test IDs are not allowed." A test ID (a data-testid attribute) is fine when no role, label, or text fits. It should not be your first choice for buttons and fields.
• "More E2E tests always means more confidence." Too many slow, wide tests make you wait longer and fail at random more often. Cover the most important tasks on purpose.
• "Accessibility tools catch everything." They catch problems that follow a clear rule. They cannot judge what a person experiences.

The table below compares three tools that are easy to mix up. Read each row as a question, and each column as one tool's answer.

Key takeaways

• A DOM test should find and use the page the way a person does: by role, label, text, and real events.
• jsdom is fast and useful, but it cannot check layout, page loading, or differences between browsers. Use a real browser for those.
• Playwright actions wait until an element can be used. Web-first assertions keep checking until the page shows what you expect.
• Accessibility tools catch problems that follow a clear rule. Checking by hand with a keyboard and a screen reader catches the rest.
• Use the smallest kind of test that can catch the problem. Save E2E tests for the most important tasks.

One-line summary: Test the page through what users rely on (roles, labels, and text), then use a real browser and a person for what a pretend page cannot see.

Up next: Advanced debugging. There, a failing test becomes your starting point for breakpoints, logpoints, traces, and tracking down async bugs.