Coder Legion - Recent posts tagged twd

The Testing Trophy, and Where TWD Fits

Mon, 26 Oct 2026 19:17:07 +0000

Most frontend teams I talk to have plenty of tests and still find out about broken screens from users. The unit tests are green, the refactor broke every one of them anyway, and nobody is sure the checkout flow works until someone clicks through it.

That tension is exactly what the Testing Trophy is about.

The trophy

Kent C. Dodds drew testing as a trophy instead of a pyramid. Four layers, and the size of each one is roughly how much of your effort it deserves:

Static: typos and type errors caught as you write the code. TypeScript, ESLint.
Unit: one function, hook or component checked in isolation. Vitest, Jest.
Integration: several units working together. The biggest part of the trophy.
End to End: a robot clicking through the deployed app, real backend included. Playwright, Cypress.

The shape comes from one line, written by Guillermo Rauch and popularized by Kent:

Write tests. Not too many. Mostly integration.

Each layer trades speed for confidence. Unit tests are cheap, but they can pass while the screen is broken. End-to-end tests give the most confidence, but they need the whole system running and are the slowest to write and run. Integration tests sit in the middle: they use the app the way a user does, and they stay fast and deterministic because the only thing faked is what you don't own.

Kent's guiding principle for them:

The more your tests resemble the way your software is used, the more confidence they can give you.

What integration means on the frontend

For a frontend app, an integration test renders the real thing (routes, providers, state, components) and mocks only the network. Then it does what a user would: visit a page, type, click, and check what is on the screen.

The classic way to do this is Testing Library with jsdom, in Vitest or Jest. It is a good setup and it is where most of us learned this style. It runs in a simulated DOM in your terminal, though, separate from the app you have open while you build.

Where TWD fits

TWD is built for that middle layer, and it runs the tests in the browser you develop in:

Next to your app. A sidebar in your dev server runs the tests against the real app. You watch each one drive the page.
Mock what you don't own. API calls are answered by a service worker, and contract testing checks every mock against your OpenAPI spec, so the mocks don't drift from the real API.
Tests that read like the user. Testing Library queries find elements by role, label and text.
The same tests everywhere. twd-cli runs them headlessly in CI, with coverage and a video per test if you want one, and your AI agent can write, run and fix them.

In practice this layer can carry a lot. On two production apps we run 872 tests on every pull request, mostly user flows, in one headless Chrome on a 2-vCPU GitHub runner, in about 5 minutes per app.

What it doesn't replace

TWD doesn't cover the whole trophy, and it shouldn't.

Keep a few end-to-end tests with Playwright or Cypress for the critical paths, the ones that need the real backend, the payment provider or the third-party SDK. Use unit tests for logic that is easier to check on its own. Keep TypeScript and ESLint at the base (and twd-lint for your test files). Then let integration tests carry most of the weight.

A map, not a ritual

TWD doesn't ask you to pick a layer before you write a test. You automate the check you were already doing by hand while you build. The trophy just shows where those checks end up: mostly in the middle.

The full page, with the trophy and the tools per layer, is at twd.dev/testing-trophy. For the strategy itself, go to the source: Kent's TestingJavaScript.com.

Your Agent Says the Tests Pass. Watch Them

Thu, 17 Sep 2026 14:24:37 +0000

An agent opened a pull request on my repo last week. Eleven files changed, three new tests, all green.

So what do you actually check?

You can read the diff. You can read the test file and see what it asserts. Both of those tell you what the agent believes it built. Neither tells you what a person using the thing would see, and that gap is where the interesting failures live.

I added a label. A minute later there was a comment on the pull request:

Recording: 3 clip(s), one per test this branch added.

Three short videos. One per test the branch added. I watched them in under a minute and knew more than the diff had told me in five.

The green tick got cheaper

For twenty years a passing test was a reasonable proxy for "someone thought about this". A human wrote the test, then wrote code until it passed. The test carried the intent of a second person, or at least of the same person on a different day.

When an agent writes the code and the test that proves the code, that separation is gone. The test is not an independent check. It is the same model's opinion, expressed twice.

That does not make the test worthless. It makes it a claim rather than evidence, and claims need checking in a way that evidence does not.

The cheapest check I have found is watching the thing run.

A test file tells you what it asserts, not what it looks like

Here is a test that passes and proves nothing useful:

const el = await screenDom.findByRole("button", { name: "Add project" });
twd.should(el, "be.visible");

The button exists. It is visible. The test is green.

It is also possible that the button sits on top of the heading, that the empty state it belongs to renders below the fold, or that clicking it does nothing at all because nobody asked for that yet. All of those are consistent with a green run and none of them are visible in the test file.

You do not find those by reading harder. You find them by looking.

Deterministic, not a demo

The distinction that makes this useful rather than decorative: the clip is produced by the run, not recorded by a person.

A demo video is a performance. Somebody walked through the app once, on their machine, at a moment when it happened to work, and the recording starts going stale the second it is saved. Six months later it shows a UI that no longer exists, and nobody notices because nobody regenerates it.

A test recording is the same execution that produced the green tick, captured. Re-run the suite and you get a new clip. Change the behaviour and the clip changes with it, or the test fails and there is no clip at all. It cannot drift from the code, because it is the code running.

That is what makes it safe to attach to a pull request and safe to keep.

The pacing detail that makes it watchable

The first time I tried recording a test suite I got a video that was mostly a flash. Tests run in milliseconds. A faithful recording of a fast test is unwatchable, which is why most attempts at this quietly get abandoned.

twd-cli paces the execution itself rather than slowing the video down afterwards:

npx twd-cli run --record --test "checkout flow"

Frames are captured at full rate and the pauses land where something just happened. The default is 300ms between actions, and --record-pace moves it:

npx twd-cli run --record --record-pace 500 --test "checkout flow"

The difference between pacing the run and slowing the file matters more than it sounds. A slowed-down video is uniformly sluggish. A paced run has rhythm: the click, then a beat, then the thing that happened. You can follow it.

Output is one file per matched test, named after the test:

twd-artifacts/
  todos-adds-a-todo.mp4
  todos-marks-a-todo-done.mp4

In CI, record only what changed

Recording an entire suite on every pull request produces an archive nobody opens. The version that gets watched records only the tests the branch added or modified:

uses: BRIKEV/twd-cli/.github/actions/record@v1.8.0
with:
  changed-since: ${{ github.event.pull_request.base.sha }}

The action installs ffmpeg, runs the recording, uploads the clips as an artifact, and gives you back a count and a URL you can put in a pull request comment. The inputs are documented at twd.dev/recording#recording-in-ci.

Three clips on a pull request is a review aid. Four hundred clips is a data retention problem.

Who it is actually for

The person who cannot read the test. A product owner can watch fifteen seconds and say "that is not what I meant". They cannot say that about a test file, and they will not tell you they cannot read it. They will just approve.

You, in six months. The pull request that changed this behaviour has a clip in it. That is a faster answer to "what did this used to do" than any amount of archaeology.

You, at 5pm. Reviewing agent output is a new and genuinely tiring kind of work. The bottleneck stopped being how fast code gets written and became how much of it you can actually check. Video is the highest bandwidth per second of attention I have found.

What it costs

A label, or one flag. Recording requires ffmpeg 8 or later, and twd-cli validates it before launching the browser so you get a clear failure rather than a corrupt file.

In my repo it is a record label on the pull request, applied after the agent has finished. Not automatic, because not every change is worth a video, and the person deciding that is me.

That is the whole trade. A minute of CI and a minute of watching, against approving a diff you skimmed because it was green.

Run Vue Component Tests Where Vue Runs: The Browser

Tue, 01 Sep 2026 07:35:19 +0000

A Vue component's job is to produce DOM in a browser. Most component tests ask it to do that somewhere else: in Node, against a DOM that jsdom simulates. That has been the default since npm create vue@latest started offering Vitest with jsdom, and for plenty of tests it is the right trade. It does set a ceiling on what a green test proves, though. Nothing is ever drawn. Your CSS never runs and nothing has a size or a position, so a component can pass every assertion in the file and still be broken on screen.

I co-maintain twd-js, which runs tests inside your actual dev server, in a sidebar, next to the app. It was built for flow testing: visit a route, click through the app, assert on what the user sees. Component testing was the thing it did not do.

Then I tried calling render() from @testing-library/vue inside a TWD test.

import { afterEach, describe, it } from "twd-js/runner";
import { twd, userEvent } from "twd-js";
import { render, screen, cleanup } from "@testing-library/vue";
import HomeView from "../../views/HomeView.vue";
import { componentHost, restorePage } from "../support/componentHost";

describe("HomeView component", () => {
  afterEach(() => {
    cleanup();
    restorePage();
  });

  it("increments the counter on click", async () => {
    // componentHost() is a blank div on an empty page. More on it below.
    render(HomeView, { container: componentHost() });

    const button = await screen.findByTestId("counter-button");
    twd.should(button, "contain.text", "Count is 0");

    await userEvent.click(button);
    twd.should(button, "contain.text", "Count is 1");
  });
});

Nothing broke. The component mounts into the page, the sidebar shows it running, and reactivity does what reactivity does, in a browser, against a DOM nobody had to simulate.

Why this works at all

Vue Testing Library is a thin layer. render() mounts your component with @vue/test-utils and binds @testing-library/dom queries to the result. Neither of those is tied to jsdom. jsdom is just the DOM most people hand them.

Give them a real one and the same code runs, except now the component is actually on a screen, with a real size, a real position, and your CSS applied to it. TWD already runs inside your app in the browser, so the real DOM is right there.

The setup

One helper, and no changes to your app.

render() appends its container to document.body, so the component lands after #app, a full viewport below your layout. The app is also still on the page, so screen matches its elements as well as the ones your test just rendered. Both of those are the same problem: the app is in the way.

const HOST_ID = "twd-component-host";
const APP_ROOT_ID = "app";

let appRoot: HTMLElement | null = null;
let placeholder: Comment | null = null;

export function componentHost(): HTMLElement {
  detachApp();

  let host = document.getElementById(HOST_ID);
  if (!host) {
    host = document.createElement("div");
    host.id = HOST_ID;
  }
  if (!host.isConnected) {
    document.body.prepend(host);
  }

  host.innerHTML = "";
  return host;
}

export function restorePage(): void {
  document.getElementById(HOST_ID)?.remove();
  attachApp();
}

function detachApp(): void {
  if (placeholder) return;

  const root = document.getElementById(APP_ROOT_ID);
  if (!root) return;

  appRoot = root;
  placeholder = document.createComment(" app detached by twd component test ");
  root.replaceWith(placeholder);
}

function attachApp(): void {
  if (!placeholder || !appRoot) return;

  placeholder.replaceWith(appRoot);
  placeholder = null;
  appRoot = null;
}

Detaching the app root is not the same as emptying it. app.innerHTML = "" pulls the DOM out from under Vue while its vnodes still point at those nodes, and the next router navigation patches elements that are no longer in the document. Moving the node out and putting it back leaves that correspondence intact, so restorePage() returns a live app.

prepend rather than append puts the component at the top of the page. It also keeps it in normal flow, which matters in a browser: the page is offset to make room for the TWD sidebar, and anything in normal flow inherits that offset for free.

One detail worth keeping: cleanup() and restorePage() belong in afterEach, not beforeEach. In jsdom the environment is torn down for you between files. In a real browser it is not, so renders stack up, and your flow tests need the app back before they run.

That is the whole setup. Your app does not change.

The part that changes how the test reads

Here is the same idea on a view that fetches on mount and posts a form.

it("posts the form values when a todo is created", async () => {
  await twd.mockRequest("getTodoList", {
    method: "GET",
    url: "/api/todos",
    response: [],
    status: 200,
  });
  await twd.mockRequest("createTodo", {
    method: "POST",
    url: "/api/todos",
    status: 201,
    response: { id: "1", title: "Write the Vue post", description: "In a real browser", date: "2026-09-01" },
  });

  render(TodosView, { container: componentHost() });
  await twd.waitForRequest("getTodoList");

  await userEvent.type(await screen.findByLabelText("Title"), "Write the Vue post");
  await userEvent.type(screen.getByLabelText("Description"), "In a real browser");
  await userEvent.type(screen.getByLabelText("Date"), "2026-09-01");

  await userEvent.click(screen.getByRole("button", { name: "Create Todo" }));

  const rule = await twd.waitForRequest("createTodo");
  expect(rule.request).to.deep.equal({
    title: "Write the Vue post",
    description: "In a real browser",
    date: "2026-09-01",
  });
});

Nothing here is stubbed except the network. The component's onMounted, its ref state, the v-model bindings and the axios call all run for real, and the assertion is on the request that actually left the browser. In jsdom that test usually starts with a vi.mock of the API module, and from then on you are asserting that your component calls your mock correctly.

userEvent here comes from twd-js, which re-exports @testing-library/user-event so there is nothing extra to install. It drives v-model the way a person does, one key event at a time, and in a real browser those are real key events.

Both kinds of test, one run

Component tests and flow tests are now the same kind of artifact. Files in the same project, listed in the same sidebar, running in the same browser session against the same bundle. There is no second runner, no second DOM, and no second config to keep in sync.

The one thing to configure is the other direction. If you also run Vitest in the same repo, exclude the browser tests from it, or Vitest will collect them, find no describe it recognises, and fail the run:

test: {
  exclude: [...configDefaults.exclude, "**/*.twd.test.*"],
},

Where each style fits

Rendering a component in isolation is the right move when the component is the subject: a form's validation states, a modal that opens and closes, a table that sorts. You skip the navigation, you skip the fixtures, and the test says exactly what it is about.

Flow tests stay the right move for anything that crosses a boundary. Routing, data loading, a sequence of screens, state that survives a navigation. Rendering a component in isolation to test those means rebuilding the app around it, which is how component test files end up longer than the components.

The useful change is not that one replaced the other. It is that choosing between them is now a decision about scope, made per test, instead of a decision about which runner and which DOM you are committing to.

Try it

If you already have Vue Testing Library tests, copy one, change the imports for describe and it to twd-js/runner, and hand render() the component host. The rest of the test stays as it is.

The example app is on GitHub, with the same component tested in jsdom and in the browser side by side: BRIKEV/twd-vue-example.

I wrote the React version of this first, if you want the same walkthrough with @testing-library/react: No More Fake DOM.

No More Fake DOM: Testing Library Unit Tests in the Real Browser

Mon, 31 Aug 2026 07:54:58 +0000

Every Testing Library test you have written runs against a simulated DOM. You know this. You accepted it years ago, along with the small pile of things that come with it: no real layout, nothing ever drawn on a screen, jsdom throwing on APIs it does not implement, and the quiet suspicion that a passing test and a working component are not quite the same claim.

I co-maintain twd-js, which runs tests inside your actual dev server. It was built for flow testing: visit a route, click through the app, assert on what the user sees. Component testing was the thing it did not do, and I said so in print when I compared it to Vitest Browser Mode.

Then I tried calling render() inside a TWD test, mostly to see what would break.

import { render, screen, cleanup } from "@testing-library/react";
import { describe, it, afterEach } from "twd-js/runner";
import { AppProvider } from "@/context/AppContext";
import { twd } from "twd-js";
import { Add } from "../Add";
import { componentHost, restorePage } from "@/twd-tests/support/componentHost";

describe("Add Component", () => {
  afterEach(() => {
    cleanup();
    restorePage();
  });

  it("renders the Add component", () => {
    // componentHost() is a blank div on an empty page. More on it below.
    render(<AppProvider><Add /></AppProvider>, { container: componentHost() });

    twd.should(screen.getByText("Add Item"), "be.visible");
  });
});

Nothing broke. The component mounts into the page, the sidebar shows it running, and the assertion checks an element that exists in a real browser. Same Testing Library API, no fake DOM under it.

That AppProvider is the real one, not a test double. Add uses a hook that reads from context and posts to an API, and in a real browser both of those work, so there is nothing to stand in for. That turns out to matter more than the missing jsdom.

Why this works at all

Testing Library was never tied to jsdom. @testing-library/react renders a component into a DOM node and @testing-library/dom queries it. jsdom is just the DOM most people hand it. Give it a real one and the same code runs, except now the component is actually on a screen, with a real size, a real position, and your CSS applied to it.

TWD already runs inside your app in the browser, so the real DOM is right there. render() uses it.

The setup

One helper, and no changes to your app.

render() appends its container to document.body, so the component lands after the app, a full viewport below the layout. The app is also still on the page, so screen matches its elements as well as the ones your test just rendered. Both of those are the same problem: the app is in the way.

const HOST_ID = "twd-component-host";
const APP_ROOT_ID = "root";

let appRoot: HTMLElement | null = null;
let placeholder: Comment | null = null;

export function componentHost(): HTMLElement {
  detachApp();

  let host = document.getElementById(HOST_ID);
  if (!host) {
    host = document.createElement("div");
    host.id = HOST_ID;
  }
  if (!host.isConnected) {
    document.body.prepend(host);
  }

  host.innerHTML = "";
  return host;
}

export function restorePage(): void {
  document.getElementById(HOST_ID)?.remove();
  attachApp();
}

function detachApp(): void {
  if (placeholder) return;

  const root = document.getElementById(APP_ROOT_ID);
  if (!root) return;

  appRoot = root;
  placeholder = document.createComment(" app detached by twd component test ");
  root.replaceWith(placeholder);
}

function attachApp(): void {
  if (!placeholder || !appRoot) return;

  placeholder.replaceWith(appRoot);
  placeholder = null;
  appRoot = null;
}

Detaching the app root is not the same as emptying it. root.innerHTML = "" pulls the DOM out from under React while it still holds references to those nodes, and the app does not come back. Moving the node out and putting it back leaves the references intact, so restorePage() returns a live app.

prepend rather than append puts the component at the top of the page instead of below where the app used to be, so you can watch it run without scrolling.

The payoff is that screen behaves exactly like it does in jsdom. The only thing in the document is what your test rendered, which also covers anything the component renders through a portal, since that lands on document.body rather than inside the container.

That is the whole setup. Your app does not change.

Two traps

screenDom will not find your component. TWD exposes screenDom, a wrapper around Testing Library queries scoped to your app root so it never matches the TWD sidebar. Testing Library's render() mounts outside that root. I probed it in a real app to be sure:

container.parentElement=<body>   inside #root=false
screen: found   screenDom: not found   screenDomGlobal: found

So use Testing Library's own screen, or TWD's screenDomGlobal, which queries the whole document. If you pick screenDomGlobal, keep queries specific, because it can also match elements inside the sidebar.

Everything else works normally. twd.should takes any element you hand it, whether a query found it in your app or in a component you just rendered.

Your test pattern probably says .ts. Component tests are .tsx. A pattern of /**/*.twd.test.ts skips them silently, with no error and no missing-file warning. They simply never appear in the sidebar:

twd({
  testFilePattern: "/**/*.twd.test.{ts,tsx}",
}),

If you also run Vitest in the same repo, exclude the browser tests from it. Vitest matches *.test.tsx by default, collects the TWD files, finds no describe it recognises, and fails the run with No test suite found in file:

test: {
  exclude: [...configDefaults.exclude, "**/*.twd.test.*"],
},

Both kinds of test, one run

This is the part I did not expect to matter as much as it does.

Component tests and flow tests are now the same kind of artifact. They are files in the same project, running in the same browser, in the same session, against the same instrumented bundle. So one command runs both:

$ npx twd-cli run
Running 14 test(s)...
Code coverage data written to .nyc_output/out.json

--- Run complete ---
  Passed: 14 | Failed: 0 | Skipped: 0
  Duration: 6.9s

Ten of those drive the whole app through routing, search, sorting and deletion. Four render a single dialog component in isolation. One coverage file comes out the other end, covering both.

That last part is usually where multi-runner setups get tedious. Component coverage in one report, end-to-end coverage in another, and a merge step that someone maintains. Here there is nothing to merge, because there was only ever one run.

Where each style fits

Rendering a component in isolation is the right move when the component is the subject: a form's validation states, a dialog that opens and closes, a table that sorts. You skip the navigation, you skip the fixtures, and the test says exactly what it is about.

Try it

If you already have Testing Library tests, the fastest way to see this is to copy one, change the imports for describe and it to twd-js/runner, and hand render() the component host.

The example app from this post is on GitHub, with the same component tested in jsdom and in the browser side by side: kevinccbsg/frontend-challenge.

In the next post I look at what happened when I put those two versions next to each other. The jsdom test mocked the hook it was testing through, and once I stopped mocking, it turned out the mocks had been doing most of the work.

AI Made Code Review the Bottleneck. Attach the UI to Your PR

Mon, 03 Aug 2026 07:01:36 +0000

You open a frontend pull request. The diff is 400 lines, an AI agent wrote most of it, and the description says "adds the checkout flow". CI is green.

You read the diff. It looks reasonable. You still have no idea what the UI actually does.

So you do what you always do. You pull the branch, install dependencies, start the dev server, and click through the flow yourself.

Ten minutes later you approve the PR.

That ten minutes is the bottleneck now.

AI made writing code dramatically faster. Reviewing frontend behavior did not.

Tests solve part of the problem

Tests already reduce a large part of that uncertainty.

With twd-js, they execute inside a real browser, against the real DOM, with the network mocked so runs stay deterministic. A green run means the entire flow actually executed.

But a green run only tells the reviewer that the assertions passed.

It does not tell them what the user sees.

Was the validation message attached to the correct field?

Did the modal actually close?

Does the empty state look intentional, or does it look broken?

Those are exactly the things reviewers still verify manually, and they are difficult to express as assertions alone.

Put the flow in the pull request

Your tests already drive the application through the exact flow under review.

If reviewers could simply watch that execution, they would not need to pull the branch just to understand the UI.

twd-cli can record the run:

npx twd-cli run --record --test "checkout flow"

That produces:

twd-artifacts/checkout-flow.mp4

Drop the video directly into the pull request description.

The first problem you'll hit

The first time you try this, you discover something unexpected.

The tests finish in about a second.

The recording is technically correct.

It is also almost impossible for a human to follow.

Slowing the video down is the wrong fix

The obvious solution is to stretch the recording afterwards.

A simple ffmpeg filter can do that, but it stretches the same frames across a longer duration. As playback slows down, the effective frame rate drops.

Speed	Duration	Effective FPS
1x	1.00s	30
0.5x	1.90s	15.3
0.25x	3.90s	7.7

At quarter speed, you're watching an 8 FPS video.

It also slows every moment equally. The interesting interactions and the idle time both become longer. The result is not easier to understand. It is simply slower.

This is where architecture matters

Most testing tools record a browser that is being driven from the outside.

The recording is a byproduct of automation, so once execution has finished, post processing is your only option.

TWD works differently.

Its commands execute as JavaScript inside the page itself.

Because TWD owns the command loop, it can control when commands execute, not just how the recording is encoded.

Instead of stretching frames afterwards, it spaces out execution while the test is running.

Frames are still captured at full frame rate.

Pauses happen only after meaningful interactions.

Typing is paced character by character instead of appearing all at once.

That produces a recording that feels natural to watch without sacrificing smoothness.

Which is why recordings are paced by default:

# Default: 300ms pause after each command
npx twd-cli run --record --test "checkout flow"

# Better for demos or stakeholder reviews
npx twd-cli run --record --record-pace 500 --test "checkout flow"

In practice, values between 200ms and 500ms are usually enough to make interactions comfortable to follow while keeping recordings concise.

The result is still a smooth 30 FPS video.

Only the moments that matter become easier to observe.

What the reviewer gets

The reviewer watches the actual flow.

Driven by the actual tests.

Running against the actual application.

Not a screen recording someone remembered to make.

Not a Loom video that becomes outdated after the next commit.

The recording is regenerated every time the tests run.

The review changes from:

"Does this diff look correct?"

to:

"Is this the behavior we actually wanted?"

That is the question worth a human's attention.

The bottleneck moved

Every improvement in software development moves the bottleneck somewhere else.

Today, AI has made writing code significantly faster.

Frontend review is still largely manual because reviewers need to understand behavior, not just source code.

A green checkmark confirms that the tests passed.

It does not show what happened.

Browser based tests can produce something much more valuable than a success badge.

They can produce evidence.

Sometimes, that evidence is a short video that saves every reviewer ten minutes.

npx twd-cli run --record --test "the flow you changed"

If your tests already know how to reproduce the feature, your pull request should show it.

See the Recording Runs documentation for all available options.

Testing microfrontends with TWD: one runner, three frameworks

Tue, 28 Jul 2026 22:29:39 +0000

Microfrontends split a frontend into apps that build, deploy and version on their own. One team ships React 19, another is still on React 17 and migrating away from it, a third runs Vue. That independence is the point, and it is usually why the architecture got chosen.

It also means there is no single test setup anymore.

What usually happens to testing

Each team picks its own stack, and the same product ends up with three runners, three sets of conventions, and three different definitions of a passing build. Or testing gets pushed into one shared end-to-end suite that lives outside every team's repo and belongs to nobody. When that suite goes red, the argument about whose change broke it takes longer than the fix.

Neither outcome is anyone's plan. Both are what you get when the architecture splits and the testing story does not follow it.

Testing is harder to skip now

A lot of frontend code is generated rather than typed. Reading all of it line by line does not scale, and the useful question is not whether it looks right, it is whether the app still does what it claims. That answer has to come from the real thing, and it has to be cheap enough that every team gets it on every change.

Splitting a frontend is a reasonable way to move faster. Splitting it and losing the check that the pieces still work is not.

The same runner, whatever the framework

TWD runs tests inside the real browser, in a sidebar next to the app. It does not care which framework rendered the page, so the React team, the legacy React team and the Vue team all install the same thing.

Setup stays small. On Vite it is a plugin. On other bundlers it is a few lines in the dev entry point, plus one command to drop in the mock service worker. Nothing ships to production.

Each app keeps its own installation, its own tests and its own mocked endpoints. No shared fixture file, no shared test repo, nothing to coordinate before a team can ship. If you work with external vendors, "ship a green TWD suite" is an acceptance criterion they can satisfy in their own pipeline.

Tests that outlive the framework

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

Because the assertions run against the DOM and the accessibility tree, the same test works against a React class component, a React hooks component and a Vue component. That matters most for the team on the old version. The usual reason a legacy microfrontend exists is that someone is migrating away from it one route at a time, and tests written this way do not get rewritten when that migration lands. The suite is the part that survives.

Living documentation, in the tab you already have open

The sidebar sits next to the running app. The tests are executable examples of what each page does, in the same place you develop, so a new team member reads behaviour by running it instead of guessing from the code.

The same suites in CI

twd-cli runs the same tests headless. Each team points it at its own dev server and runs its own suite in its own pipeline:

npx twd-cli run

Nobody blocks anybody. Nothing gets rewritten into a second framework for the pipeline. What you watched pass in the sidebar is what runs on the pull request.

One thing to know

Today TWD is set up per microfrontend, and each one is tested on its own. Testing the fully composed page, with every microfrontend mounted together, is not something it does yet. In practice the split suits the architecture: teams own their own apps, and their tests follow the same boundary.

Try it

Microfrontends give every team its own framework, its own release and its own repo. They should not cost you the tests.

TWD: twd.dev
Example repo (three microfrontends, three frameworks, a TWD suite each): github.com/BRIKEV/twd-module-federation
Getting started: twd.dev/getting-started
Frameworks and bundlers: twd.dev/frameworks
Writing tests: twd.dev/writing-tests
API mocking: twd.dev/api-mocking
CI execution: twd.dev/ci-execution

Real-browser testing for Open Cells apps with TWD

Mon, 27 Jul 2026 20:12:59 +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

Fri, 24 Jul 2026 09:04:43 +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

Fri, 24 Jul 2026 09:03:09 +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

Thu, 16 Jul 2026 07:19:49 +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.

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

Wed, 01 Jul 2026 12:52:42 +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.

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

Wed, 17 Jun 2026 22:17:53 +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

Wed, 17 Jun 2026 22:17:03 +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.

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

Mon, 15 Jun 2026 16:52:22 +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.

The easiest way to test React Router v7 apps

Mon, 15 Jun 2026 16:50:54 +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.

TWD setup is now two Vite plugins and zero app code

Tue, 26 May 2026 15:30:45 +0000

Setting up TWD used to mean adding a block of dev-only code to your app's entry file — a dynamic import for the runner, a test glob, a service-worker config, and a twd-relay browser client. It worked, but it never really belonged there.

With twd-js@1.8 and twd-relay@1.2, both packages ship Vite plugins. Setup is two entries in vite.config.ts and nothing in main.tsx.

The new setup

vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { twd } from "twd-js/vite-plugin";
import { twdRemote } from "twd-relay/vite";

export default defineConfig({
    plugins: [
        react(),
        twd({
            testFilePattern: "/**/*.twd.test.ts",
            open: false,
            position: "right",
            search: true,
        }),
        twdRemote(),
    ],
});

main.tsx:

import React from "react";
import ReactDOM from "react-dom/client";
import { RouterProvider } from "react-router";
import { router } from "./routes/router";
import "./styles/index.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
    <RouterProvider router={router} />,
);

That's the whole setup. twd() owns the sidebar, glob discovery, and service-worker registration. twdRemote() attaches the relay to the Vite dev server and auto-injects the browser client into index.html. Both plugins use apply: 'serve', so production builds are untouched.

What it replaces

For comparison, here's what a TWD entry file looked like a few weeks ago:

if (import.meta.env.DEV) {
    const { initTWD } = await import("twd-js/bundled");
    const tests = import.meta.glob("./**/*.twd.test.ts");
    initTWD(tests, {
        open: false,
        position: "right",
        serviceWorker: true,
        serviceWorkerUrl: "/mock-sw.js",
        search: true,
    });

    const { createBrowserClient } = await import("twd-relay/browser");
    const client = createBrowserClient({
        url: `${window.location.origin}/__twd/ws`,
    });
    client.connect();
}

Two top-level await imports, a glob, a service-worker URL that had to stay in sync with the runner, a WebSocket URL that had to match the relay path, and config repeating defaults. All of it dev-only, all of it sitting above ReactDOM.createRoot.

After the upgrade, that block is gone. No if (import.meta.env.DEV), no dynamic imports, no relay client. The dev-tooling story lives entirely in vite.config.ts.

Why it matters

One source of truth for the wiring. The serviceWorkerUrl, the SW served by the dev server, the WebSocket path used by the relay, and the path the browser client connects to were all strings in different files that had to agree. Now the plugins own them.

No top-level await for tooling. The await import("twd-js/bundled") was loading a chunk that had nothing to do with your app, before React was allowed to mount.

Tooling lives in tooling config. New developers reading main.tsx shouldn't have to mentally if (import.meta.env.DEV)-out a quarter of the file to understand startup. The plugin model is what the rest of the Vite ecosystem already does — @vitejs/plugin-react, Tailwind, Tanstack Router devtools — and TWD now matches.

Non-Vite projects

Webpack, Angular CLI, Rollup, esbuild, Rspack — anywhere the Vite plugins don't apply — keep the manual API. initTWD and createBrowserClient stay public exports forever. twdRemote({ autoConnect: false }) is also there as an escape hatch for Vite projects that want to wire the browser client by hand.

Try it

The runner is at https://twd.dev. Upgrade to twd-js@1.8 and twd-relay@1.2, drop the dev-only block from main.tsx, add the two plugins to vite.config.ts, and you're done.

Modern Frontend Frameworks Are Failing at Testing

Tue, 30 Dec 2025 12:12:28 +0000

A few weeks after releasing TWD, a tool designed to integrate testing directly into the development workflow. I started creating testing recipes for different frontend frameworks. While doing that, a few patterns became very clear.

What works

Frontend-focused applications (SPAs) are relatively easy to test using tools like TWD and traditional runners such as Vitest.
You can validate real user interactions, keep tests close to the UI, and iterate quickly.

What doesn’t

SSR frameworks make testing unnecessarily confusing.

Frameworks like Next.js, Astro, TanStack, Qwik, and Solid provide little to no guidance on how to test applications in a reliable and maintainable way. Most of them simply delegate testing to external tools like Playwright or Cypress (example next.js docs), treating testing as an afterthought rather than part of the framework itself.

The problem with SSR frameworks

SSR frameworks blur the line between backend and frontend. In theory, this sounds powerful. In practice, it creates serious testing problems.

Yes, you need to test both frontend and backend behavior, but SSR frameworks don’t offer a clear or opinionated way to do that. If you look at their documentation, testing is either:

Completely missing
Mentioned briefly
Outsourced to E2E tools like Playwright or Cypress

This effectively means: “Here’s how to build fast. Testing is your problem.”

From a company perspective—especially one building a long-lived product—this is a big red flag. You want:

Tests that are easy to write
Tests that reliably fail when something is actually broken
Tests that help reproduce bugs
Tests that evolve with the product

Most SSR frameworks don’t provide that. They optimize for speed of development, but you start accumulating testing debt from day one.

“But you can unit test, right?”

Technically, yes. But in practice, unit testing frontend code often becomes testing for the sake of testing.

What usually happens:

You mock half of the system
You test implementation details
You don’t test real user interactions

Eventually, you fall back to Playwright. And now:

Tests live outside your app
They’re slower
They’re harder to debug
They don’t feel like part of your development workflow

This is extremely common in Next.js applications. To this day, I haven’t seen a truly robust testing setup for Next.js that:

Fails only when something meaningful is broken
Avoids implementation details
Is easy to write and maintain

By “robust,” I mean tests that actually protect the product—not just increase coverage numbers.

React Router loaders and actions: an exception

In the React ecosystem, I found one notable exception: React Router, specifically createRoutesStub.

This API is interesting because it allows you to:

Mock routes with loaders and actions
Create different scenarios per page
Test frontend behavior realistically
test loaders and actions separately as pure functions

This separation of concerns is something many frameworks try to replicate—but React Router gets it right.

The API design makes testing:

Straightforward
Explicit
Predictable

Even better, migrating from SPA data mode to framework (SSR) mode is incremental and low-risk.

After researching multiple alternatives, and considering that testing is one of the most critical aspects of a product, React Router is the only SSR-capable solution I’d personally choose today.

Using TWD with React Router

When building TWD, we noticed how powerful createRoutesStub was—and decided to use it in a different way.

Instead of testing routes in isolation, we:

Added a dedicated testing route
Executed TWD tests inside the real application
Rendered pages using route stubs
Controlled loaders, actions, and scenarios per test

Here’s the setup.

Route configuration

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("todos", "routes/todolist.tsx"),
  route("testing", "routes/testing-page.tsx"),
] satisfies RouteConfig;

Testing page

// app/routes/testing-page.tsx
let twdInitialized = false;

export async function clientLoader() {
  if (import.meta.env.DEV) {
    const testModules = import.meta.glob("../**/*.twd.test.{ts,tsx}");
    if (!twdInitialized) {
      const { initTWD } = await import('twd-js/bundled');
      initTWD(testModules, {
        serviceWorker: false,
      });
      twdInitialized = true;
    }
    return {};
  } else {
    return {};
  }
}

export default function TestPage() {
  return (
    <div data-testid="testing-page" >
      <h1 style={{ opacity: 0.5, fontFamily: 'system-ui, sans-serif' }}>TWD Test Page</h1>
      <p style={{ opacity: 0.5, fontFamily: 'system-ui, sans-serif' }}>
        This page is used as a mounting point for TWD tests.
      </p>
    </div>
  );
}

Example test

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;
  }

  // Navigate to the empty test page
  await twd.visit('/testing');
  
  // Get the container from the test page
  const container = await screenDomGlobal.findByTestId('testing-page');
  root = createRoot(container);
  return root;
}

describe("Hello World Test", () => {
  // root instance to re render the stub
  let root: ReturnType<typeof createRoot> | undefined;

  beforeEach(async () => {
    // preparing the root instance
    root = await setupReactRoot();
  });

  it("should render home page test", async () => {
    // mocking the component
    const Stub = createRoutesStub([
      {
        path: "/",
        Component: () => {
          const loaderData = useLoaderData();
          const params = useParams();
          const matches = useMatches() as any;
          return <Home loaderData={loaderData} params={params} matches={matches} />;
        },
        loader() {
          return { title: "Home Page test" };
        },
      },
    ]);

    // Render the Stub
    root!.render(<Stub />);
    await twd.wait(300);
    // Check for the element within our test container
    // We scope the search to the container to be safe, or just search globally since the harness is empty otherwise
    const h1 = await screenDom.findByRole('heading', { level: 1 });
    twd.should(h1, 'have.text', 'Home Page test');
  });
});

Once the test runs, the route is rendered inside the real application, fully interactive, with all assertions passing.

Conclusion

At the end of the day, you have a choice:

Keep using tools that optimize for speed but accumulate testing debt
Or adopt an approach where testing is part of everyday development

For SSR applications, React Router + TWD is the first setup I’ve seen that truly supports:

Real UI testing
Maintainability and easier to debug
Long-lived products
Fast feedback

If you work on large applications with complex requirements, this approach scales far better than traditional SSR testing strategies.

An example on how to integrate twd + react router.

TWD 1.3.x release - Multiple framework support

Sun, 14 Dec 2025 11:23:48 +0000

One of the biggest milestones we’ve been working on is now live:
TWD 1.3.x brings full multi-framework support with a single unified setup.

This means you can now drop TWD into React, Vue, Solid, and Angular projects using the exact same initialization code, thanks to the new bundled build.

At its simplest, all you need is this:

// src/main.tsx (or .ts)
if (import.meta.env.DEV) {
  const { initTWD } = await import('twd-js/bundled');
  const tests = import.meta.glob("./**/*.twd.test.ts");
  
  initTWD(tests, { open: true, position: 'left' });
}

React

React continues to have the most flexible integration: use the standard setup for advanced customization or the bundled one for simplicity.

Standard Setup (full control)

if (import.meta.env.DEV) {
  const testModules = import.meta.glob("./**/*.twd.test.ts");
  const { initTests, twd, TWDSidebar } = await import('twd-js');
  
  initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
  twd.initRequestMocking().catch(console.error);
}

Simplified Setup (bundled)

if (import.meta.env.DEV) {
  const { initTWD } = await import('twd-js/bundled');
  const tests = import.meta.glob("./**/*.twd.test.ts");
  
  initTWD(tests, { open: true, position: 'left' });
}

View React Examples - Multiple React examples available in the repository.

Vue

For Vue applications, use the bundled version of TWD. This ensures that the React runtime required by TWD's UI is handled correctly without conflicting with your Vue app. Request mocking is automatically initialized.

Vue Example Repository - Complete working example with advanced scenarios.

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'

if (import.meta.env.DEV) {
  // Use the bundled version
  const { initTWD } = await import('twd-js/bundled');
  const tests = import.meta.glob("./**/*.twd.test.ts")
  
  // Request mocking is automatically initialized
  initTWD(tests);
}

createApp(App).mount('#app')

Solid

For Solid.js applications, use the bundled version of TWD. This ensures that the React runtime required by TWD's UI is handled correctly without conflicting with your Solid app. Request mocking is automatically initialized.

Solid Example Repository - Complete Solid.js integration example.

// src/main.tsx
/* @refresh reload */
import { render } from 'solid-js/web';
import 'solid-devtools';

import App from './App';

if (import.meta.env.DEV) {
  const { initTWD } = await import('twd-js/bundled');
  const tests = import.meta.glob("./**/*.twd.test.ts");
  
  // Request mocking is automatically initialized
  initTWD(tests);
}

const root = document.getElementById('root');

if (import.meta.env.DEV && !(root instanceof HTMLElement)) {
  throw new Error(
    'Root element not found. Did you forget to add it to your index.html? Or maybe the id attribute got misspelled?',
  );
}

render(() => <App />, root!);

Notes for Solid

This setup works with Solid + Vite applications
Solid Start compatibility has not been tested yet, but may work with similar configuration

Angular

Angular applications can also use the bundled version. Note that you might need to manually construct the tests object if your build tool doesn't support glob imports in the same way. Request mocking is automatically initialized.

Angular Example Repository - Working Angular integration example.

// src/main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { App } from './app/app';
import { isDevMode } from '@angular/core';

if (isDevMode()) {
  const { initTWD } = await import('twd-js/bundled');
  
  // Define your test files manually or use a compatible glob importer
  const tests = {
    './twd-tests/helloWorld.twd.test.ts': () => import('./twd-tests/helloWorld.twd.test'),
    './twd-tests/todoList.twd.test.ts': () => import('./twd-tests/todoList.twd.test'),
  };
  
  // Request mocking is automatically initialized
  initTWD(tests);
}

bootstrapApplication(App, appConfig)
  .catch((err) => console.error(err));

Summary

TWD 1.3.x introduces a universal setup that lets you write a test and run it in any framework—React, Vue, Solid, or Angular. The new bundled version provides a single, simple initialization method that works everywhere.

You get the full TWD experience in every environment:

Testing While Developing with the live in-app sidebar
Fast, interactive test creation directly inside your running app
Straightforward setup with just one init function
Automatic request mocking included by default
CI-ready tests that behave the same in development and pipelines
Easy to write, easy to maintain, and now fully framework-agnostic

With TWD 1.3.x, your tests become portable, consistent, and reusable—write them once, run them anywhere.

Coder Legion - Recent posts tagged twd

The Testing Trophy, and Where TWD Fits

The trophy

What integration means on the frontend

Where TWD fits

What it doesn't replace

A map, not a ritual

Your Agent Says the Tests Pass. Watch Them

The green tick got cheaper

A test file tells you what it asserts, not what it looks like

Deterministic, not a demo

The pacing detail that makes it watchable

In CI, record only what changed

Who it is actually for

What it costs

Run Vue Component Tests Where Vue Runs: The Browser

Why this works at all

The setup

The part that changes how the test reads

Both kinds of test, one run

Where each style fits

Try it

No More Fake DOM: Testing Library Unit Tests in the Real Browser

Why this works at all

The setup

Two traps

Both kinds of test, one run

Where each style fits

Try it

AI Made Code Review the Bottleneck. Attach the UI to Your PR

Tests solve part of the problem

Put the flow in the pull request

The first problem you'll hit

Slowing the video down is the wrong fix

This is where architecture matters

What the reviewer gets

The bottleneck moved

Testing microfrontends with TWD: one runner, three frameworks

What usually happens to testing

Testing is harder to skip now

The same runner, whatever the framework

Tests that outlive the framework

Living documentation, in the tab you already have open

The same suites in CI

One thing to know

Try it

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

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

A fallback `/testing` route