TWD (Test While Developing)

Frontend tests that run in your real browser. Same DOM, same routes, same state as your dev server. For React, Vue, Angular, and Solid.

The problem

Testing gets pushed to next week, and next week never comes. When it does happen, tests usually run in a different environment from where you're building, so testing feels like overhead the moment you finish a feature.

The tooling pushes you the same way. You end up writing more code for the tests than for the feature itself, between setup, mocks, and helpers. Adding tests starts to feel like shipping a second app on top of the one you already finished.

As AI writes more of your code, the gap widens. Agents generate test files that look correct but never actually execute in a real browser. The mocks those tests rely on quietly drift from the real API over time. Fields get renamed, mocks stay frozen, tests pass, production breaks.

The solution

TWD puts tests inside your dev server. A sidebar appears in your real browser, runs tests against the same DOM your users see, and updates as you code. When you're ready, plug in an AI agent that writes tests, runs them via a WebSocket bridge, and iterates until they pass. When you ship, validate every mock against your OpenAPI spec to catch drift before a user does.

Test what you own. Mock what you don't.

Full pitch and docs at twd.dev.

Quick start

npm install --save-dev twd-js

Add the Vite plugin (auto-loads the sidebar and discovers your test files):

// vite.config.ts
import { defineConfig } from 'vite'
import { twd } from 'twd-js/vite-plugin'

export default defineConfig({
  plugins: [twd({ open: true })],
})

Write a test next to your code:

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

describe('App', () => {
  it('shows the heading', async () => {
    await twd.visit('/')
    const heading = await screenDom.findByRole('heading', { level: 1 })
    twd.should(heading, 'be.visible')
  })
})

Run npm run dev and open the app. The TWD sidebar appears in your browser; click play to run the test.

→ Full setup guide · Framework integration (Angular, non-Vite, Astro, React Router)

The TWD ecosystem

One package today. The rest when you need it.

Tool	What it does
twd-js	The core sidebar. Frontend tests that run in your real browser.
twd-relay	Token-efficient browser testing for AI agents. Structured pass/fail over WebSocket. No Playwright, no screenshots.
twd-cli	Headless CI runs with coverage and OpenAPI contract validation.

Examples & showcase

• twd-shadcn: React + shadcn/ui with a live demo you can interact with
• twd-react-router: React Router (Framework Mode) with createRoutesStub and loader mocking
• twd-tanstack-example: TanStack Router integration
• twd-vue-example: Vue 3
• twd-angular-example: Angular
• twd-auth0: Auth0 session mocking

→ All examples and community content

Documentation

• Getting Started: Install, set up, write your first test
• Writing Tests: Selectors, assertions, interactions, navigation
• API Mocking: Built-in request mocking via service worker
• AI Integration: Connect Claude Code (or any agent) via twd-relay
• Contract Testing Setup: Validate mocks against OpenAPI specs in CI
• API Reference: Test functions, commands, assertions

Contributing

Open issues or pull requests on GitHub. If you're starting out in tech and looking for a beginner-friendly first PR, see the open issues. Reach out and the maintainer will help with setup and walk you through it.

Contributors ✨

Kevin Julián Martínez Escobar 💻

Javier Rodriguez 📖

Guillermo Ruiz Arranz 💻

Roberto Gomez Fabrega 📖

This project follows the all-contributors specification. Contributions of any kind are welcome.

License

MIT