Frontend testing ecosystem

Testing isn't a phase.It's how you build.

Write tests while you develop, in your real browser. Let the AI agent iterate. Validate every mock against the real API before you merge.

Get Started View on GitHub
TWD sidebar showing passing tests in the browser

Testing is always last

Every sprint, testing gets pushed to "next week." Next week never comes. The codebase grows. The debt compounds.

AI writes tests that don't run

Your agent generates test files. They look correct. They never execute in a real browser. No one notices until someone does.

Your mocks lie

The backend renames a field. Your mock doesn't know. Tests pass. Production breaks. You find out from a user.

The TWD Ecosystem

All optional. All composable. Start with the sidebar, add what you need.

CORE

DEVELOP + TEST

twd-js

Sidebar in your browser

optional

AI AGENT

twd-relay + twd-ai

Write, run, fix, repeat

optional

CI PIPELINE

twd-cli

Headless tests + coverage

optional

VALIDATE CONTRACTS

openapi-mock-validator

Every mock vs the real spec

SHIP

Merge with confidence

Contracts validated, tests green

Quick Start

Install and add to your entry point

terminal
npm install twd-js
src/main.tsx
// Only load TWD in development
if (import.meta.env.DEV) {
  const { initTWD } = await import('twd-js/bundled');
  const tests = import.meta.glob("./**/*.twd.test.ts");
  initTWD(tests, { open: true });
}

Write a test

src/App.twd.test.ts
import { twd, userEvent, screenDom } from "twd-js";
import { describe, it } from "twd-js/runner";

describe("App", () => {
  it("should render the heading", async () => {
    await twd.visit("/");
    const heading = screenDom.getByRole("heading", { level: 1 });
    twd.should(heading, "be.visible");
  });
});

Run your dev server and see results

terminal
npm run dev

The sidebar appears in your browser. Click play to run any test.

TWD sidebar showing passing tests in the browser

Frequently Asked Questions

How is this different from Playwright/Cypress?

TWD validates your frontend UI logic with mocked boundaries. Playwright/Cypress validate that your systems work together end-to-end. They complement each other — TWD for fast deterministic feedback during dev, E2E for full integration in CI.

How is this different from Vitest Browser Mode?

Vitest Browser runs unit/component tests in a browser but in isolation from your app. TWD runs inside your actual dev server — same page, same routes, same state. You test what the user sees, not a mounted component in a vacuum.

Does this replace Testing Library?

No. TWD uses Testing Library under the hood. screenDom is a scoped wrapper around Testing Library queries. You get the same semantic selectors — TWD just adds the runner, sidebar, and mocking layer on top.

What frameworks are supported?

React, Vue, Angular, and Solid.js. Anything Vite-based. Not compatible with SSR-first architectures like Next.js App Router (the testing boundary becomes unclear when the server owns rendering).

Can AI actually write good tests?

The twd-ai plugin doesn't just generate test files. It runs them, reads real failures, fixes them, checks quality, and finds gaps. The tests execute in a real browser — if they pass, they mean something. And because results come back as structured text over WebSocket (not screenshots or DOM snapshots), token usage is significantly lower than tools like Playwright MCP.

Does TWD code ship to production?

No. All TWD imports are guarded by import.meta.env.DEV. Nothing reaches your production bundle.

TWD isn't about writing more tests — it's about writing the right ones, at the right time.
Read the full manifesto →
$ npm install twd-js
Get started