DEV Community: Kevin Julián Martínez Escobar

Real-browser testing for Open Cells apps with TWD

Kevin Julián Martínez Escobar — Mon, 27 Jul 2026 08:39:38 +0000

Open Cells is an open-source framework from BBVA for building web apps out of Web Components. It leans on Lit, real Shadow DOM, a hash-based router, and channels for state. If you build with Cells, you are working with real custom elements the whole way down. That is what makes Cells apps feel solid. It is also what makes them interesting to test.

The usual Vite stack, and the gap

A Vite app usually reaches for two tools: Vitest for component tests and Playwright for end-to-end. Both are solid. For a Web Components app, each leaves a gap.

Vitest runs in Node against a simulated DOM. For custom elements that means rebuilding the parts that matter most: Shadow DOM, element upgrades, the router, browser storage. You spend your effort standing in for the browser instead of using it, and you test an approximation of your app.

Playwright drives a real browser, but a separate one, outside the tab you develop in. It shines for full end-to-end flows and is heavier for the everyday component check.

TWD offers a third place to test: the real browser, in a sidebar next to your app. Your Cells app renders exactly as it always does, and the tests run against it right there. Real DOM, real components with their Shadow DOM intact, real browser APIs. The only thing you replace is the network.

Not just Cells

TWD is framework-agnostic. It works with any client-rendered frontend: React, Vue, Angular, Solid, Lit and Open Cells, even HTMX or plain vanilla JavaScript. If your app renders in the browser, TWD tests it in the browser. Cells is simply where the real-browser approach pays off most, because Cells is Web Components all the way down.

Setup is small

Cells apps run on Vite, and TWD installs as a Vite plugin. Add it to the config and the TWD sidebar appears next to your app, discovering your tests. Nothing to wire into your entry file, nothing shipped to production.

The tests read like Testing Library: findByRole, findByText, a click. Anyone who has written a React Testing Library test already knows the shape.

Because the tests run in a real browser, browser APIs are real. localStorage, sessionStorage, cookies: no mocks, no shims. A feature that reads a saved preference or a stored session is tested against the browser actually doing it. When you need to cut the app off from the outside world, you mock the network, so a page that calls a backend runs against fixed responses and stays deterministic and offline.

Coverage, without changing the build

TWD also produces coverage. A coverage-only dev server instruments the app, the headless runner collects it, and you get a standard report. No change to how the app is built beyond that coverage serve. The same tests run in CI with one command, so what you write in the dev tab is what runs on every pull request.

Try it

For a framework built on Web Components, the real browser is the natural place to test. Cells gives you real custom elements. TWD lets you test them as they actually run.

TWD: twd.dev
Example repo (a Cells app tested with TWD): github.com/BRIKEV/twd-cells
Writing tests: twd.dev/writing-tests
API mocking: twd.dev/api-mocking
CI execution: twd.dev/ci-execution
Coverage: twd.dev/coverage

Testing HTMX apps in the real browser with TWD

Kevin Julián Martínez Escobar — Wed, 22 Jul 2026 20:48:23 +0000

HTMX apps are refreshingly simple: the server returns HTML fragments, and HTMX swaps them into the page in response to hx-get, hx-post, and friends. There is usually no bundler and no client framework. That simplicity is the point, and it is also why the usual testing tools feel wrong. A jsdom unit test cannot see an HTMX swap, and a full end-to-end runner is a lot of machinery to bolt onto an app that deliberately avoids machinery.

twd-js fits the HTMX model well. It runs tests inside the real browser, so it sees exactly what HTMX does to the DOM, and it installs from a CDN with an import map, so it adds no build step of its own.

Setup: load both from a CDN

Load HTMX as usual, then add an import map for TWD next to it. esm.sh resolves TWD's internal dependency, so there is nothing else to wire up.

<script src="https://unpkg.com/htmx.org@2.0.10/dist/htmx.min.js"></script>
<script type="importmap">
  {
    "imports": {
      "twd-js": "https://esm.sh/twd-js@1.8.2",
      "twd-js/runner": "https://esm.sh/twd-js@1.8.2/runner",
      "twd-js/bundled": "https://esm.sh/twd-js@1.8.2/bundled"
    }
  }
</script>

Your markup stays pure HTMX:

<button hx-get="/api/todos" hx-target="#todo-list" hx-swap="innerHTML">Load todos</button>
<ul id="todo-list"></ul>

Test against the real backend

The important design choice for HTMX is what to assert against. Because HTMX endpoints return HTML fragments rather than JSON, the cleanest approach is to run the tests against your real HTML-returning backend and reset it between tests, rather than mocking. This is the same pattern the Nuxt example uses for real-backend testing.

A tiny dev-only reset endpoint gives every test a clean starting point:

import { twd, userEvent, screenDom } from 'twd-js';
import { describe, it, beforeEach } from 'twd-js/runner';

describe('Todo List (HTMX)', () => {
  beforeEach(async () => {
    await fetch('/api/reset', { method: 'POST' });
  });

  it('loads the seeded todos', async () => {
    await twd.visit('/');

    const loadButton = await screenDom.getByRole('button', { name: 'Load todos' });
    await userEvent.click(loadButton);

    // HTMX swaps asynchronously, so use findBy* (which waits) rather than getBy*.
    const todo = await screenDom.findByText('Learn TWD');
    twd.should(todo, 'be.visible');
  });
});

The one detail worth internalizing: HTMX swaps happen after an async request, and there is no mock to await, so query with Testing Library's findBy* (which retries until the element appears) instead of the synchronous getBy*.

A note on mocking

TWD's service worker will happily intercept HTMX's requests, the same as any fetch or XHR. Today twd.mockRequest serializes responses as JSON, which is a natural fit for JSON APIs but not for HTML fragments, so for HTMX we recommend the real-backend approach above. First-class HTML-fragment mocking for hypermedia frameworks is on the roadmap.

Try it

A complete example, an HTMX todo list with load, create, and delete, a small Express backend with a reset endpoint, in-browser tests, and CI, lives in twd-htmx. It is served as static files with TWD loaded straight from the CDN, so you can read the whole thing top to bottom without a build step in sight.

Test your vanilla JS app in the real browser, with no build step

Kevin Julián Martínez Escobar — Wed, 22 Jul 2026 20:47:10 +0000

Not every app has a bundler. Plenty of real software is still a folder of HTML and JavaScript served as static files: internal tools, landing pages, small products, and anything deliberately kept simple. These apps ship and they matter, but their testing story is thin.

The usual options do not fit. Jest plus jsdom tests a fake DOM, so tests pass while the real page breaks. Playwright is a lot of stack, and its own runner, for an app whose whole appeal is that it has no stack. What is missing is something in between: real browser behavior, without a build step to earn it.

twd-js is that middle option. It runs your tests inside the real browser, in a sidebar next to your app, using Testing Library queries you already know. And because its bundled build is self-contained, you can load it from a CDN with an import map. No bundler, no npm install.

Setup: one import map

TWD's bundled entry ships everything it needs, and esm.sh resolves its internal dependency automatically. So the entire install is an import map in your HTML:

<script type="importmap">
  {
    "imports": {
      "twd-js": "https://esm.sh/twd-js@1.8.2",
      "twd-js/runner": "https://esm.sh/twd-js@1.8.2/runner",
      "twd-js/bundled": "https://esm.sh/twd-js@1.8.2/bundled"
    }
  }
</script>

Then boot TWD from your entry module. With no bundler there is no import.meta.glob, so you list your test files by hand: a label pointing at a lazy import of each one.

<script type="module">
  import { initTWD } from 'twd-js/bundled';

  if (location.hostname === 'localhost') {
    initTWD(
      {
        './tests/helloWorld.twd.js': () => import('/tests/helloWorld.twd.js'),
        './tests/todoList.twd.js': () => import('/tests/todoList.twd.js'),
      },
      { open: true, position: 'left', serviceWorker: true, serviceWorkerUrl: '/mock-sw.js' },
    );
  }
</script>

The localhost guard keeps TWD out of production. Wrap your app in a known root such as <div id="app"> so TWD's scoped queries know where to look.

The tests read like Testing Library

Test files import from the same bare specifiers the import map defines. If your team has ever written a Testing Library test, this is familiar:

import { twd, userEvent, screenDom } from 'twd-js';
import { describe, it } from 'twd-js/runner';

describe('Counter', () => {
  it('increments on click', async () => {
    await twd.visit('/');
    const button = await screenDom.getByText('Count is 0');
    await userEvent.click(button);
    twd.should(button, 'have.text', 'Count is 1');
  });
});

Mocking works too

TWD ships a mock service worker. The library loads from the CDN, but the service worker has to be served from your own origin, because browsers only register same-origin service workers. Run npx twd-js init public (or download mock-sw.js from the CDN) once, and API mocking works exactly like a bundled setup:

await twd.mockRequest('getTodos', {
  method: 'GET',
  url: '/api/todos',
  response: [{ id: '1', title: 'Learn TWD' }],
  status: 200,
});
await twd.visit('/todos');
await twd.waitForRequest('getTodos');

The part that pays off later

Here is the argument for starting with TWD even on a throwaway vanilla app: the tests are not tied to vanilla JS. They are Testing Library queries and TWD commands against the rendered DOM. The day you outgrow plain HTML and move the app to React, Vue, or Solid, the test files come with you unchanged. Only the setup changes: the import map becomes a devDependency and a Vite plugin.

That makes TWD a low-commitment way to add real tests now, and a migration you never have to redo. A working end-to-end example, counter and todo list, API mocking, and CI, lives in twd-vanillajs.

The easiest way to test a legacy Create React App

Kevin Julián Martínez Escobar — Tue, 14 Jul 2026 13:15:20 +0000

Create React App was officially deprecated in February 2025. The apps built with it didn't disappear. If you maintain one, you know the drill: the app works, it ships, and the Vite migration sits on the backlog behind everything that makes money.

The testing story is where that hurts. Your options look like Jest plus jsdom, where tests pass while the real page breaks, or bolting Playwright onto an app that's in maintenance mode. One is too far from the browser, the other is a lot of stack for an app nobody wants to invest in.

There's a third option. twd-js runs your tests inside the real browser, in the dev server you already have open, using Testing Library queries you already know. Every TWD guide assumes Vite, but the library doesn't care about your bundler. It works on CRA's Webpack with one block of code.

That's the TWD sidebar next to a CRA app. The tests drive the actual page: real DOM, real router, real fetch calls intercepted by a service worker.

Setup

Install the library and copy the mock service worker into public/:

npm install --save-dev twd-js
npx twd-js init public

Vite projects get a plugin that handles test discovery. On Webpack you wire it yourself with require.context in src/index.js:

if (process.env.NODE_ENV === "development") {
  // Webpack's version of import.meta.glob
  const context = require.context("./", true, /\.twd\.test\.ts$/);

  const testModules = {};
  context.keys().forEach((key) => {
    testModules[key] = async () => Promise.resolve(context(key));
  });

  const { initTWD } = await import('twd-js/bundled');

  initTWD(testModules, {
    open: true,
    search: true,
    serviceWorker: true,
    serviceWorkerUrl: '/mock-sw.js',
  });
}

The NODE_ENV guard keeps all of it out of the running production app.

One detail that surprised me: the test files are TypeScript (.twd.test.ts) inside a plain JavaScript CRA project, and that just works. CRA's Babel pipeline strips types without the typescript package installed. You don't get type checking on the tests, but they compile and run.

You already know the queries

TWD's screenDom wraps @testing-library/dom and its userEvent wraps the Testing Library user-event package. If your team writes Testing Library unit tests today, the tests read the same. The difference is where they run.

import { twd, userEvent, screenDom } from "twd-js";
import { describe, it } from "twd-js/runner";

describe("Hello World Page", () => {
  it("should display the welcome title and counter button", async () => {
    await twd.visit("/");

    const title = await screenDom.getByText("Welcome to TWD");
    twd.should(title, "be.visible");

    const counterButton = await screenDom.getByText("Count is 0");
    await userEvent.click(counterButton);
    twd.should(counterButton, "have.text", "Count is 1");
  });
});

Run npm start, open the app, and the sidebar lists your suites. Click one and watch it drive the page you're looking at.

Mocking the API

The service worker intercepts requests before they leave the browser, so tests are deterministic without a backend running (expect ships with twd-js, no chai install needed):

it("should create a todo", async () => {
  await twd.mockRequest("getTodoList", {
    method: "GET",
    url: "/api/todos",
    response: [],
    status: 200,
  });
  await twd.mockRequest("createTodo", {
    method: "POST",
    url: "/api/todos",
    response: { id: "1" },
    status: 200,
  });
  await twd.visit("/todos");

  await userEvent.type(await screenDom.getByLabelText("Title"), "Test Todo");
  await userEvent.type(await screenDom.getByLabelText("Description"), "Test Description");
  await userEvent.type(await screenDom.getByLabelText("Date"), "2024-12-20");
  await userEvent.click(await screenDom.getByRole("button", { name: "Create Todo" }));

  const rule = await twd.waitForRequest("createTodo");
  expect(rule.request).to.deep.equal({
    title: "Test Todo",
    description: "Test Description",
    date: "2024-12-20",
  });
});

That last assertion checks the exact body your form submitted. If someone renames a field in the payload, this fails in the sidebar while you're developing, not in QA.

Two gotchas (and the fixes)

CRA's tooling assumes every test file in src/ is a Jest test. TWD tests are not, so there are two collisions.

Jest picks up the TWD tests. react-scripts test matches *.twd.test.ts and tries to run browser tests in jsdom. Exclude them in the test script:

"test": "react-scripts test --testPathIgnorePatterns=src/twd-tests"

ESLint flags the assertions. The react-app/jest preset reports TWD's chai-style expect(...).to.deep.equal(...) as jest/valid-expect errors, and CRA surfaces them as compile errors in the dev server. Relax the rules for TWD test files only:

"eslintConfig": {
  "extends": ["react-app", "react-app/jest"],
  "overrides": [
    {
      "files": ["src/twd-tests/**/*", "**/*.twd.test.*"],
      "settings": {
        "testing-library/utils-module": "off",
        "testing-library/custom-renders": "off",
        "testing-library/custom-queries": "off"
      },
      "rules": {
        "jest/valid-expect": "off",
        "jest/valid-expect-in-promise": "off"
      }
    }
  ]
}

Everything stays strict for your regular Jest tests.

CI in one job

The same tests run headlessly with twd-cli, a Puppeteer-based runner. After the usual checkout and npm ci, the whole job is: start the dev server, run the CLI.

- name: Start CRA dev server
  run: |
    nohup npm start > cra.log 2>&1 &
    npx wait-on http://localhost:3000
  env:
    CI: true
    BROWSER: none

- name: Run TWD tests
  uses: BRIKEV/twd-cli/.github/actions/run@main

The CLI can also validate every request mock against an OpenAPI spec, so your mocks can't silently drift from the real API. See contract testing if that's your kind of thing.

The whole thing is a repo

Everything above comes from a working example with green CI: twd-create-react-app. The CRA guide in the TWD docs covers the same steps.

When you finally migrate to Vite

Here's the payoff that outlasts the maintenance work. These tests are agnostic to your bundler. They drive the real DOM in a real browser, not your webpack config, so nothing in them is tied to CRA.

When the Vite migration finally gets prioritized, you don't rewrite the suite. You run it against the new build and confirm the app behaves exactly as before. TWD runs on Vite too, so the tests carry over untouched. The setup you added to survive on CRA is the setup that tells you the migration worked.

Your app might be legacy. Your tests don't have to be.

The Production Bug You Can't Reproduce by Clicking

Kevin Julián Martínez Escobar — Fri, 03 Jul 2026 11:40:59 +0000

A payment request showed up in production logs with country: "ROW" at the top level and billing_address.country: "FRA" inside the customer object. Two different countries in the same body. The frontend clearly sent it, but nobody could make it happen again.

Every team has a bug like this. The payload contradicts itself, the logs prove it happened, and no amount of clicking through the app reproduces it. That's usually the signature of a timing bug: something failed, or arrived late, at exactly the wrong moment.

Why Manual Testing Can't Touch It

We tried to reproduce it by hand first. No luck.

The reason is structural, not lack of effort. To trigger this bug you need one specific API call, the price recalculation that fires when the user changes country, to either fail or respond slowly, at the exact moment the user submits the payment. Manually, you have no lever for that:

You can't make the real backend fail once, on demand, for one request.
Browser devtools throttling is global and clumsy: it slows everything, not the one call you care about.
Even if you get lucky once, you can't do it twice. A repro you can't repeat is not a repro.

So the bug stays "unconfirmed", the ticket goes stale, and the payload keeps showing up in the logs every few weeks.

An Agent Reads Code, Not Screens

This is where the AI agent changed the approach. Instead of guessing from the outside, it read the code and found that the app keeps the country in two places: one in the billing form the user fills in, and one in app state, set when the page first loads. When the user picks a different country, the app fires a background request to update prices, and only when that request succeeds does the app state catch up with the form.

That gap between "the form changed" and "the app state caught up" is the whole bug. Two ways to fall into it, found in minutes:

The background request fails. The app state keeps the old country, the form shows the new one, and the pay button still works.
The user pays too fast. The payment is built before the background request comes back, so it still reads the old country.

Both are timing conditions. Both are exactly the kind of thing you can't produce by clicking. And both are trivial to express as TWD mocks, because in TWD the test controls the server's behavior per request.

The failure case is one mock:

await twd.mockRequest("recalcFail", {
    url: "/api/pricing/quote",
    method: "POST",
    status: 500,
    response: { message: "recalculation failed" },
});

await selectBillingCountry("France");
await twd.waitForRequest("recalcFail");

await clickSubmitPayment();
const rule = await twd.waitForRequest("createPayment");

// The exact payload from the production logs
expect(rule.request.country).to.equal("ROW");
expect(rule.request.customer.billing_address.country).to.equal("FRA");

Note the assertion: twd.waitForRequest returns the intercepted body, so the test checks what the app actually sent over the wire, not what the UI displayed.

Reproducing the Race with a Delayed Mock

The second path needs timing control: the recalculation must succeed, but slowly. TWD mocks accept a delay, so the service worker holds the response while the test keeps going:

await twd.mockRequest("recalcSlow", {
    url: "/api/pricing/quote",
    method: "POST",
    status: 200,
    response: cartResponse,
    delay: 3000,
});

await selectBillingCountry("France");
await clickSubmitPayment(); // pay before the recalculation lands

const rule = await twd.waitForRequest("createPayment");
expect(rule.request.country).to.equal("ROW"); // stale, the store never updated

No setTimeout in the test, no flaky sleep, no real backend behaving badly on cue. The race is deterministic because the delay is part of the mock definition. The condition we could never hit manually now reproduces on every single run.

Both tests passed on the first attempt. Weeks of "cannot reproduce" closed in one session.

What Made the Difference

Two things, and neither is magic:

The agent reads code. A human reproducing a bug works from the UI inward and has to guess where the timing window is. An agent works from the code outward: it finds the store, the sync mechanism, and the gaps, then writes tests that target them directly.
The mock layer makes timing a test input. Failures and delays are declared per request, in the test file, running against your real app in the browser. That turns "race condition" from something you hope to catch into something you specify.

The whole loop ran through twd-relay, which drives the browser tab you already have open, so every repro attempt was visible as it executed. After the fix, the same two tests stayed in the suite as regression coverage.

If you have a ticket that says "cannot reproduce" and a log line that says otherwise, this combination is worth trying: let the agent read the code and put the timing in a mock.

Automated Accessibility Testing: axe-core, Keyboard Navigation, and WCAG in the Browser

Kevin Julián Martínez Escobar — Mon, 22 Jun 2026 21:02:04 +0000

Automated accessibility testing usually means one thing: point a scanner at the page, let it check the initial HTML against a set of WCAG rules, and turn green. Missing alt text, an unlabeled input, low-contrast text at load. Caught. Done.

Then a user opens the menu, submits the empty form, expands the accordion, and lands in a state your scanner never saw. The newly revealed panel steals focus and never gives it back. The modal traps a keyboard user with no way out. None of that exists in the first render, so none of it was tested.

That is the gap this post is about. Accessibility is not a property of a page, it is a property of every state a page can reach, and most of those states only exist after someone interacts. The fix is to run your accessibility checks in a real browser, after the interaction, with two complementary tools: axe-core for WCAG rule checks, and keyboard navigation tests for focus order. This walks through both.

The gap: accessibility tests that run in jsdom

The default setup runs your tests in jsdom. Render a component with Testing Library, run axe-core over it with jest-axe or vitest-axe, assert no violations. It is fast, and it is fine for catching the obvious stuff: a button with no accessible name, an input with no label, a misused ARIA attribute.

It also has a hard ceiling. jsdom does no layout and no rendering, so any check that depends on what actually paints on screen cannot run there. axe-core's color-contrast rule is the clearest example: in jsdom it comes back as "incomplete," not pass or fail, because there is nothing to measure. And that is before you get to anything interactive.

What it cannot tell you:

Whether focus moves somewhere sensible after a dialog opens, and comes back when it closes.
Whether the validation summary that renders after a failed submit is actually announced and reachable.
Whether your tab order matches the visual order once a section expands.
Whether a custom component announces its name, role, and state to a screen reader after it changes.

These are not edge cases. They are where most real accessibility complaints come from. And they all depend on layout, focus, and event behavior that jsdom only approximates. To test them you need the real thing: a real browser, real focus, real events.

That is the part TWD is built for. Tests run inside the actual browser, against your real app, and you drive them the way a user would. Which means you can scan accessibility after the interaction, not just before it.

Approach 1: axe-core, scanned after the interaction

axe-core is the engine behind most accessibility tooling. It is excellent at the rule-based checks: contrast, names, roles, ARIA misuse. The trick is not running axe. The trick is running it against the state that matters.

A small helper turns axe results into a readable failure instead of a wall of JSON:

import axe from "axe-core";

type AxeResults = import("axe-core").AxeResults;
type RunOptions = import("axe-core").RunOptions;
type ElementContext = import("axe-core").ElementContext;

/**
 * Run axe-core against the page (or a scoped element) and throw a
 * formatted error if there are any accessibility violations.
 */
export async function checkA11y(
  context?: ElementContext,
  options?: RunOptions
): Promise<AxeResults> {
  const results = await axe.run(context ?? document, options);

  if (results.violations.length) {
    const report = results.violations
      .map((v, i) => `${i + 1}. [${v.impact ?? "n/a"}] ${v.id}: ${v.help}\n   ${v.helpUrl}`)
      .join("\n\n");
    throw new Error(
      `Found ${results.violations.length} accessibility violation(s):\n\n${report}`
    );
  }

  return results;
}

A baseline scan of the page that loads is the easy case:

import { twd, userEvent, screenDom } from "twd-js";
import { describe, it, beforeEach } from "twd-js/runner";
import { checkA11y } from "./helpers/axe";

// Only WCAG 2.0/2.1 A & AA rules. Skips axe "best-practice" rules
// (region, landmark-one-main, ...) which are recommendations, not failures.
const WCAG = {
  runOnly: {
    type: "tag" as const,
    values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"],
  },
};

describe("Accessibility", () => {
  beforeEach(() => {
    twd.clearRequestMockRules();
  });

  it("should have no WCAG 2 A/AA violations on the home page", async () => {
    await twd.visit("/");
    await checkA11y(document, WCAG);
  });
});

That is the part every tool can do. Here is the part that needs a real browser and a real interaction: scanning a state that only exists after the user does something.

it("should stay accessible after form validation errors render", async () => {
  await twd.mockRequest("getTodoList", {
    method: "GET",
    url: "/api/todos",
    response: [],
    status: 200,
  });
  await twd.visit("/todos");
  await twd.waitForRequest("getTodoList");

  // Submit the empty form to force the validation error messages to render.
  const submitButton = await screenDom.findByRole("button", { name: "Create Todo" });
  await userEvent.click(submitButton);

  // Confirm the new dynamic content actually appeared before scanning.
  const error = await screenDom.findByText("Title is required");
  twd.should(error, "be.visible");

  // Scope the scan to just the form so the report is about this component.
  const form = await screenDom.findByTestId("todo-form");
  await checkA11y(form, WCAG);
});

The error messages in that test do not exist in the initial HTML. They render after a failed submit. A static scan never reaches them, so it never checks whether they are associated with their fields, announced, or reachable. Driving the interaction first, then scoping the scan to the form, checks the state a user actually lands in.

Scoping matters too. Passing the form element instead of document keeps the report about the component you just exercised, rather than re-flagging everything else on the page.

Approach 2: keyboard navigation and focus order

axe will not tell you whether your tab order makes sense. It cannot. Whether Tab moves through controls in an order that matches the visual flow, whether focus is visible, whether a control is even reachable by keyboard: that is behavior, and you have to drive it.

Because TWD tests run in the real browser, userEvent drives real focus. So you can walk the page the way a keyboard user does and assert where focus lands at each step.

it("keyboard navigation should work", async () => {
  await twd.visit("/chat");

  const user = userEvent.setup();

  // Tab from the top of the page. First stop should be the back link.
  await user.tab();
  const backToLanding = screenDom.getByRole("link", { name: "← Back to Landing" });
  twd.should(backToLanding, "be.focused");

  // Tab again. Focus should land on the prompt input, and typing should work.
  await user.tab();
  await user.keyboard("write some text");
  const textarea = screenDom.getByLabelText("Main prompt input (required)");
  twd.should(textarea, "have.text", "write some text");
});

This is a deterministic check of two things a scanner cannot see: the focus order is correct (back link, then input), and the input is reachable and usable by keyboard alone. If someone later drops a non-focusable div with a click handler into the flow, or reorders the DOM so tab order no longer matches the layout, this test fails. You find out in the run, not from a user report.

You can extend the same pattern to the cases that bite hardest: open a dialog and assert focus moved into it, close it and assert focus returned to the trigger, tab to the end of a menu and assert it does not escape into the page behind it.

Watch out with automated accessibility testing

Automated accessibility testing has a ceiling. Rule-based tools catch roughly a third of WCAG issues. axe is very good inside that third, and driving the interaction first stretches it to states a load-time scan cannot reach, but it is still a third. The rest needs a human: real screen reader testing, and judgment about whether labels, content order, and motion actually make sense.

So treat this as the regression net, not the whole strategy. It is the part you can run on every change, in CI, that stops obvious and post-interaction failures from sliding back in between manual audits.

Why this matters to us

We build the tool this runs on, twd-js, and we treat its own accessibility as a first-class requirement, not a nice-to-have. A tool whose entire job is to help people ship correct software has no business locking anyone out of using it. So the sidebar UI is fully keyboard navigable with a logical focus order and no traps, the focus indicator is visible in both light and dark themes, and text and controls meet WCAG contrast ratios. We had it audited by an external accessibility consultancy against WCAG 2.2 Level AA, and it came back at full conformance. You can read the accessibility statement for the full scope and methodology.

Try it

Both approaches are just tests, running in your real app, in a real browser:

npm install twd-js

Docs: twd.dev
The axe-core helper and the validation-state example live in the tutorial repo
Source and issues: github.com/BRIKEV/twd

Point a scan at the page that loads if you want a baseline. Then write the one that clicks the button first. That second test is the one your users were waiting for.

In-Browser Testing: Vitest Browser Mode and TWD, Side by Side

Kevin Julián Martínez Escobar — Sun, 14 Jun 2026 17:13:47 +0000

Testing components in a simulated DOM (jsdom, happy-dom) has always felt like a compromise. What we actually want is tests that run in a real browser. So when Vitest Browser Mode shipped, I was genuinely excited to try it.

I co-maintain TWD (Testing While Developing), an open-source tool built around in-browser testing, so I'm not a neutral party here. But the point isn't to declare a winner. It's to notice what each tool feels like to live with, where each one is clearly strong, and which scope each is really built for. I pointed both at the same TODO app for a working session: user flows, routing, network mocking. Here's the honest read.

1. Setup

The first difference shows up before you write a line of code.

Vitest Browser Mode asks you to make a few choices up front: your framework, and a browser provider (Playwright or WebdriverIO) that becomes a dependency in your repo. It makes sense for what it is, a runner that has to drive a real browser engine, but it's a layer you set up and keep around.

TWD's in-browser side is one package plus a single command to drop the service worker into your public directory:

npm install --save-dev twd-js
npx twd-js init public --save

That's the whole setup to start writing tests. Different shapes for different goals: Vitest sets up its own browser-driving layer, while TWD installs into the dev environment you already have.

2. The standalone runner

Boot up Vitest Browser Mode and you get a dedicated standalone server with a dashboard: a sidebar, runner reports, code views, even mobile responsive toggles.

It's also young, and a couple of rough edges show that:

Accessibility. Some contrast issues, and the test navigation tree doesn't have interactive controls yet to collapse or expand sections. The kind of thing that tends to get polished as a tool matures.

No clear live execution trace. You don't get a command-by-command log in the sidebar while a test runs, which is something I lean on in TWD.

It ships with an example, and the example is a standalone component. That fits the intent: the tool leans toward component testing, and it's good at it.

3. Component testing vs full app flows

This is where the scopes split, and I think it's the most useful thing to understand about the two tools. The Vitest Browser docs lean toward component testing, and that's the lane it's built for. When I went the other way and tried to render the full app to test a flow with routing, I had to bring more setup along:

Path aliases. If your app uses @/components/*, you replicate that bundler config so Vitest understands it.
Global styles. With Tailwind it's straightforward (setupFiles: ['./src/index.css']). With other CSS tooling it's more config to work out.

Here's the test I wrote for a counter button wrapped in a React Router provider:

import { expect, test } from 'vitest'
import { render } from 'vitest-browser-react'
import { RouterProvider } from 'react-router'
import router from '../src/AppRoutes'
import { userEvent } from 'vitest/browser'

test('renders name and increments count', async () => {
  const { getByText } = await render(
    <RouterProvider router={router} />
  )
  const title = getByText('Welcome to TWD')
  expect(title).toBeInTheDocument()

  const counterButton = getByText('Count is 0')
  expect(counterButton).toBeInTheDocument()

  await userEvent.click(counterButton)
})

Even for something this basic I sometimes had to restart the run to get the state to sync. None of this is a flaw so much as a sign of which job the tool is shaped around: these are small things on a TODO app, but they add up on a full app.

That's the core difference in approach. There's no separate "rendering" phase inside a sandbox wrapper with TWD. It injects into your already-running app and adapts to your project, rather than the project adapting to it.

4. Network mocking

This is the part that matters most to me, because in TWD we treat network interception as a pillar of frontend testing rather than an afterthought: you mock a request and own its response from the test.

Vitest Browser Mode leaves network mocking to you, by design. You have three routes:

Option	Level	Trade-off
MSW	Real network (service worker)	Most realistic. The request actually fires and you assert on bodies. Vitest officially recommends it for browser-mode mocking. More setup: worker file in `public/`, handlers.
`vi.mock('@/api/todos')`	Module	Simplest. Replace the API functions with fakes. But you bypass the HTTP client and the URL, so you're testing component plus router, not the contract.

MSW is the one I'd reach for, and the nice surprise is that it supports the test-owns-the-response pattern TWD's mockRequest gives you. worker.use() prepends a one-off handler that takes precedence, and an afterEach(() => worker.resetHandlers()) wipes it after each test, so nothing leaks:

import { http, HttpResponse } from 'msw'

test('shows empty state', async () => {
  worker.use(
    http.get('http://localhost:3001/api/todos', () => HttpResponse.json([]))
  )
  // render, assert "No todos yet"
})

You can keep zero defaults and have every test declare its own handler (closest to the TWD style), or keep in-memory defaults and override per test for edge cases. You can also capture await request.json() inside the handler and assert on it, mirroring a payload check.

So both styles are available. The difference is mostly where the work lives: MSW means standing up handlers as your own little backend, where in TWD that interception is built in. Contract testing sits in the same place: it's part of TWD out of the box, and in Vitest it's something you'd add on top.

5. CI and coverage

Both run well in CI. It depends mostly on the browser install step on your runner, and once that's set up execution is fast either way. twd-cli handles the headless side for TWD and isn't hard to wire up.

Coverage is the one spot where the defaults differ. Vitest reports it out of the box, while in TWD you add the Istanbul plugin. That's a little setup rather than a real obstacle, but the out-of-the-box default is a nice touch on Vitest's side.

Conclusion

Both tools earned their place by the end of the session. Just not in the same place.

Vitest Browser Mode is backed by a strong team and a large community, the terminal execution was genuinely good, and coverage comes for free. For component testing, a design system or a UI kit, try it: it's a real step up from testing components in a simulated DOM.

For a full production app driven by user flows, TWD is the one I reach for. The flow tests were possible in Vitest too, just with more setup along the way, and I'd rather stay in the tab I'm already developing in than switch to a separate browser window.

For TWD: testing isn't a separate phase you run after coding, it's part of development. That's the bias, stated plainly. If you're doing component work, Vitest Browser Mode is worth your time. If you're testing whole flows while you build, that's the lane TWD was made for.

The TWD is at twd.dev. The repo is at BRIKEV/twd.

Testing Nuxt apps in the real browser, against a real backend

Kevin Julián Martínez Escobar — Wed, 10 Jun 2026 17:47:18 +0000

You just built a Nuxt todo page. It loads from a Nitro route, adds a todo, deletes one, and it works when you click around. Now you want a test that proves it keeps working.

The usual answer is to leave the app, stand up a separate test stack, and rebuild the page in a fake environment with every route mocked. TWD takes the other path: test it where you already are, while you are still building it.

TWD runs your tests inside the Nuxt dev server, in the real browser tab where the app already runs. The same todo page gets tested end to end, against your real backend. No route mocks, no separate e2e stack, no jsdom.

Here is the full setup.

Setup

npm install --save-dev twd-js
npx twd-js init public --save

Add the Vite plugin in nuxt.config.ts:

import { twd } from 'twd-js/vite-plugin'

export default defineNuxtConfig({
  vite: {
    plugins: [
      twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}' }),
    ],
  },
})

Two Nuxt-specific bits to wire up, both one-time.

1. Inject the sidebar in app.vue

Nuxt does not serve a Vite index.html. Nitro renders the HTML, so the plugin cannot auto-inject its sidebar script. Point your app at the virtual module yourself, dev-only, in app.vue:

<script setup lang="ts">
if (import.meta.dev) {
  useHead({
    script: [{ src: '/_nuxt/@id/virtual:twd/init', type: 'module' }],
  })
}
</script>

<template>
  <div>
    <NuxtPage />
  </div>
</template>

Note the /_nuxt/ prefix, that is Nuxt's Vite base. The import.meta.dev guard keeps the tag out of production.

2. Reload the browser when a test file changes

On Nuxt 4 with Vite 7, editing a .twd.test file does not reload the browser on its own. This small plugin fixes it: it watches your test files and triggers a reload when one changes.

// npm install --save-dev chokidar
import chokidar from 'chokidar'
import type { Plugin } from 'vite'

function twdTestHmr(): Plugin {
  const isTestFile = (file: string) => /\.twd\.test\.tsx?$/.test(file)
  return {
    name: 'twd-test-hmr',
    apply: 'serve',
    configureServer(server) {
      // Under Nuxt, Vite's config.root is the app/ srcDir, where the tests live.
      const watcher = chokidar.watch(server.config.root, {
        ignored: (path) => /node_modules|\.nuxt|\.output|\.git/.test(path),
        ignoreInitial: true,
      })
      const reload = (file: string) => {
        if (!isTestFile(file)) return
        // Drop the cached module so the reload serves fresh code.
        const graph = server.environments?.client?.moduleGraph ?? server.moduleGraph
        for (const mod of graph.getModulesByFile(file) ?? []) {
          graph.invalidateModule(mod)
        }
        server.ws.send({ type: 'full-reload', path: '*' })
      }
      watcher.on('change', reload).on('add', reload).on('unlink', reload)
      server.httpServer?.once('close', () => void watcher.close())
    },
  }
}

Add twdTestHmr() to the plugins array next to twd(). Edit a test, the browser reloads.

Run npm run dev. Sidebar on the left, your app on the right.

Testing against the real backend

You do not mock routes. The tests hit your dev server and your database for real. The only thing you need is a clean starting point for each test.

A dev-only endpoint gives you that. It resets the database to a seeded baseline, guarded so it never exists in production:

// server/api/__test/reset.post.ts
export default defineEventHandler(() => {
  if (!import.meta.dev) {
    throw createError({ statusCode: 404, statusMessage: 'Not found' })
  }
  resetDb()
  return { ok: true, todos: listTodos() }
})

resetDb() deletes every row, resets the id sequence so seeded ids are deterministic, and re-seeds. The import.meta.dev guard means the route returns 404 in a production build.

Call it before each test, then drive the real UI:

import { twd, userEvent, screenDom } from 'twd-js'
import { describe, it, beforeEach } from 'twd-js/runner'

describe('Todos (real SQLite backend)', () => {
  beforeEach(async () => {
    // Reset the database to its seeded state. No route mocking.
    await fetch('/api/__test/reset', { method: 'POST' })
  })

  it('creates a todo end to end', async () => {
    await twd.visit('/todos')
    await userEvent.type(screenDom.getByTestId('todo-input'), 'Buy milk')
    await userEvent.click(screenDom.getByTestId('todo-add'))

    twd.should(await screenDom.findByText('Buy milk'), 'be.visible')
  })
})

No mock rules. The POST persists to the database, the list refreshes, and the assertion runs against the real rendered DOM. Delete a row and assert it is gone, same shape. When a test fails, it failed against the real backend, not against a mock you forgot to update.

Try it

Sample repo: BRIKEV/twd-nuxt-example. Nuxt 4, a SQLite-backed todo list, the HMR plugin, the dev-only reset endpoint, and tests that run against the real backend.
Docs: twd.dev

npm install --save-dev twd-js
npx twd-js init public --save

Add the plugin to nuxt.config.ts, drop the dev-only script into app.vue, add the HMR plugin, write your first .twd.test.ts. The sidebar opens itself.

Playwright vs TWD: A Frontend Developer's Honest Comparison

Kevin Julián Martínez Escobar — Thu, 21 May 2026 15:09:23 +0000

I had both Playwright and TWD pointed at the same small app for a working day. Same backend, same UI, the same bugs to chase. The point wasn't to declare a winner. It was to notice what each one feels like to live with, especially when an AI agent is in the loop too.

Two different rhythms. Different things they make easy. Different things they make slower. One of them I ended up reaching for much more often.

The first thing you notice: where the tests live

Playwright spawns its own browser. A separate window, a separate context, a separate world. You write tests in Node, run them, watch them happen in a window you can look at but not really use.

TWD lives in the tab you're already developing in. The sidebar sits on top of your app while you work. Click run on a test, the test drives the same page you were just clicking around on, then hands it back to you. You can keep using the app.

That single difference shapes most of what comes after. When you can keep using the app while tests run, you reach for them more often. When tests take you out of the app to another window, you reach less.

The feedback loop

Inside TWD, the cycle is short: write a line, save, click run, watch. If something fails, the failure shows up next to the code that produced it. You're never out of the dev tab.

Playwright's loop is longer in feel, even when the run itself is fast. There's a separate browser, a terminal, a report, sometimes a trace viewer. Each piece is fine on its own. Together they add up to context-switching cost.

It isn't that one runs in CI and the other doesn't. Both have a headless CLI runner. Both are fine in CI. The difference is which side of the day each one is designed around. TWD is shaped for the inside of a dev session and treats CI as the export target. Playwright is shaped for the run-the-whole-thing pass and treats local dev as a smaller slice of that.

The debugging story (and why it matters more now)

Both runners are good at telling you why something failed. They tell you in different shapes.

When a TWD test fails, the error is usually about something specific. "Couldn't find this label." "The request payload didn't match." "This element wasn't visible." It's the vocabulary you used to write the test, applied to what just happened. The diagnosis is the test reading itself back to you, in a sentence or two.

When a Playwright test fails, you get richer artifacts. Screenshots, traces, a structured dump of the accessibility tree. The diagnosis is forensic. It's good at telling you what the browser looked like just before things went wrong.

That forensic detail has a cost that didn't matter much when humans were the only audience. Now that the audience is often an AI agent reading test output as part of a session, the cost shows up. A single Playwright failure can drop kilobytes of locator HTML, class lists, and page snapshots into the context window. The agent reads all of it. The token bill scales accordingly. On a long debugging loop where the agent runs the suite, reads the failure, edits a file, runs the suite again, that footprint stacks up fast.

TWD's failures are one-liners. The label name. The payload diff. The selector that didn't match. Cheap to read, cheap for an agent to act on, almost always enough to point at the line that broke.

If your debugging loop involves an LLM in any way, the per-error footprint stops being a stylistic preference and starts being a budget line.

What you get without having to build it

This is where the gap shows up the most.

TWD ships with coverage. Run the headless runner and you get a report. It also ships with contract testing: every mock you write gets validated against your OpenAPI spec on every run. You don't wire it up. It just runs.

Playwright's job is testing. Coverage and contract testing aren't part of that job by design. You can add them. There are packages and recipes for both. None of it is hard, but none of it is free either. You write fixtures, capture data, post-process the output, integrate with reporters. The work isn't huge, but it's the kind of work that quietly gets deprioritized.

This isn't a knock on Playwright. It's a question of which tool defines its scope to include the surrounding tooling, and which one stays narrow on purpose.

How they actually compose

The clean answer for choosing Playwright is real cross-browser. If your app has to work identically across Chromium, Firefox, and WebKit, Playwright gives you that natively. TWD runs in whichever browser you're developing in, one engine at a time. That's the lane. It's a real one. Most apps don't actually live in it, though.

But the framing that earned the most ground for me during the session wasn't "pick one." It was layering them.

TWD on the inside. Every day. The tab you're already developing in. Component mocks, network mocks, fast feedback. Coverage and contract testing carried into CI as part of the same stack.
Playwright at the gate. A small set of true black-box smokes that run in real Chromium, Firefox, and WebKit before a deploy. Login flow, checkout, anything that has to behave identically across engines. Half a dozen tests at most.

Most teams don't need 200 Playwright tests. They need 200 TWD tests and 6 Playwright tests. The math gets cheaper, the dev loop stays fast, and the cross-browser worry stays answered.

That's the stack worth running, if you're going to run both.

What the session left me with

Both tools earned their place by the end. Just not in the same place.

TWD was the right hand for everything I wrote and rewrote during the session: tests in the dev tab, instant feedback, errors short enough to read at a glance. The headless mode brought coverage and contract checks into CI without a separate setup. That's a lot of testing surface from one config.

Playwright was the right hand for the cross-engine question. Not for every spec. For the small set that has to behave identically across browsers.

Two tools, two scopes, one healthy boundary between them. That's the shape of it.

The TWD runner is at twd.dev. The repo is at BRIKEV/twd-docs-tutorial.

Frontend with AI: workflow first, agent second

Kevin Julián Martínez Escobar — Sun, 17 May 2026 17:24:45 +0000

If you're about to plug AI into your team's frontend, define the process before you let it loose. Without a workflow, what gets faster isn't delivery. It's technical debt.

At Orbitant we run a development consultancy, and we've spent months refining a concrete workflow for integrating AI into the day-to-day of the frontend teams we work with, adapting it to each client's stack and constraints. The idea isn't new, but the nuance matters: AI only amplifies what your team already does. If you already had a quality process, speed goes up and quality holds. If not, what goes up is the amount of code without tests, without context, and without review.

That was the starting point.

The problem: AI amplifies what you already have

Before AI was part of the flow, in any tight sprint the usual story played out: focus on the happy path, push tests to next week, close the ticket. AI didn't change that. It sharpened it. More code per hour meant more uncovered paths, more untested components, more silent decisions nobody was going to review.

A team figures this out fast. The problem isn't the tool. It's that there's no mandatory process the AI has to respect.

The proposal: define the workflow first

The opening rule is simple: if we take AI out of the picture, quality, relative speed, and regression control all have to stay exactly where they were. AI on top of a good process amplifies results. On top of a broken one, it amplifies problems.

So first you define the path. Then you build a Claude Code skill that orchestrates that path step by step. Everyone goes through the same hoop. With or without AI.

The piece that makes it click: TWD

A workflow like this only works if the tool running the tests also respects the process. TWD (Test While Developing) does exactly that: it runs the tests inside your own dev server, against the same DOM and the same mocks you're looking at right now in the browser. No simulations, no jsdom, no separate Chrome under the hood.

That fits with AI for a very specific reason: results come back as text. The agent reads whether the test passed or failed, reads the error if there is one, and retries. No heavy screenshots, no DOM dumps. The loop costs few tokens, so it's viable to repeat it hundreds of times a day without the bill exploding. And test quality goes up because the tests stop being "a component mounted in isolation". They become what the user is going to see in the real app, with its real components and real interactions.

The flow, phase by phase

It's six phases, but in practice it simplifies to four mental blocks:

Understand the ticket properly. Figma, screenshots, brainstorm if the feature is complex. The clearer the start, the better the implementation. The skill can pull from the Figma MCP when there's design, and break out into a separate brainstorm if the thing looks fuzzy.
RED → GREEN, non-negotiable. Tests come first, from the requirements. When a test fails, you fix the implementation, never the test. No guess-coding. If after three attempts a test is still red, mark it as it.skip with a TODO. Never silence.
TWD live loop. The part people like most when they see it for the first time. The agent sends tests to the browser tab you already have open: no separate Chrome, no new window, no simulated environment. Your tab, your app, your mocks. You watch the clicks, the forms, and the redirects happen in real time while the agent reads the results as text and decides the next step. (The technical piece connecting agent and browser is called twd-relay; details at twd.dev for anyone who wants them.)
Reviewer. Before closing, a subagent runs lint, build, and the full suite. If anything breaks, back into the loop. The feature isn't done until everything is green.

The bottleneck moves. From "writing code" to "deciding what you want and reviewing what comes out". Which is exactly where we want it.

The rules for structuring tests

The workflow is the kitchen; the rules are the recipe. These are the four non-negotiables that come up in any team conversation:

Test what you own, mock what you don't. Tests cover what you control. What you don't (third-party iframes, external SDKs, cross-origin widgets) gets mocked, documented as out of scope, and covered from the QA layer with real E2E or manual tests. It doesn't disappear, it gets tested somewhere else.
Flow-based tests, not element-based. Each it() covers a complete journey: visit, interact, assert the outcome. One test per element is noise, not signal.
Test first, code second. Non-negotiable, even when "it's just a small change". Small changes break the system; tests take minutes.
A test that passes without an implementation is suspect. Either it's testing pre-existing behavior (justify it) or it's testing nothing. Either way, look at it.

These rules didn't come from a manual. They came from looking at what broke in previous sprints and putting a brake at each point.

Closing

If your team is about to put AI into frontend, the real decision is this: what process do you want the AI to amplify?

An agent without a process is a developer in a hurry. An agent inside a workflow is a colleague that respects the same rules as the rest of the team. The difference shows up the first time a regression doesn't reach production.

Looked at from outside, this is harness engineering applied to a software process: the harness doesn't just call the model, it enforces a workflow the team already considered good before AI showed up.

first the failing test → then the most obvious implementation that passes

The easiest way to test React Router v7 apps

Kevin Julián Martínez Escobar — Sat, 16 May 2026 15:44:49 +0000

You wrote a React Router v7 route. It has a loader, an action, a form, some interactivity. Now you want to test it. The official docs hand you two paths and neither one covers the case you actually have.

Path one is createRoutesStub plus @testing-library/react, running in a terminal-based test runner. It works for small reusable components that consume router hooks. The docs explicitly warn against using it for full route components with the framework-mode Route.* types: "not designed for (and is arguably incompatible with) direct testing of Route components". So if you want to test the actual route the user is going to load, this path stops short.

Path two is Playwright or Cypress. The docs themselves point you there for route-level tests: "we recommend you do that via an Integration/E2E test... against a running application". That works, but you've left your dev loop, you've added a separate test stack, and the feedback cycle gets long. It's QA-shaped, not developer-shaped.

There's a middle path. Use the same createRoutesStub the docs recommend for components, but render it inside the real browser, in the real dev server, against the real DOM, with the dev loop still attached. That's what TWD does. The framework's own utility, in the right environment.

That's the TWD sidebar on the left, the app on the right. The sidebar is running real createRoutesStub tests against the live page. No jsdom, no headless Chrome, no separate process.

Setup

Install:

npm install --save-dev twd-js
npx twd-js init public --save

Add the Vite plugin:

// vite.config.ts
import { reactRouter } from '@react-router/dev/vite'
import { defineConfig } from 'vite'
import { twd } from 'twd-js/vite-plugin'

export default defineConfig({
  plugins: [
    reactRouter(),
    twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}' }),
  ],
})

There's one SSR-mode workaround you'll hit exactly once. React Router v7 framework mode does not use a Vite-served index.html. The framework's own middleware renders HTML from app/root.tsx, and Vite's transformIndexHtml hook never fires for that HTML. The plugin can't auto-inject its sidebar bootstrap script. The fix is one dev-only block in app/root.tsx:

<head>
  <Meta />
  <Links />
  {import.meta.env.DEV && (
    <script type="module" src="/@id/virtual:twd/init" />
  )}
</head>

The plugin still registers the virtual module. Vite still serves it at /@id/.... You're just pointing your SSR'd template at it yourself. The import.meta.env.DEV guard keeps the tag out of production.

Run npm run dev. Sidebar on the left, your app on the right.

A fallback `/testing` route

createRoutesStub builds a tiny in-memory router. To mount it, you need a DOM container and a React root. The cleanest way is a dedicated route that exists only as a mounting point for tests:

// app/routes/testing-page.tsx
export default function TestPage() {
  return <div data-testid="testing-page" style={{ minHeight: '100vh' }} />
}

Add it to your route table at /testing. Then a small utility navigates to it and hands you a fresh root in beforeEach:

// app/twd-tests/utils.ts
import { createRoot } from 'react-dom/client'
import { twd, screenDomGlobal } from 'twd-js'

let root: ReturnType<typeof createRoot> | undefined

export async function setupReactRoot() {
  if (root) { root.unmount(); root = undefined }
  await twd.visit('/testing')
  const container = await screenDomGlobal.findByTestId('testing-page')
  root = createRoot(container)
  return root
}

That's the whole harness. One route, seven lines of utility. The cost is small and you reuse it across every test.

Writing a route-level test

This is the test the official docs say not to write with createRoutesStub. In TWD it works, because the stub is rendering into the same real document your app lives in. Full Route.* types, full hooks, real DOM.

// app/twd-tests/todoList.twd.test.tsx
import { twd, expect, userEvent, screenDom } from 'twd-js'
import { describe, it, beforeEach } from 'twd-js/runner'
import {
  createRoutesStub,
  useLoaderData,
  useParams,
  useMatches,
} from 'react-router'
import TodoListPage from '~/routes/todolist'
import todoListMock from './mocks/todoList.json'
import { setupReactRoot } from './utils'

describe('Todo List page', () => {
  let root: Awaited<ReturnType<typeof setupReactRoot>>

  beforeEach(async () => {
    root = await setupReactRoot()
  })

  it('renders todos from the loader', async () => {
    const Stub = createRoutesStub([
      {
        path: '/',
        Component: () => {
          const loaderData = useLoaderData()
          const params = useParams()
          const matches = useMatches() as any
          return (
            <TodoListPage
              loaderData={loaderData}
              params={params}
              matches={matches}
            />
          )
        },
        loader() {
          return { todos: todoListMock }
        },
      },
    ])

    root.render(<Stub />)
    await twd.wait(300)

    const firstTodoTitle = await screenDom.getByText('Learn TWD')
    twd.should(firstTodoTitle, 'be.visible')

    const firstTodoDate = await screenDom.getByText('Date: 2024-12-20')
    twd.should(firstTodoDate, 'be.visible')
  })

  it('submits the create-todo action with the right payload', async () => {
    let payload: Record<string, string> | null = null
    const Stub = createRoutesStub([
      {
        path: '/todos',
        Component: /* same wrapper */ () => null,
        loader() { return { todos: [] } },
        async action({ request }) {
          const formData = await request.formData()
          payload = Object.fromEntries(formData) as Record<string, string>
          return null
        },
      },
    ])

    root.render(<Stub initialEntries={['/todos']} />)

    const titleInput = await screenDom.getByLabelText('Title')
    await userEvent.type(titleInput, 'Test Todo')

    const submitButton = await screenDom.getByRole('button', { name: 'Create Todo' })
    await userEvent.click(submitButton)

    expect(payload).to.deep.equal({ title: 'Test Todo' /* ... */ })
  })
})

The pattern is exactly the one the official docs show. The wrapper component pulls useLoaderData / useParams / useMatches and forwards them as props. The stub provides a loader and (optionally) an action. You render, you interact, you assert. The only difference from the docs example is where it runs.

Backend tests: any runner works

Framework mode splits the route in two: the loader and action are server-side, the component is client-side. The two halves get tested by different tools, and the backend half is the easier one.

loader and action are async functions that take a Request and a context. They have no DOM, no router, no rendering. Test them with whatever your project already uses: vitest, jest, node's built-in test runner, anything. Here it is in vitest as one example:

// app/routes/todolist.test.ts
import { describe, it, expect, vi } from 'vitest'
import { loader, action } from './todolist'
import * as api from '~/api/todos'

it('loader returns todos from the api layer', async () => {
  vi.spyOn(api, 'fetchTodos').mockResolvedValue([
    { id: '1', title: 'Learn TWD', description: '', date: '2024-12-20' },
  ])

  const result = await loader({
    request: new Request('http://test/todos'),
    params: {},
    context: new Map() as any,
  })

  expect(result.todos).toHaveLength(1)
})

Whatever runner you pick, the test boots in milliseconds and runs anywhere Node runs. It's a function call.

Two suites, one per layer. When the backend test fails, the loader broke. When the TWD test fails, the rendering broke. You stop debugging the wrong layer.

Why this works: same utility, different environment

createRoutesStub is a great piece of API. The official docs scope it to non-route components for a fair reason: mounting a full route component into jsdom is genuinely brittle, because framework-mode Route.* types, auto-imports, and the dev loop weren't built for a synthetic DOM. You can spend more time wrestling the harness than writing the test.

TWD changes one thing about that picture. The test runs inside your real Vite dev server, in the real browser tab where your app already runs. Auto-imports resolve. Types match runtime. The dev loop is still there. With the surrounding environment in place, the same createRoutesStub scales up to route-level components without fighting anything.

That change pulls a few extras along with it. The sidebar is part of your dev loop, not a separate thing you switch into. The same tab where you're building the page runs the tests. The DOM you're testing is the DOM you're using. Click around manually, run a test, watch the assertion render in real time, fix it, re-run. No context switch, no second window, no headless screenshot to interpret.

Try it

Sample repo: BRIKEV/twd-react-router. React Router v7 in framework mode, a todo list with loader and action, the harness route wired up, GitHub Actions CI configured against a json-server backend (the part most sample repos forget).
Docs: twd.dev

npm install --save-dev twd-js
npx twd-js init public --save

Add the plugin to vite.config.ts, drop the <script> tag into app/root.tsx, add the /testing route, write your first .twd.test.tsx. The sidebar opens itself.

Testing TanStack Router + Query apps in the real browser

Kevin Julián Martínez Escobar — Tue, 12 May 2026 21:35:12 +0000

The first time you try to test a TanStack app the way the React Testing Library docs suggest, the test file gets bigger than the component. You spin up a memory router, instantiate a new QueryClient per test, wrap everything in QueryClientProvider and RouterProvider, set up MSW handlers for every request the loader fires, and finally write three lines of actual assertion. The component renders against jsdom. Close to the real thing, but not it.

It works. It's also where a lot of people give up on testing TanStack apps and go straight to Playwright.

There's a middle ground: run the test inside the real app, against the real router, the real query client, the real component tree, and get the result back as plain text. That's what TWD does, and TanStack happens to be a particularly good fit, because everything TanStack provides is already wired up by the time your test runs.

This article walks through the actual setup against a TanStack Router + Query + Form sample app, the test patterns that emerge, and the one trap you'll hit if you don't know about it.

The setup is two Vite plugins

Install:

npm install --save-dev twd-js twd-relay
npx twd-js init public --save

Add the plugins to vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import { twd } from 'twd-js/vite-plugin'
import { twdRemote } from 'twd-relay/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
    react(),
    twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}', open: true, position: 'left' }),
    twdRemote(),
  ],
})

That's the whole integration. twd-js auto-discovers *.twd.test.ts files, mounts a sidebar inside your real app, and registers a service worker for network mocking. twd-relay attaches a WebSocket to the Vite dev server (the AI part, more on that below). Both plugins use apply: 'serve', so production builds are untouched.

Run npm run dev. The sidebar appears on the left. Your TanStack app is on the right.

Writing a test

A .twd.test.ts file runs in the same browser tab as your app. It can import anything your app imports.

Here's the full counter test from the sample repo:

// src/twd-tests/helloWorld.twd.test.ts
import { twd, userEvent, screenDom } from 'twd-js'
import { describe, it, beforeEach } from 'twd-js/runner'
import { queryClient } from '#/query-client'

describe('Hello World Page', () => {
  beforeEach(() => {
    twd.clearRequestMockRules()
    queryClient.clear()
  })

  it('counts up when you click', async () => {
    await twd.visit('/')

    const button = await screenDom.findByText('Count is 0')
    await userEvent.click(button)
    twd.should(button, 'have.text', 'Count is 1')
  })
})

That's it. No render(<Counter />), no MemoryRouter, no provider wrapper. The real TanStack Router handles the visit('/'). The real component renders. The screenDom API is Testing Library's same findByText etc., scoped to the live DOM.

For a route that fetches:

it('shows the todo list', async () => {
  await twd.mockRequest('getTodos', {
    method: 'GET',
    url: '/api/todos',
    response: [{ id: '1', title: 'Learn TWD', description: '...', date: '2024-12-20' }],
    status: 200,
  })

  await twd.visit('/todos')
  await twd.waitForRequest('getTodos')

  const title = await screenDom.findByText('Learn TWD')
  twd.should(title, 'be.visible')
})

The TanStack Router loader runs (it calls queryClient.ensureQueryData(...)), the mock matches, useSuspenseQuery reads the cached data, the component renders. You only assert on the result.

The trap nobody warns you about: SPA navigation keeps the cache alive

Try writing two tests against /todos back to back and you'll hit this:

Rule "getTodoList" was not executed within 1000ms.
  Expected: GET /api/todos
  Executed rules: none

The mock is registered. The route renders. And no network request happens.

Here's why. twd.visit('/todos') is a router navigation: same browser tab, same JS runtime, same module instances. The first test populated the ['todos'] query cache. The second test's loader calls ensureQueryData(['todos']), gets the cached array, and never calls fetch. Your mock sits there waiting for a request that will never come.

The error looks like a network bug. It's not.

The fix is to expose your QueryClient as a module-level singleton and clear it between tests:

// src/query-client.ts
import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 1000 * 30 } },
})

Use that singleton in main.tsx (instead of creating one inline) and import it in your tests:

import { queryClient } from '#/query-client'

beforeEach(() => {
  twd.clearRequestMockRules()
  queryClient.clear()
})

This is worth knowing for any in-browser test runner against any caching library. It's not a TWD quirk; it's the price you pay for not throwing away your app between tests. The upside is that everything else just works: your real router, your real form library, your real query devtools.

The relay: how anything can run your tests

The second Vite plugin, twd-relay, opens a WebSocket on the dev server. With the app running in any browser tab, anyone (you, a teammate, an AI agent) can trigger the full suite from another terminal:

npx twd-relay run

The tests run in the tab you already have open, against the real router, real query cache, real component tree. The result comes back as plain text: pass/fail and the failing assertion. No headless Chrome boot, no screenshots, no DOM dumps to parse.

That's the protocol the TWD AI plugin for Claude Code uses to write and iterate on tests autonomously: the agent writes a .twd.test.ts file, runs twd-relay run, reads the output, fixes the test if it failed, and reruns. Same tab, same app, every iteration.

If you've ever watched an AI assistant generate a test that "looks right" and then spent twenty minutes fixing the imports and selectors, the difference is hard to overstate.

Try it

Sample repo: BRIKEV/twd-tanstack-example. TanStack Router + Query + Form, four passing TWD tests, OpenAPI contract validation in CI, the singleton trick wired up.
Docs: twd.dev
Install in your own TanStack app:

  npm install --save-dev twd-js twd-relay
  npx twd-js init public --save

Add the two plugins to vite.config.ts, write your first .twd.test.ts, run npm run dev. The sidebar opens itself.

DEV Community: Kevin Julián Martínez Escobar

Real-browser testing for Open Cells apps with TWD

The usual Vite stack, and the gap

Not just Cells

Setup is small

Coverage, without changing the build

Try it

Testing HTMX apps in the real browser with TWD

Setup: load both from a CDN

Test against the real backend

A note on mocking

Try it

Test your vanilla JS app in the real browser, with no build step

Setup: one import map

The tests read like Testing Library

Mocking works too

The part that pays off later

The easiest way to test a legacy Create React App

Setup

You already know the queries

Mocking the API

Two gotchas (and the fixes)

CI in one job

The whole thing is a repo

When you finally migrate to Vite

The Production Bug You Can't Reproduce by Clicking

Why Manual Testing Can't Touch It

An Agent Reads Code, Not Screens

Reproducing the Race with a Delayed Mock

What Made the Difference

Automated Accessibility Testing: axe-core, Keyboard Navigation, and WCAG in the Browser

The gap: accessibility tests that run in jsdom

Approach 1: axe-core, scanned after the interaction

Approach 2: keyboard navigation and focus order

Watch out with automated accessibility testing

Why this matters to us

Try it

In-Browser Testing: Vitest Browser Mode and TWD, Side by Side

1. Setup

2. The standalone runner

3. Component testing vs full app flows

4. Network mocking

5. CI and coverage

Conclusion

Testing Nuxt apps in the real browser, against a real backend

Setup

1. Inject the sidebar in app.vue

2. Reload the browser when a test file changes

Testing against the real backend

Try it

Playwright vs TWD: A Frontend Developer's Honest Comparison

The first thing you notice: where the tests live

The feedback loop

The debugging story (and why it matters more now)

What you get without having to build it

How they actually compose

What the session left me with

Frontend with AI: workflow first, agent second

The problem: AI amplifies what you already have

The proposal: define the workflow first

The piece that makes it click: TWD

The flow, phase by phase

The rules for structuring tests

Closing

The easiest way to test React Router v7 apps

Setup

A fallback /testing route

Writing a route-level test

Backend tests: any runner works

Why this works: same utility, different environment

Try it

Testing TanStack Router + Query apps in the real browser

The setup is two Vite plugins

Writing a test

The trap nobody warns you about: SPA navigation keeps the cache alive

The relay: how anything can run your tests

Try it

A fallback `/testing` route