DEV Community: Kevin Julián Martínez Escobar

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

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

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

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

1. Setup

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

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

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

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

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

2. The standalone runner

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

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

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

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

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

3. Component testing vs full app flows

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

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

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

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

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

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

  await userEvent.click(counterButton)
})

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

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

4. Network mocking

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

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

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

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

import { http, HttpResponse } from 'msw'

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

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

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

5. CI and coverage

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

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

Conclusion

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

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

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

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

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

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

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

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

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

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

Here is the full setup.

Setup

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

Add the Vite plugin in nuxt.config.ts:

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

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

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

1. Inject the sidebar in app.vue

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

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

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

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

2. Reload the browser when a test file changes

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

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

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

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

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

Testing against the real backend

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

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

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

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

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

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

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

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

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

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

Try it

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

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

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

Playwright vs TWD: A Frontend Developer's Honest Comparison

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

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

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

The first thing you notice: where the tests live

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

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

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

The feedback loop

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

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

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

The debugging story (and why it matters more now)

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

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

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

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

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

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

What you get without having to build it

This is where the gap shows up the most.

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

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

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

How they actually compose

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

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

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

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

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

What the session left me with

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

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

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

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

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

Frontend with AI: workflow first, agent second

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

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

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

That was the starting point.

The problem: AI amplifies what you already have

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

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

The proposal: define the workflow first

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

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

The piece that makes it click: TWD

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

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

The flow, phase by phase

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

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

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

The rules for structuring tests

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

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

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

Closing

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

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

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

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

The easiest way to test React Router v7 apps

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

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

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

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

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

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

Setup

Install:

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

Add the Vite plugin:

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

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

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

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

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

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

A fallback `/testing` route

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

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

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

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

let root: ReturnType<typeof createRoot> | undefined

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

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

Writing a route-level test

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Backend tests: any runner works

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

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

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

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

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

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

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

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

Why this works: same utility, different environment

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

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

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

Try it

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

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

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

Testing TanStack Router + Query apps in the real browser

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

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

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

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

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

The setup is two Vite plugins

Install:

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

Add the plugins to vite.config.ts:

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

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

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

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

Writing a test

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

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

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

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

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

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

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

For a route that fetches:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The relay: how anything can run your tests

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

npx twd-relay run

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

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

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

Try it

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

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

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

TWD setup is now two Vite plugins and zero app code

Kevin Julián Martínez Escobar — Fri, 08 May 2026 23:19:11 +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.

Two test runtimes, two coverage reports, one fragile merge

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

You have unit tests in Vitest (or Jest). You have E2E tests in Playwright. CI runs both. Coverage works for each, until you try to look at a single number.

Then it gets weird.

Two runtimes, two coverage outputs

Unit tests run in Node, instrumented by V8 or istanbul. Playwright runs your real app in a real browser. Each produces its own coverage data. Stitching them together usually means:

nyc merge (or a custom step) combining coverage-final.json files
Reconciling source maps between Vitest's transform pipeline and Playwright's
Hoping both tools agree on file paths

It works, until it doesn't. A path mismatch silently drops files from the merged report. A Playwright run on a different Node version emits slightly different paths. Coverage drops by 12% and nobody knows why.

The deeper issue: you're not really merging coverage. You're merging evidence that two different runtimes touched the same lines. The merge step is a heuristic.

What TWD does differently

TWD runs both styles of test in the same environment, your app's Vite dev server, one browser, one execution context.

A flow test exercises the page through the DOM:

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

describe("checkout", () => {
    it("submits the order", async () => {
        await twd.visit("/checkout");
        await userEvent.click(screenDom.getByRole("button", { name: /pay/i }));
        // ...
    });
});

A unit test imports the function and asserts directly:

import { expect } from "twd-js";
import { describe, it } from "twd-js/runner";
import { normalizeOrder } from "@/utils/normalizeOrder";

describe("normalizeOrder", () => {
    it("defaults quantity to 1 when missing", () => {
        const result = normalizeOrder({ items: [{ sku: "ABC" }] });
        expect(result.items[0].quantity).to.equal(1);
    });
});

Same describe, same it, same expect. Same browser. Same coverage source.

There's no merge step because there's nothing to merge.

When to reach for which

Flow tests are most important and valuable. They cover real user behaviour, routes, interactions, mutations. They catch the bugs your users would actually hit.

Unit tests fill the gaps flow tests can't reach. A pure utility with seven branches in a switch statement isn't worth seven Flow tests, but it's worth covering. Drop it in a unit/ folder, parameterize the branches inline in one it(), done.

The rule of thumb:

Prefer flow-based tests for anything user-visible.
Use unit tests for pure functions and edge-case branches that flow tests genuinely can't reach.
Don't duplicate coverage between the two styles.

The real win

The coverage number at the end of a TWD run is one number from one runtime — not two reports that almost agree. If a line is uncovered, your tests didn't exercise it. That's the only reason left.

That's a small thing. Until you spend a day debugging a CI failure that turned out to be a path mismatch in a coverage merge.

If you want to try it, the runner is at https://twd.dev.

Testing Payment Flows Without the Payment SDK

Kevin Julián Martínez Escobar — Sun, 19 Apr 2026 19:04:53 +0000

Payment integrations are one of the hardest things to test in a web app. The SDK renders its own UI, controls its own form fields, and fires callbacks when the user completes a payment. You can't programmatically fill in a credit card number. You can't simulate a declined card. And if the SDK fails to initialize — because of a network issue, a bad API key, or a test environment misconfiguration — your entire test falls apart.

You can mock the SDK's setup endpoint to get the SDK rendering, the form mounting, the session resolving. That covers surface area — but it stops there. It doesn't test what happens after the payment resolves: the API calls, the analytics events, the navigation, the error states. The part that actually matters.

This article shows a different approach: using TWD's component mocking to replace the payment SDK entirely with a simple mock that gives you full control over the payment lifecycle.

Test What You Own. Mock What You Don't.

That's TWD's philosophy, and it's the whole reason component mocking is the right tool here. The payment SDK is someone else's code — its internals and lifecycle are their problem, covered by their test suite. Your responsibility is the seam: the callbacks fired into your app, the API calls they trigger, the analytics events, the UI state. That's where your bugs ship from.

You won't exercise the real SDK in these tests. That's the tradeoff — and it's deliberate. What you gain is the ability to exercise your side of the integration exhaustively: every callback, every branch, every error path. The SDK's correctness is the vendor's concern. The correctness of everything your app does around it is yours, and that's what these tests finally reach.

The Problem

A typical payment component looks like this:

function PaymentDropIn({ session, clientKey, orderId, cart }) {
  useEffect(() => {
    const checkout = await PaymentSDK.init({
      session,
      clientKey,
      onPaymentCompleted: async () => {
        await confirmOrder(orderId);
        await trackPurchase(cart, orderId);
        navigate("/success");
      },
      onPaymentFailed: (result) => {
        trackPaymentError(cart, result.code);
        setError("Payment failed");
      },
    });
    checkout.mount(ref.current);
  }, []);

  return <div ref={ref} />;
}

Everything is tangled inside one component: the SDK initialization, the business logic, the analytics, the navigation, the error handling. You can't test the onPaymentCompleted callback without actually initializing the SDK. And you can't initialize the SDK without a real (or carefully mocked) payment session.

Step 1: Separate the SDK from the Logic

The fix is architectural. Move the callback logic out of the payment component and into the parent. The payment component becomes a thin SDK wrapper that receives callbacks as props:

// Thin wrapper — just the SDK
function PaymentDropIn({ session, clientKey, onCompleted, onFailed, onError }) {
  useEffect(() => {
    const checkout = await PaymentSDK.init({
      session,
      clientKey,
      onPaymentCompleted: () => onCompleted(),
      onPaymentFailed: (result) => onFailed(result.code),
      onError: (err) => onError(err.message),
    });
    checkout.mount(ref.current);
  }, []);

  return <div ref={ref} />;
}

// Parent — owns the business logic
function CheckoutPage({ cart, orderId }) {
  const handleCompleted = async () => {
    await confirmOrder(orderId);
    await trackPurchase(cart, orderId);
    navigate("/success");
  };

  const handleFailed = (code) => {
    trackPaymentError(cart, code);
    setError("Payment failed");
  };

  return (
    <PaymentDropIn
      session={session}
      clientKey={clientKey}
      onCompleted={handleCompleted}
      onFailed={handleFailed}
      onError={handleError}
    />
  );
}

This is a good refactor regardless of testing. The parent owns the business logic. The payment component owns the SDK. Clean separation.

Step 2: Wrap for Mocking

TWD provides MockedComponent — a wrapper that lets tests replace a component's children with a mock. Wrap the payment component:

import { MockedComponent } from "twd-js/ui";

function PaymentDropIn(props) {
  return (
    <MockedComponent name="paymentDropIn">
      <PaymentDropInContent {...props} />
    </MockedComponent>
  );
}

In production, MockedComponent is a transparent pass-through — it renders its children. In tests, twd.mockComponent("paymentDropIn", ...) replaces the children with whatever you provide.

One important detail: MockedComponent passes its child's props to the mock component. That's why we need PaymentDropInContent as a separate component that receives all the callback props — so the mock receives them too.

Step 3: Build the Mock

The mock is dead simple. Three buttons — one per payment outcome:

twd.mockComponent("paymentDropIn", ({ onCompleted, onFailed, onError }) => {
  return (
    <div>
      <button onClick={() => onCompleted()}>Pay</button>
      <button onClick={() => onFailed("Refused")}>Fail Payment</button>
      <button onClick={() => onError("SDK crashed")}>Error</button>
    </div>
  );
});

Click "Pay" and the parent's handleCompleted fires — calling confirmOrder, sending the purchase event, navigating to success. Click "Fail Payment" and handleFailed fires — sending the error event, showing the error banner. No SDK involved. Just callbacks.

Step 4: Test Everything

Now you can test the full payment lifecycle with standard TWD patterns:

it("should call confirmOrder and navigate to success", async () => {
  await twd.mockRequest("confirmOrder", {
    url: `/api/orders/${orderId}/confirm`,
    method: "PATCH",
    status: 200,
    response: { customer_id: "cust-123", order_count: 3 },
  });

  // ... fill form, submit, wait for payment session ...

  const payButton = await screenDom.findByRole("button", { name: "Pay" });
  await userEvent.click(payButton);

  // Verify the API was called
  const rule = await twd.waitForRequest("confirmOrder");
  expect(rule).to.exist;

  // Verify navigation
  await twd.url().should("contain.url", "/success");
});

it("should fire purchase_error when payment is declined", async () => {
  // ... setup ...

  const failButton = await screenDom.findByRole("button", { name: "Fail Payment" });
  await userEvent.click(failButton);

  const errorEvent = await twd.waitFor(() => {
    const ev = window.dataLayer.find(e => e.event === "purchase_error");
    if (!ev) throw new Error("Event not found");
    return ev;
  });
  expect(errorEvent.error_code).to.equal("Refused");
});

it("should show error banner when confirmOrder fails", async () => {
  await twd.mockRequest("confirmOrderFail", {
    url: `/api/orders/${orderId}/confirm`,
    method: "PATCH",
    status: 500,
    response: { message: "Server error" },
  });

  // ... setup ...

  const payButton = await screenDom.findByRole("button", { name: "Pay" });
  await userEvent.click(payButton);

  const errorBanner = await twd.get("[data-testid='payment-error']");
  errorBanner.should("be.visible");
  await twd.url().should("not.contain.url", "/success");
});

What This Pattern Gives You

Coverage you couldn't get before:

Analytics events fire with the correct data (payment type, transaction ID, error codes)
The confirmOrder API is called with the right order ID
Navigation to the success page happens after payment, not before
Error banners appear when the API fails
Error banners appear when the payment is declined
Error banners appear when the SDK crashes

Speed: These tests run in ~1 second each. No SDK initialization, no payment session setup, no Adyen/Stripe endpoint mocking.

Reliability: No more flaky tests that break because the payment SDK's test environment is down. The mock is deterministic.

Conclusion

The unlock is component mocking. TWD's MockedComponent lets you replace a third-party SDK in tests with a simple stand-in whose callbacks you fire on demand — so the payment flow, which previously depended on an un-drivable SDK, becomes three buttons and a set of assertions. The SDK never boots. Tests run in a second. The callback flow — API calls, analytics, navigation, error states — is finally exercised.

The thin-wrapper refactor is what makes that possible, but it's the enabler, not the point. Once it's in place, the pattern transfers to any third-party component that fires callbacks: map SDKs, video players, chat widgets, auth flows. Same shape every time — wrap the component, swap it in tests.

Existing tests that mock the SDK's setup endpoint still work; they cover different ground. The component mock picks up where those stop.

More on the feature at twd.dev/component-mocking.

When Your Mocks Lie: Contract Testing with TWD

Kevin Julián Martínez Escobar — Sun, 19 Apr 2026 19:03:50 +0000

Every mock you write is a claim about what your backend returns. The moment the backend changes — a renamed field, a tightened enum, a new required property — that claim becomes a lie. Your tests still pass. Production breaks.

This is mock drift, and it's invisible. You don't find out until a user hits a 500 or an empty UI in prod. The mocks that gave you confidence were the thing misleading you.

TWD's contract testing closes this gap. Every mock response registered in a test gets validated against your OpenAPI spec during the same run that executes the test. A schema mismatch becomes a loud, specific error — in the same output as the test failures. No separate pipeline, no broker, no provider verifier. One command does both.

This article walks through what contract testing in TWD actually does, how to wire it into an existing project, and what the output looks like when it catches real drift.

The problem contract testing solves

Consider a typical mock in a TWD test:

await twd.mockRequest("userList", {
  method: "GET",
  url: "/v1/users",
  response: {
    count: 3,
    next: null,
    previous: null,
    results: [
      {
        id: "a1b2-...",
        name: "Acme Corp",
        balance: "10000.00",
        // ...
      }
    ],
  },
  status: 200,
});

This shape made the test pass three months ago. Since then:

The backend team removed balance from the list endpoint (it's a wallet concept now, served elsewhere).
A new required field external_id was added.
The discount field format tightened from "15" to "15.00" (two decimals).

None of these changes break the test. The component receives exactly the shape the mock provides. The test is green. Everything looks fine.

Meanwhile in production, the real API returns external_id (which a column in the table now expects), omits balance (which a detail drawer is still reading), and sends "10.00" where the formatter assumes trailing decimals. Bugs ship.

The test was never wrong — it was testing the wrong reality. The mock had drifted from the contract.

What TWD does about it

TWD's contract testing runs as part of npx twd-cli run — the headless runner you'd typically invoke in CI, not the live sidebar you use during local dev. Your inner loop stays fast; drift gets surfaced on every push.

On every call to twd.mockRequest(), the response payload is collected. After tests run, each response is validated against the OpenAPI schema for the endpoint that the mock targets.

The validation uses openapi-mock-validator under the hood and covers what you'd expect from JSON Schema:

Types (string, number, integer, boolean, array, object)
String formats (uuid, email, date-time, uri, and so on)
Numeric bounds, array constraints, enum values
Required fields, additionalProperties
Composition (oneOf, anyOf, allOf)

In practice this means: if your mock returns "id": "user-123" where the spec says "format": "uuid", you hear about it. If your mock omits external_id where the spec marks it required, you hear about it. If your mock sets "status": "pending" where the spec enum only allows ["COMPLETED", "FAILED", "PENDING"], you hear about it.

The key design choice: no extra test-writing effort. You don't author contract tests separately. The mocks you already write double as contract probes. Two signals from one artifact.

Setting it up

Three pieces: get the spec, tell TWD about it, decide how loud to be.

1. Get the OpenAPI spec

Point TWD at an openapi.json somewhere on disk. How it gets there is up to you — a curl against your backend's spec endpoint in CI is the common path. Download fresh on every run so you're always validating against the current contract.

2. Configure TWD

Create twd.config.json at the project root:

{
  "url": "http://localhost:5173",
  "contractReportPath": ".twd/contract-report.md",
  "retryCount": 3,
  "contracts": [
    {
      "source": "./openapi.json",
      "baseUrl": "/",
      "mode": "warn",
      "strict": true
    }
  ]
}

Key fields:

source — path to the OpenAPI JSON.
baseUrl — prefix to strip when matching mock URLs against spec paths. If your mocks call /v1/users and the spec paths are also /v1/..., set "/". If the spec is served under /api and your mocks include that prefix, set "/api".
mode — "warn" or "error". Start with "warn".
strict — whether to reject undocumented response properties.

3. Decide the mode

This is the one real decision.

"warn" — mismatches appear in the output but the test run still passes. Good posture when you're introducing contract testing into an existing codebase with accumulated drift. You see what's broken without immediately red-gating the team.

"error" — mismatches fail the run. This is where you want to land. It's the only mode that prevents regressions.

A realistic migration path: start in warn to surface the backlog, fix mismatches module by module, then flip to error once you're clean. The flip is the important step — without it, nothing stops new drift from accumulating.

The TWD ecosystem

Contract testing isn't a standalone library — it's the seam where the TWD packages meet: mocks authored with twd-js, runs executed by twd-cli, validation handled by openapi-mock-validator, and (if you're also using the AI agent skills) the browser bridge through twd-relay.

If you're starting from zero with TWD, the AI-powered frontend testing series walks through project setup, writing tests, and wiring them into CI. Contract testing slots in once that's working.

The payoff: what the output looks like

This is the part worth showing up for — and it exists only because you're already in the TWD stack. Your mocks run through twd-js. twd-cli already executes them. The validator just reads what's already moving through your tests. No separate contract test suite, no broker to run, no provider verifier to keep in sync.

Run your normal test command:

npx twd-cli run

Alongside the usual pass/fail output for each test, you'll see a per-mock contract status line:

✓ GET /v1/users (200) — mock "userList" — in "User list > should display the table"
✗ GET /v1/users/{user_id} (200) — mock "getUser" — in "User detail"
  → response.external_id: missing required property "external_id"
✗ GET /v1/orders (200) — mock "getOrders" — in "User detail"
  → response.next: missing required property "next"
  → response.previous: missing required property "previous"

And a summary:

Mocks validated: 253 | Errors: 93 | Warnings: 1 | Skipped: 0

Contract report written to .twd/contract-report.md

That second failure line — a required property missing on a test that otherwise passes — is where contract testing earns its keep. Without it, the mock keeps serving a shape the real API no longer returns, and the only person who finds out is a user.

The markdown report is useful for PRs and CI artifacts — it groups failures by endpoint and includes the test name that produced each mock, so tracing a failure back to a specific file is straightforward.

Why this matters more than it looks

Most contract testing tools (Pact being the canonical one) are heavy: brokers, provider verifiers, consumer-driven workflows, separate CI pipelines, coordination between frontend and backend teams. The ceremony is often what kills adoption — teams try it, find it exhausting, and revert to hoping for the best.

TWD's approach gets maybe 80% of the value for 10% of the cost, because it's opportunistic rather than exhaustive. You're not testing every possible response the backend could emit — you're testing the specific responses your app actually depends on (your mocks). That's often the right target: the place where client assumptions are encoded is exactly the place worth validating.

And it's cheap to adopt. No broker, no CI changes beyond one step to download the spec, no coordination with the backend team. A consuming team can turn this on unilaterally in an afternoon and immediately benefit.

The moment the backend ships a breaking change, your next CI run reports it. Not the next deploy. Not the next bug report from a user. The next CI run.

Wiring it into CI

One change to your workflow:

- name: Download OpenAPI contract
  run: npm run contract:download

- name: Install service worker
  run: npx twd-js init public --save

- name: Run TWD tests
  run: npx twd-cli run

- name: Contract testing report
  run: cat .twd/contract-report.md

Conclusion

Contract testing isn't the whole pitch — it's one piece of a stack designed to make each part of the testing workflow cheap instead of painful. Adopt TWD and you get:

Tests that run in your real browser, with a live sidebar as you develop.
A CI pipeline that's a few lines of YAML away.
Coverage collected without a separate configuration fight.
Mocks that double as contract probes, validated against your OpenAPI spec on every run.

The opportunity isn't just catching drift. It's that once you're in the TWD stack, everything above comes with it — and each piece is an afternoon of setup, not a quarter of migration.

More details and the full config reference live at twd.dev/contract-testing. The project is on GitHub at BRIKEV/twd. If you find a bug in the validator or want a new format supported, PRs welcome.

Guide to AI-Powered Frontend Testing with TWD

Kevin Julián Martínez Escobar — Sun, 19 Apr 2026 10:54:42 +0000

If you've ever watched an AI assistant generate a test file and thought "that looks right" only to spend the next twenty minutes fixing imports, selectors, and mock shapes — this series is for you.

TWD (Test While Developing) is an in-browser testing library built around a simple idea: tests should run inside your real application, against the real DOM, while you develop. No jsdom. No simulated environments. Just your app, a sidebar showing results in real time, and instant feedback as you code.

Over the past year, TWD has grown into a full ecosystem — and the part that changed everything is the AI workflow. A set of skills for Claude Code that let an AI agent write tests, execute them in your browser, fix failures, set up CI, find gaps in your coverage, grade the quality of your tests, and generate visual documentation for your whole team.

This series walks through each piece, in the order you'd use them.

What the Series Covers

1. Stop Letting AI Write Untestable Code. Add Determinism Back with TWD

The starting point. Run /twd:setup to analyze your project, answer a few questions, and generate .claude/twd-patterns.md — a configuration file that teaches the AI agent your project's testing conventions. Framework detection, API patterns, auth middleware, third-party modules — all captured in one file.

2. Your AI Doesn't Just Write Tests. It Runs Them Too

The core of the workflow. The /twd skill writes tests based on your project patterns, sends them to your browser via WebSocket, reads pass/fail results, and iterates until they're green. No screenshots, no heavy payloads — just a tight write-run-fix loop.

3. From Local Tests to CI in One Command

Once you have tests, /twd:ci-setup detects your project configuration and generates a GitHub Actions workflow using the official twd-cli action. Coverage, contract validation, Puppeteer setup — handled automatically.

4. Your Tests Are Running — But Are They Covering the Right Things?

The /twd:test-gaps skill scans your routes, cross-references them against your test files, and classifies each one as tested, partially tested, or untested. High-risk routes with mutations or permissions are flagged first so you know where to focus.

5. Your Tests Pass. But Are They Good?

Having tests is not the same as having good tests. The /twd:test-quality skill grades each test file across four dimensions: journey coverage, interaction depth, assertion quality, and edge case handling. Each file gets a letter grade and actionable suggestions.

6. Turning Your Test Suite Into a Visual Map Your Whole Team Can Read

The final piece. The /twd:test-flow-gallery skill generates Mermaid flowcharts and plain-language summaries from your test files. New developers can understand coverage without reading code. Product can see which user journeys are validated. QA can spot gaps at a glance.

The Philosophy Behind It

TWD is built on a simple principle: automate what you already verify manually. If you check that a form submits correctly by filling it out in the browser, that's your test. TWD just makes it repeatable.

The AI workflow extends that same idea. Instead of writing tests after the fact, the agent writes them as part of the development process — using your conventions, running them against your real app, and iterating until they pass.

The philosophy hasn't changed. What changed is that now your AI agent tests while developing too.

Getting Started

Install the TWD AI plugin for Claude Code:

claude plugin marketplace add BRIKEV/twd-ai
claude plugin install BRIKEV/twd-ai

Then run /twd:setup in your project to kick things off. The rest of the series follows from there.

Full documentation: twd.dev

Source: github.com/BRIKEV/twd-ai

Turning Your Test Suite Into a Visual Map Your Whole Team Can Read

Kevin Julián Martínez Escobar — Sun, 19 Apr 2026 10:49:42 +0000

You have written the tests. The CI pipeline runs them. The gap analysis has helped you fill the blind spots. Quality checks are passing. The work is solid.

And yet — ask a product manager what your test suite actually covers, and you will get a blank stare. Ask a new developer which user flows are tested, and they will spend an hour reading test files to piece it together. Ask QA to verify the coverage makes sense, and they will ask for a document that does not exist.

This is the last problem the TWD AI workflow solves. And it is not a small one.

The Gap Between Tests and Understanding

Test code is written for machines to execute. It is dense, technical, and full of implementation detail. A test that reads:

await twd.mockRequest('getTodos', { method: 'GET', url: '/api/todos', response: [{ id: 1 }, { id: 2 }], status: 200 });
await twd.mockRequest('createTodo', { method: 'POST', url: '/api/todos', response: { id: 3 }, status: 201 });
await twd.visit('/todos');
await twd.waitForRequest('getTodos');

const user = userEvent.setup();
const titleInput = await screenDom.findByLabelText('Title');
await user.type(titleInput, 'New todo');
const descInput = await screenDom.findByLabelText('Description');
await user.type(descInput, 'A new task');
const dateInput = await screenDom.findByLabelText('Date');
await user.type(dateInput, '2026-04-15');
const createButton = await screenDom.findByRole('button', { name: /create todo/i });
await user.click(createButton);

const rule = await twd.waitForRequest('createTodo');
expect(rule.request).to.deep.equal({ title: 'New todo', description: 'A new task', date: '2026-04-15' });

...tells a developer exactly what is being tested. It tells a product manager nothing. And for a new team member, figuring out what user journeys are covered means reading through dozens of files like this and piecing it together mentally.

The /twd:test-flow-gallery skill generates that picture for you.

What the Skill Produces

Running /twd:test-flow-gallery in Claude Code (with the TWD AI plugin installed) analyzes your TWD test files and generates two things for each test file it finds:

Mermaid flowcharts — one per test case. Each chart uses a consistent visual grammar:

Blue rectangles for user actions (clicks, form inputs, navigation)
Green hexagons for assertions (what the test verifies is true)
Separate subgraphs for API calls made during the test

Business-friendly summaries — plain language descriptions of what each test verifies. No function names, no selector syntax. Just: "A user fills out the create todo form with a title, description, and date, then clicks Create Todo. The form data is sent to the server as a new todo."

Here is an example of the flowchart generated from the code above:

The result is a .flows.md file colocated next to each test file, plus a root-level index that gives you a single navigation point across the entire test suite.

Who Actually Benefits From This

New developers can understand what is covered without reading a single line of test code. On day one, they can open the flow gallery and see the user journeys the team has validated. That is faster onboarding and fewer "wait, is this tested?" conversations in code review.

Product teams finally have visibility into testing. Not a coverage percentage — an actual map of user journeys. When they ask "are we testing the checkout flow?", the answer is a link, not a meeting.

QA engineers can identify gaps at a glance and verify that what is visually described matches what they expect to be covered. They can spot missing edge cases by looking at the flows rather than reading assertions.

Running It

With the TWD AI plugin installed, you run:

/twd:test-flow-gallery

That is it. The skill finds your TWD test files, processes them, and writes the .flows.md files alongside your tests. The root index is placed at a predictable location so you can link to it from your README or project wiki.

The flowcharts use standard Mermaid syntax, which renders natively on GitHub, GitLab, Notion, and most modern documentation tools. No extra dependencies, no build step.

The Complete TWD AI Workflow

This skill is the finale of a six-step workflow that takes you from zero to a fully automated, AI-assisted testing practice:

/twd:setup — Scaffolds the TWD testing environment in your project
/twd (twd skill) — AI agent that writes and runs in-browser tests against live components
/twd:ci-setup — Wires your tests into CI/CD with the headless runner
/twd:test-gaps — Identifies untested user flows and generates missing tests
/twd:test-quality — Reviews your tests for reliability, false positives, and maintenance burden
/twd:test-flow-gallery — Turns your test suite into visual documentation for the whole team

Each step builds on the last. The result is a test suite that is not just green in CI — it is legible, maintainable, and understood by everyone who needs to understand it.

Try It

The TWD AI plugin is open source and available at github.com/BRIKEV/twd-ai. The full TWD documentation, including the philosophy behind test-while-developing, is at twd.dev.

If you have been following this series, you now have the full picture. If you are coming to this article first — the rest of the series walks through each step in detail. Start at the beginning and build the workflow incrementally.

Testing should not be a black box. Your team deserves to see what is covered.

DEV Community: Kevin Julián Martínez Escobar

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

1. Setup

2. The standalone runner

3. Component testing vs full app flows

4. Network mocking

5. CI and coverage

Conclusion

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

Setup

1. Inject the sidebar in app.vue

2. Reload the browser when a test file changes

Testing against the real backend

Try it

Playwright vs TWD: A Frontend Developer's Honest Comparison

The first thing you notice: where the tests live

The feedback loop

The debugging story (and why it matters more now)

What you get without having to build it

How they actually compose

What the session left me with

Frontend with AI: workflow first, agent second

The problem: AI amplifies what you already have

The proposal: define the workflow first

The piece that makes it click: TWD

The flow, phase by phase

The rules for structuring tests

Closing

The easiest way to test React Router v7 apps

Setup

A fallback /testing route

Writing a route-level test

Backend tests: any runner works

Why this works: same utility, different environment

Try it

Testing TanStack Router + Query apps in the real browser

The setup is two Vite plugins

Writing a test

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

The relay: how anything can run your tests

Try it

TWD setup is now two Vite plugins and zero app code

The new setup

What it replaces

Why it matters

Non-Vite projects

Try it

Two test runtimes, two coverage reports, one fragile merge

Two runtimes, two coverage outputs

What TWD does differently

When to reach for which

The real win

Testing Payment Flows Without the Payment SDK

Test What You Own. Mock What You Don't.

The Problem

Step 1: Separate the SDK from the Logic

Step 2: Wrap for Mocking

Step 3: Build the Mock

Step 4: Test Everything

What This Pattern Gives You

Conclusion

When Your Mocks Lie: Contract Testing with TWD

The problem contract testing solves

What TWD does about it

Setting it up

1. Get the OpenAPI spec

2. Configure TWD

3. Decide the mode

The TWD ecosystem

The payoff: what the output looks like

Why this matters more than it looks

Wiring it into CI

Conclusion

Guide to AI-Powered Frontend Testing with TWD

What the Series Covers

The Philosophy Behind It

Getting Started

Turning Your Test Suite Into a Visual Map Your Whole Team Can Read

The Gap Between Tests and Understanding

What the Skill Produces

A fallback `/testing` route