← React / TypeScript

React / TypeScript · 23 / 24

Test user workflows with Playwright

Verify input, persistence and reopening through a real browser.

  • Large
  • Advanced
  • 90 min

Prerequisites: First React app: JSX, props and state, Test components and repositories meaningfully

In this tutorial
  1. Understand the state model
  2. Start the project
  3. Verify the contract with a test
  4. Observe failures and boundaries
  5. Implement the exercise
  6. Verify the solution
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

Node.js 22.23 or newer with npm. Python 3 is also required for the common verification entry point. Extract the learning package into a new folder and run python3 run_checks.py there. The script copies the included files into a temporary learning directory. It verifies the example and then the supplied solution there, preserving the original files. Required packages are downloaded on the first run.

Playwright downloads Chromium. A fresh Linux system may also require browser system libraries. The launcher reports missing libraries explicitly.

Verified on 2026-10-20 on Linux x86_64. Check empty input, successful saving and reloading. The solution adds a failed storage write. Wait for visible states instead of a fixed arbitrary delay.

A complete workflow checks several boundaries together. Here an interaction crosses form validation and local persistence. Reload must show the same confirmed record. Playwright creates an isolated browser context for each test, preventing accidental dependence on previous state.

Package contents and individual files

01Understand the state model

A browser test describes user actions through visible roles and labels. For the failure scenario the test deliberately makes the localStorage write fail. A failure must preserve input so the user can retry.

src/App.tsx · typescriptOpen file
import { useState } from "react";
function read(): string[] {
  const raw = localStorage.getItem("learning-vehicles");
  if (!raw) return [];
  try {
    const value: unknown = JSON.parse(raw);
    return Array.isArray(value) && value.every((x) => typeof x === "string")
      ? value
      : [];
  } catch {
    return [];
  }
}
export default function App() {
  const [rows, setRows] = useState<string[]>(read);
  const [error, setError] = useState("");
  return (
    <main>
      <h1>Vehicles</h1>
      <form
        onSubmit={(e) => {
          e.preventDefault();
          const form = e.currentTarget;
          const name = String(new FormData(form).get("name") ?? "").trim();
          if (!name) {
            setError("Name required");
            return;
          }
          try {
            const next = [...rows, name];
            localStorage.setItem("learning-vehicles", JSON.stringify(next));
            setRows(next);
            setError("");
            form.reset();
          } catch {
            setError("Cannot save");
          }
        }}
      >
        <label htmlFor="name">Vehicle name</label>
        <input id="name" name="name" />
        <button>Save</button>
        <p role="alert">{error}</p>
      </form>
      <ul>
        {rows.map((row, i) => (
          <li key={i}>{row}</li>
        ))}
      </ul>
    </main>
  );
}

02Start the project

Install the pinned dependencies and run npm run dev. Data consists of synthetic learning values. Open the local address and trigger the action yourself.

package.json · jsonOpen file
{
  "name": "appfabrik-learning",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "tsc --noEmit && vite build",
    "test": "playwright test"
  },
  "dependencies": {
    "react": "19.2.3",
    "react-dom": "19.2.3",
    "react-router-dom": "7.18.4",
    "@tanstack/react-query": "5.104.5"
  },
  "devDependencies": {
    "vite": "8.1.5",
    "typescript": "6.0.3",
    "@types/react": "19.2.14",
    "@types/react-dom": "19.2.3",
    "@types/node": "22.19.15",
    "vitest": "4.1.10",
    "@testing-library/react": "16.3.2",
    "@testing-library/user-event": "14.6.1",
    "jsdom": "29.1.1",
    "@playwright/test": "1.64.1"
  }
}

03Verify the contract with a test

Check empty input, successful saving and reloading. The solution adds a failed storage write. Wait for visible states instead of a fixed arbitrary delay.

tests/workflow.spec.ts · typescriptOpen file
import { test, expect } from "@playwright/test";
test("validated record survives reload", async ({ page }) => {
  await page.goto("/");
  await page.getByRole("button", { name: "Save" }).click();
  await expect(page.getByRole("alert")).toHaveText("Name required");
  await expect(page.getByRole("listitem")).toHaveCount(0);
  await page.getByLabel("Vehicle name").fill(" Family car ");
  await page.getByRole("button", { name: "Save" }).click();
  await expect(page.getByRole("listitem")).toHaveText(["Family car"]);
  await page.reload();
  await expect(page.getByRole("listitem")).toHaveText(["Family car"]);
});

Run / check

npm install
npm test
npm run build
Expected result

Check empty input, successful saving and reloading. The solution adds a failed response. Wait for visible states instead of a fixed arbitrary delay.

04Observe failures and boundaries

Change the expected output and observe a failed test. A TypeScript build protects type contracts while a browser test protects interactions. The two checks serve different purposes.

05Implement the exercise

Force a storage failure and verify draft and confirmed list remain correct.

06Verify the solution

The solution replaces setItem in the browser with a deliberate exception. The record must not appear in the confirmed list and the input must remain available for retry. Copy the solution files to the corresponding locations in the learning project and run tests and build again.

Expected result

Tests and type checking pass. The observed result matches the learning goal.

Your exercise

Force a storage failure and verify draft and confirmed list remain correct.

Show the solution and explanation

The solution replaces setItem in the browser with a deliberate exception. The record must not appear in the confirmed list and the input must remain available for retry.

solution/workflow.spec.ts · typescriptOpen file
import { test, expect } from "@playwright/test";
test("validated record survives reload", async ({ page }) => {
  await page.goto("/");
  await page.getByRole("button", { name: "Save" }).click();
  await expect(page.getByRole("alert")).toHaveText("Name required");
  await expect(page.getByRole("listitem")).toHaveCount(0);
  await page.getByLabel("Vehicle name").fill(" Family car ");
  await page.getByRole("button", { name: "Save" }).click();
  await expect(page.getByRole("listitem")).toHaveText(["Family car"]);
  await page.reload();
  await expect(page.getByRole("listitem")).toHaveText(["Family car"]);
});

test("failed storage preserves draft", async ({ page }) => {
  await page.goto("/");
  await page.evaluate(() => {
    Storage.prototype.setItem = () => {
      throw new DOMException("Full", "QuotaExceededError");
    };
  });
  await page.getByLabel("Vehicle name").fill("Draft");
  await page.getByRole("button", { name: "Save" }).click();
  await expect(page.getByRole("alert")).toHaveText("Cannot save");
  await expect(page.getByRole("listitem")).toHaveCount(0);
  await expect(page.getByLabel("Vehicle name")).toHaveValue("Draft");
});

Project context and sources

This independent learning project explores a topic in this technology area. Project references provide a pinned revision as architectural context. They do not imply that every library or feature introduced here is already used in that application.