# TWD (Test While Developing) - Full Documentation
> In-browser frontend testing for React, Vue, Angular, Solid, Astro, Nuxt, HTMX and vanilla JS. Runs in your real browser via Vite, Webpack, or a CDN. This file concatenates the full TWD documentation for LLM ingestion. For a concise index, see https://twd.dev/llms.txt.
# TWD Manifesto
Source: https://twd.dev/twd-manifesto
**Test While Developing** (TWD) is a mindset, not a checklist.
It's about writing tests as you build — not afterward, not someday, not just when you're done.
TWD is for developers who want faster feedback, deeper confidence, and fewer regressions — without the ceremony of traditional testing philosophies.
---
## Principles
1. **Write tests while building, not after**
Testing is part of the development flow — not something you add at the end.
2. **Keep your test runner open**
Let your tests run continuously while coding to get fast, meaningful feedback.
3. **Automate what you already check manually**
If you're repeating a check by hand, it's a good candidate for a test.
4. **Let real use guide what you test**
Focus on the behaviors and flows your users actually rely on.
5. **Use coverage to find gaps, not for validation**
Don't chase numbers — use coverage tools after the fact to spot what you missed, not to prove anything.
6. **Prefer fast feedback over strict structure**
Don't get stuck on test types or formats — prioritize feedback that helps you move forward.
7. **Test what you own, mock what you don't**
Focus on testing your own code and logic. External services, third-party APIs, and dependencies you don't control should be mocked — not tested.
8. **Design features to be easy to validate**
Write code that's naturally testable and easy to observe as you develop.
---
> TWD isn't about writing *more* tests — it's about writing the *right* ones, at the right time.
# Rethinking Testing - Why I Test While Developing
Source: https://twd.dev/motivation
These days, we're surrounded by tools that help us move faster — frameworks, CLIs, even AI that writes code for us. It's never been easier to build.
And yet, despite all that speed, many teams still struggle with something fundamental: **testing**.
Think about it:
You build a feature. You check that it works — maybe in the browser, maybe with an API call, maybe by looking at the database.
In your mind, the **feature is done**.
Then someone says:
> "Now let's add some tests."
And suddenly, what felt complete now feels like overhead.
Why write more code to prove something you just confirmed manually?
## Why Testing Still Gets Left Behind
This frustration isn't rare — it's a symptom of how we've been taught to think about testing.
Ask someone about testing and you'll often hear:
- "We didn't have time to add tests."
- "TDD just slows me down."
- "I test manually and it works, why write more code?"
And to be fair, they're not entirely wrong.
Testing often feels like a **separate task** — something formal and rigid that comes after development. It's rarely part of the same flow. We switch mental gears, bring in new tools, write boilerplate... and all to confirm something we already verified manually.
No wonder it feels like overhead.
But the problem isn't testing itself — it's the **disconnect between building and testing**.
## Testing Should Be Part of Development, Not a Chore
What if, instead of treating testing as a separate step, we just **automated the same checks** we're already doing during development?
I think about testing the same way I think about committing code: it's not optional, it's just part of getting the job done.
But here's the catch — to make that work, we need to **stop treating testing as a set of rituals**. Forget about the pyramid, about whether it's unit, integration, or E2E. Forget about TDD or BDD. Instead, ask yourself:
- What am I building right now?
- How do I manually check that it works?
- How can I automate **that exact validation**?
That's your test. That's the mindset.
## Example: Building an API Endpoint
Let's say you're developing an API endpoint that inserts in a database and returns the inserted data.
Typical workflow:
1. Write the endpoint code.
2. Test it manually in Postman.
3. Add the DB insert logic.
4. Check the data in your DB client.
5. Verify the final response again in Postman.
Cool, it works. But now someone asks you to "add tests." You feel resistance — **why repeat all that work** when you already know it works?
So maybe you write a unit test for some internal function… or you try to mock the DB in an integration test. Either way, it's an extra effort for something you've already tested manually.
## The Alternative: Test While Developing
Instead of starting with tests like in strict TDD, or leaving them for later (which often means never), **I take a different route**.
I build the feature as I normally would, but I replace every manual step with a test.
For example:
1. Create the endpoint.
2. Instead of opening Postman, write a test that calls the endpoint the same way Postman would (Supertest in node for example).
3. Add the DB logic.
4. Instead of checking your DB with a client like DBeaver, include tools in your test to validate your database.
5. Instead of manually verifying the response, assert it with your test framework.
You've just automated the exact checks you would've done manually. No extra work — **just redirected effort**. These tests stick around, and they run every time the code changes.
Yes, it's a bit more work at first — and you'll probably hit some friction the first few times. But it pays off quickly. You're **not doing extra work** — you're just turning your manual checks into repeatable ones.
## It Scales and Teaches Well
This approach comes with a lot of side benefits:
- You get real coverage of actual business logic.
- Onboarding juniors is easier — they can read working tests that mirror how features work.
- You don't need to explain how to test things manually — the tests are the documentation.
- Plus, you still get all the classic benefits of having tests: safer refactors, faster debugging, and fewer regressions.
## What About Frontend?
For frontend development, I use **TWD** — a testing library designed specifically for this philosophy.
Instead of waiting for the full app to be ready or relying on real backends, TWD runs tests directly in your browser during development. You get a beautiful sidebar that shows test results in real-time as you code. I use a built-in service worker to mock API responses, so I can develop and test features without needing a running backend.
That's right — I'm not running tests in a separate terminal or waiting for CI. I'm building and testing in the same environment, with instant feedback right in my browser.
Some might say "that's not how traditional testing works."
But we're not here to follow tradition — **we're here to build solutions**. And TWD gives me fast feedback, solid coverage, and minimal extra effort. It's testing while developing, not testing after developing.
## What About Traditional Tests?
Yes, you should still do those too — once the main work is done.
Here's where **coverage tools** come in. Not as a vanity metric, but as a checklist. Once your "test while developing" tests are done, run coverage to see what's missing. Then fill in the gaps with more traditional unit, integration, or even property-based tests.
## What Changes in the AI Era
Now that AI is generating a big portion of our frontend code, everything we've talked about matters even more.
Speed is no longer the bottleneck — **confidence is**.
AI can produce features fast, but it doesn't know your project the way you do. It doesn't know what should be mocked, how your auth works, or what "good tests" look like in your codebase. Without that context, AI-generated tests are generic, inconsistent, and sometimes useless.
That's why TWD now includes an [AI Workflow](/twd-ai/setup) — a set of skills that give the AI agent your project context, your testing patterns, and your rules. The AI writes tests that actually fit your architecture, executes them in your real browser, and iterates until they pass.
The philosophy hasn't changed. The principles still apply. But now, instead of just *you* testing while developing, **your AI agent tests while developing too** — with the same mindset, the same patterns, and the same confidence.
## Final Thoughts
Testing isn't a separate phase of development. It's not an extra burden. It's a **different way of thinking** about the same job.
Stop trying to follow someone else's test strategy. Just ask:
> How do I know this works?
Then automate that answer.
That's it. That's my philosophy. Test while developing.
# Frontend tests that run in your real browser — TWD
Source: https://twd.dev/twd-js
## The problem
Testing gets pushed to next week. Next week never comes.
The reason isn't that you don't care — it's that testing usually runs in a different environment from where you're building. You write a feature, check it works in the browser, then context-switch to a different tool to "add tests." Suddenly what felt complete feels like overhead.
twd-js fixes this by putting the tests where the feature lives: in your real browser, in your real dev server, with a sidebar that updates as you code.
## How it works
You install `twd-js`, add the Vite plugin, and write tests next to your code in `*.twd.test.ts` files. When you run `npm run dev`, the TWD sidebar appears in your browser. Click play to run any test. Tests use the same DOM, routes, and state your users will — there's no separate test environment to keep in sync.
Selectors come from Testing Library (`screenDom.findByRole`, `findByLabelText`, …); assertions are chainable (`twd.should(el, 'be.visible')`). Mocking is built in: `twd.mockRequest(...)` intercepts fetch/XHR via a service worker so you can develop and test features without a running backend.
Nothing TWD ships to production — every `twd-js` import is dev-only (`import.meta.env.DEV`-guarded), so your prod bundle is untouched.
## Quick start
```bash
npm install --save-dev twd-js
```
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { twd } from 'twd-js/vite-plugin'
export default defineConfig({
plugins: [twd({ open: true })],
})
```
```ts
// 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 sidebar appears in your browser; click play to run the test.
# Token-efficient browser testing for AI agents — TWD
Source: https://twd.dev/twd-relay
## The problem
AI agents write test files that look correct, then never execute them in a real browser. No one notices until production does.
The other half of the problem: when agents *do* try to run browser tests, they usually reach for Playwright or Puppeteer MCP. Those tools talk back in screenshots and DOM dumps, and the payloads are huge. A single test run can burn thousands of tokens on visual diffs the agent can't really reason about.
twd-relay fixes both halves. It runs in the dev server you already have open, and it streams structured pass/fail events back over a WebSocket. Text, not pixels.
## How it works
`twd-relay` is a WebSocket server that routes messages between your **browser** (where TWD is loaded) and an **external client** (an AI agent, a script, or the bundled `twd-relay run` CLI).
```
┌───────────────┐ WebSocket ┌──────────────────┐ ┌───────────────────┐
│ AI Agent │◄──────────────────►│ Relay Server │◄──────────────►│ Browser (TWD) │
│ (Claude Code,│ /__twd/ws │ (Vite plugin or │ │ Test runner + │
│ script) │ │ standalone) │ │ sidebar UI │
└───────────────┘ └──────────────────┘ └───────────────────┘
```
The agent sends `{ type: "run", scope: "all" }`; the relay forwards it to the browser; TWD runs the tests; per-test events stream back; the relay closes with `run:complete`. The agent reads pass/fail/skip counts, opens failing test names, fixes the code, and runs again. A tight write/run/read/fix loop with no browser automation runtime, no screenshots, and a tiny token footprint per iteration.
## Quick start
```bash
npm install --save-dev twd-relay
```
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { twd } from 'twd-js/vite-plugin'
import { twdRemote } from 'twd-relay/vite'
export default defineConfig({
plugins: [
twd(), // sidebar + test discovery
twdRemote(), // relay endpoint + auto-injected browser client
],
})
```
Add a line to your agent's instructions file (e.g. `CLAUDE.md`):
```text
To run TWD tests: npx twd-relay run
Exit code 0 means all tests passed; 1 means failures or errors.
```
That's it. Start `npm run dev`, leave the tab open, and your agent can drive tests on demand.
# Validate every mock against your OpenAPI spec — TWD
Source: https://twd.dev/contract-testing
## The problem
Frontend teams write mock responses in tests that drift from reality over time. Fields get renamed, removed, or added in the API — but mocks stay frozen. Tests pass, code ships, and the app breaks in production.
Contract testing closes this gap: **test what you own, mock what you don't — then validate the mocks.**
## How it works
During the test run, TWD collects every mock registered via `twd.mockRequest()`. After tests complete, `twd-cli` validates those mocks against your OpenAPI specs. Each mock either matches the spec (✓), fails (✗) with the precise field that broke, or warns (⚠) when the status code or schema isn't documented yet.
You pick the mode per spec. `"error"` fails the test run (use this for stable endpoints you trust). `"warn"` reports but doesn't fail (use this while you're catching up to a moving target). When the GitHub Action runs in CI, a summary table is posted as a PR comment so the breakage is visible to the reviewer, not just to whoever scrolled the CI log.
## Quick start
```bash
npm install --save-dev twd-cli
```
```json
// twd.config.json
{
"url": "http://localhost:5173",
"contractReportPath": ".twd/contract-report.md",
"contracts": [
{
"source": "./contracts/users-3.0.json",
"baseUrl": "/api",
"mode": "error",
"strict": true
}
]
}
```
## What you see in CI
After `npx twd-cli run` finishes, contract validation results print alongside the test output:
```
$ npx twd-cli run
Running TWD tests in headless browser…
✓ Users page > shows users
✓ User detail > shows address
✓ Counter > increments on click
3 passed, 0 failed (0.4s)
Validating mocks against OpenAPI specs…
Source: ./contracts/users-3.0.json ERROR
✓ GET /users (200) — mock "getUsers"
✗ GET /users/{userId} (200) — mock "getUserBadAddress"
→ response.address.city: missing required property
→ response.address.country: missing required property
⚠ GET /users/{userId} (404) — mock "getUserNotFound"
Status 404 not documented for GET /users/{userId}
Contract report written to .twd/contract-report.md
```
With the GitHub Action, the same summary is posted as a PR comment so failed validations surface in the reviewer's queue, not just the CI log.
[Full setup, options, validations, and PR reports →](/contract-testing-setup)
# Getting Started
Source: https://twd.dev/getting-started
Welcome to TWD (Test While Developing)! This guide will help you set up TWD in your application and write your first test. TWD is a deterministic browser validation layer for your frontend boundaries. It works with any frontend that renders in the browser: SPAs (React, Vue, Angular, Solid), hydrated SSR (React Router, Nuxt), Astro islands, and no-build projects (HTMX, vanilla JS) via a CDN, on Vite, Webpack, or no bundler at all.
## Installation
Install TWD using your preferred package manager:
::: code-group
```bash [npm]
npm install --save-dev twd-js
```
```bash [yarn]
yarn add --dev twd-js
```
```bash [pnpm]
pnpm add -D twd-js
```
:::
::: tip No build step? Use a CDN
Plain HTML pages, static sites, and [HTMX](https://htmx.org/) projects can load TWD from a CDN with no bundler and no install, using an import map. See [Vanilla JS](/frameworks#vanilla-js-cdn-no-bundler) and [HTMX](/frameworks#htmx-cdn-no-bundler) in the framework guide.
:::
## Quick Setup
### 1. Add the Vite Plugin
For Vite-based projects (React, Vue, Solid.js, and other Vite-native frameworks), add the `twd()` plugin to your `vite.config.ts`. The plugin auto-loads the sidebar and discovers test files in dev — no entry-file changes required.
```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react'; // or vue, solid, etc.
import { twd } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
react(),
twd({
testFilePattern: '/**/*.twd.test.{ts,tsx}',
open: true,
position: 'left',
search: true, // Enable search/filter in the sidebar (default: false)
pace: true, // Enable the execution speed selector (default: false)
serviceWorker: true, // Enable request mocking (default: true)
serviceWorkerUrl: '/mock-sw.js', // Custom service worker path (default: '/mock-sw.js')
// rootSelector: '#my-app', // (Optional) Override the app root for screenDom queries
}),
],
});
```
The plugin only runs in `vite dev` (`apply: 'serve'`), so production builds never include any TWD code.
::: tip Using Angular or another non-Vite tool?
Skip to [Manual setup for non-Vite projects](#manual-setup-for-non-vite-projects) below.
:::
### 2. Set Up the Service Worker (Optional but recommended)
If you plan to use API mocking, set up the mock service worker:
```bash
npx twd-js init public
```
This copies the required `mock-sw.js` file to your public directory.
### 3. Write Your First Test
Create your first test file:
```ts
// src/App.twd.test.ts
import { twd, userEvent, screenDom } from "twd-js";
import { describe, it } from "twd-js/runner";
describe("App Component", () => {
it("should render the main heading", async () => {
await twd.visit("/");
// Use screenDom for testing library queries
const heading = screenDom.getByRole("heading", { level: 1 });
twd.should(heading, "be.visible");
});
it("should handle button clicks", async () => {
await twd.visit("/");
const user = userEvent.setup();
const button = screenDom.getByRole("button");
await user.click(button);
// Add your assertions here
const result = screenDom.getByText("Button clicked!");
twd.should(result, "be.visible");
});
});
```
### 4. Run Your App
Start your development server as usual:
```bash
npm run dev
```
You should now see the TWD sidebar in your browser automatically in development mode. Click on it to view and run your tests!
## Manual setup for non-Vite projects
If your project doesn't use Vite (e.g. Angular CLI, Webpack, custom bundler), initialize TWD manually in your dev entry point. The `twd()` Vite plugin doesn't apply here, but the underlying `initTWD` API works the same way the plugin does internally.
```tsx
// src/main.tsx (or main.ts)
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App';
// Only load the test sidebar and tests in development mode
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',
search: true, // Enable search/filter in the sidebar (default: false)
pace: true, // Enable the execution speed selector (default: false)
serviceWorker: true, // Enable request mocking (default: true)
serviceWorkerUrl: '/mock-sw.js', // Custom service worker path (default: '/mock-sw.js')
// rootSelector: '#my-app', // (Optional) Override the app root for screenDom queries
});
}
createRoot(document.getElementById('root')!).render(
,
);
```
The bundled setup ships React internally, so it works with any framework — the entry-file integration is the only difference.
## File Naming Convention
We recommend naming your test files using the following patterns:
- `*.twd.test.ts`
- `*.twd.test.tsx`
- `*.twd.test.js`
- `*.twd.test.jsx`
You can customize this pattern in your test loader using different glob patterns.
## Development Workflow
1. **Write tests** alongside your components
2. **Run tests** using the browser sidebar
3. **See instant feedback** as you develop
4. **Mock external systems** (APIs, auth, feature flags) for deterministic results
5. **Iterate quickly** with live reloading
## Next Steps
- Learn about [Writing Tests](/writing-tests) in detail
- Explore [API Mocking](/api-mocking) capabilities
- Follow the [Tutorial](/tutorial/) for step-by-step learning
- Browse the [API Reference](/api/) for all available methods
## Troubleshooting
### Tests Not Loading
Make sure you:
1. Are running in development mode (`vite dev` / `import.meta.env.DEV` is true)
2. Used a file name that matches your `testFilePattern`. The default is
`'/**/*.twd.test.ts'`, which matches `.ts` only. If your tests are `.tsx` or
`.jsx`, set `twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}' })` or they will
be skipped silently.
3. Added `twd()` to the `plugins` array in your `vite.config.ts` (Vite projects), or have the manual `initTWD` logic in your entry file (non-Vite projects)
### Service Worker Issues
If API mocking isn't working:
1. Run `npx twd-js init public` to install the service worker
2. Make sure request mocking is enabled (`serviceWorker: true` is the default in both the plugin and `initTWD`)
3. Check the browser console for service worker registration errors
### Test Duplication on HMR
If you're using the `twd()` Vite plugin, full-reload on test edits is handled automatically — no extra plugin needed.
For manual (non-Vite) setups where you notice test entries duplicating when you edit test files during development, add the TWD HMR plugin alongside `initTWD`:
```ts
// vite.config.ts
import { twdHmr } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
// ... other plugins
twdHmr(),
],
});
```
This plugin forces a full page reload when TWD test files change, preventing duplicate test entries.
## Getting Help
- 📖 [Browse the documentation](/api/)
- 🐛 [Report issues](https://github.com/BRIKEV/twd/issues)
- 💬 [Join discussions](https://github.com/BRIKEV/twd/discussions)
# Writing Tests
Source: https://twd.dev/writing-tests
Learn how to write effective tests with TWD's intuitive API and powerful features.
## Test Structure
TWD uses a familiar testing structure similar to Jest, Mocha, and other popular testing frameworks:
```ts
import { twd, userEvent } from "twd-js";
import { describe, it, beforeEach } from "twd-js/runner";
describe("User Authentication", () => {
beforeEach(() => {
// Reset state before each test
console.log("Setting up test environment");
});
it("should login with valid credentials", async () => {
// Your test logic here
});
it("should show error with invalid credentials", async () => {
// Your test logic here
});
});
```
### Test Functions
| Function | Purpose | Example |
|----------|---------|---------|
| `describe(name, fn)` | Groups related tests | `describe("Login Form", () => {...})` |
| `it(name, fn)` | Defines a test case | `it("should submit form", async () => {...})` |
| `describe.only(name, fn)` | Runs only this suite (and its children) — helpful when debugging a group of tests | `describe.only("Only this suite", () => {...})` |
| `describe.skip(name, fn)` | Skips this suite and all its descendant tests | `describe.skip("Skipped suite", () => {...})` |
| `it.only(name, fn)` | Runs only this test | `it.only("debug this test", () => {...})` |
| `it.skip(name, fn)` | Skips this test | `it.skip("broken test", () => {...})` |
| `beforeEach(fn)` | Runs before each test | `beforeEach(() => {...})` |
| `afterEach(fn)` | Runs after each test | `afterEach(() => {...})` |
### Nested Describes
You can nest `describe` blocks for better organization:
```ts
describe("User Management", () => {
describe("Registration", () => {
it("should create new user", async () => {
// Registration tests
});
});
describe("Login", () => {
it("should authenticate user", async () => {
// Login tests
});
});
});
```
## Element Selection
TWD provides multiple ways to select DOM elements. **Prefer Testing Library's async `findBy*` queries.** They are the recommended way to select elements in TWD, ahead of `getBy*`/`queryBy*` and ahead of TWD's native `twd.get()`.
::: tip Testing a single component instead of a page?
If you render a component in isolation with Testing Library's `render()`, use
`screen` rather than `screenDom`. See [Component Testing](/component-testing#queries).
:::
### Recommended: `findBy*` queries
> **Always reach for `findBy*` first.**
>
> - **`findBy*` (recommended)**: returns a promise and **waits** for the element to appear. Because UI in a real app renders asynchronously (after navigation, data fetches, state updates, or re-renders), `findBy*` is the most reliable choice and avoids flaky tests.
> - **`getBy*`**: synchronous; throws immediately if the element isn't already in the DOM. Only use it when you're certain the element is already rendered.
> - **`queryBy*`**: synchronous; returns `null` if not found. Use it **only** when you intentionally want to assert that an element is *absent*.
>
> Default to `findBy*`. Use `findBy*` over `twd.get()` too, since Testing Library's semantic queries are more accessible and resilient than CSS selectors.
```ts
// ✅ Recommended: waits for the element to appear
const successMessage = await screenDom.findByText("Login successful!");
const submitButton = await screenDom.findByRole("button", { name: /sign in/i });
// ⚠️ Synchronous: throws if not already in the DOM
const heading = screenDom.getByRole("heading", { name: "Welcome" });
// ⚠️ Only to assert absence
const error = screenDom.queryByText("Error");
expect(error).to.equal(null);
```
### Testing Library Queries
TWD supports Testing Library's query methods through two APIs:
1. **`screenDom`** - Scoped queries that exclude the TWD sidebar (recommended for most cases)
2. **`screenDomGlobal`** - Global queries for portal-rendered elements (modals, dialogs)
#### Import
```ts
import { screenDom, screenDomGlobal } from "twd-js";
```
#### When to Use screenDom vs screenDomGlobal
**Use `screenDom` (default):**
- For regular page content within your app
- Automatically excludes sidebar elements
- Recommended for most queries
**Use `screenDomGlobal`:**
- For portal-rendered elements (modals, dialogs, tooltips)
- When you need to search outside the root container
- ⚠️ **Important:** Use specific selectors (e.g., `getByRole` with `name`) to avoid matching sidebar elements
#### Query by Role (Recommended)
```ts
// Find button by role and accessible name (waits for it to appear)
const submitButton = await screenDom.findByRole("button", { name: /submit/i });
const heading = await screenDom.findByRole("heading", { name: "Welcome", level: 1 });
// Find form elements
const emailInput = await screenDom.findByRole("textbox", { name: /email/i });
const checkbox = await screenDom.findByRole("checkbox", { name: /terms/i });
```
#### Query by Label
```ts
// Find inputs by their labels (most accessible)
const emailInput = await screenDom.findByLabelText("Email Address:");
const searchInput = await screenDom.findByLabelText(/search/i);
```
#### Query by Text
```ts
// Find elements by text content
const title = await screenDom.findByText("Welcome to TWD");
const partialMatch = await screenDom.findByText(/welcome/i);
```
#### Query by Test ID
```ts
// Find elements by data-testid
const userCard = await screenDom.findByTestId("user-card");
```
#### Query Methods
- **findBy*** *(recommended)* - Returns a promise, **waits** for the element to appear. Use this by default.
- **getBy*** - Returns element or throws immediately if not found. Use only when the element is already rendered.
- **queryBy*** - Returns element or `null` if not found. Use only to assert an element is absent.
- **findAllBy*** *(recommended for lists)* / **getAllBy*** / **queryAllBy*** - Returns an array of elements.
```ts
// ✅ findBy waits for element to appear (recommended)
const successMessage = await screenDom.findByText("Success!");
// findAllBy waits and returns an array
const buttons = await screenDom.findAllByRole("button");
expect(buttons).to.have.length(3);
// getBy throws if element doesn't exist (must already be rendered)
const button = screenDom.getByRole("button");
// queryBy returns null if element doesn't exist (use to assert absence)
const error = screenDom.queryByText("Error");
expect(error).to.equal(null);
```
#### Complete Example with screenDom
```ts
import { screenDom, screenDomGlobal, userEvent, twd } from "twd-js";
import { describe, it } from "twd-js/runner";
describe("Login Form", () => {
it("should submit login form", async () => {
await twd.visit("/login");
// Use screenDom findBy* for semantic queries (regular page content)
const emailInput = await screenDom.findByLabelText("Email:");
const passwordInput = await screenDom.findByLabelText("Password:");
const submitButton = await screenDom.findByRole("button", { name: /sign in/i });
// Use userEvent for interactions
const user = userEvent.setup();
await user.type(emailInput, "user@example.com");
await user.type(passwordInput, "password123");
await user.click(submitButton);
// Wait for success message
const successMessage = await screenDom.findByText("Login successful!");
twd.should(successMessage, "be.visible");
});
it("should handle modal confirmation", async () => {
await twd.visit("/settings");
// Use screenDom findBy* for regular button
const deleteButton = await screenDom.findByRole("button", { name: /delete/i });
const user = userEvent.setup();
await user.click(deleteButton);
// Use screenDomGlobal for modal (rendered via portal)
// ⚠️ Use specific queries to avoid matching sidebar elements
const confirmModal = await screenDomGlobal.findByRole("dialog", {
name: "Confirm Deletion"
});
const confirmButton = await screenDomGlobal.findByRole("button", {
name: "Yes, Delete Account"
});
await user.click(confirmButton);
});
});
```
> **Note:** For complete Testing Library documentation, see the [Testing Library API reference](/testing-library).
### TWD Native Selectors
TWD's native selectors use CSS selectors for simple, direct element access. Prefer Testing Library's `findBy*` queries above; reach for these only when a CSS selector is genuinely the simplest option (for example, selecting by a non-semantic class or a complex structural selector).
#### Single Element Selection
Use `twd.get()` to select a single element:
```ts
// By tag
const button = await twd.get("button");
// By ID
const emailInput = await twd.get("#email");
// By class
const errorMessage = await twd.get(".error-message");
// By attribute
const submitButton = await twd.get("button[type='submit']");
// By data attribute
const userCard = await twd.get("[data-testid='user-card']");
// Complex selectors
const firstListItem = await twd.get("ul > li:first-child");
```
#### Multiple Element Selection
Use `twd.getAll()` to select multiple elements:
```ts
// Get all buttons
const buttons = await twd.getAll("button");
// Get all list items
const listItems = await twd.getAll("li");
// Access specific elements
buttons[0].should("be.visible");
listItems[2].should("contain.text", "Third item");
```
## Assertions
TWD provides a comprehensive set of assertions for testing element states and content. There are two ways to make assertions:
1. **Method style** (`element.should()`) - For elements from `twd.get()` or `twd.getAll()`
2. **Function style** (`twd.should(element, ...)`) - For any element, especially from Testing Library queries
### Using Assertions
#### Method Style (TWD Elements)
Elements returned from `twd.get()` and `twd.getAll()` have a `.should()` method:
```ts
const element = await twd.get("h1");
element.should("have.text", "Welcome");
element.should("be.visible");
```
#### Function Style (Any Element)
Use `twd.should()` for elements from Testing Library queries or any raw DOM element:
```ts
import { twd, screenDom } from "twd-js";
// With Testing Library queries
const button = screenDom.getByRole("button");
twd.should(button, "be.visible");
twd.should(button, "have.text", "Submit");
// With raw DOM elements
const element = document.querySelector(".my-element");
twd.should(element, "contain.text", "Hello");
```
### Text Content Assertions
```ts
// Method style (TWD elements)
const element = await twd.get("h1");
element.should("have.text", "Welcome to TWD");
element.should("contain.text", "Welcome");
element.should("be.empty");
// Function style (Testing Library or raw elements)
const heading = screenDom.getByRole("heading");
twd.should(heading, "have.text", "Welcome to TWD");
twd.should(heading, "contain.text", "Welcome");
// Negated assertions
element.should("not.have.text", "Goodbye");
twd.should(heading, "not.be.empty");
```
### Attribute Assertions
```ts
// Method style
const input = await twd.get("input#email");
input.should("have.attr", "type", "email");
input.should("have.value", "user@example.com");
input.should("have.class", "form-control");
// Function style
const emailInput = screenDom.getByLabelText("Email:");
twd.should(emailInput, "have.attr", "type", "email");
twd.should(emailInput, "have.value", "user@example.com");
twd.should(emailInput, "have.class", "form-control");
```
### Element State Assertions
```ts
// Method style
const button = await twd.get("button");
button.should("be.disabled");
button.should("be.visible");
// Function style
const submitButton = screenDom.getByRole("button", { name: /submit/i });
twd.should(submitButton, "be.enabled");
twd.should(submitButton, "be.visible");
// Checked state
const checkbox = screenDom.getByRole("checkbox");
twd.should(checkbox, "be.checked");
// Selected state
const option = screenDom.getByRole("option", { selected: true });
twd.should(option, "be.selected");
// Focus state
const input = screenDom.getByLabelText("Username:");
input.focus();
twd.should(input, "be.focused");
```
### URL Assertions
```ts
// Exact URL match
await twd.url().should("eq", "http://localhost:3000/dashboard");
// URL contains substring
await twd.url().should("contain.url", "/dashboard");
await twd.url().should("contain.url", "localhost");
// Negated URL assertions
await twd.url().should("not.contain.url", "/login");
```
### chai expect assertions
You can use the `expect` function from the `chai` library to make assertions:
```ts
import { expect, twd } from "twd-js";
// Get all list items
const listItems = await twd.getAll("li");
// Assert array length. These assertions are not displayed in the sidebar logs.
expect(listItems).to.have.length(3);
```
## User Interactions
TWD integrates with `@testing-library/user-event` for realistic user interactions. All user event methods are available and automatically logged in the TWD sidebar:
### Click Events
```ts
import { userEvent } from "twd-js";
const user = userEvent.setup();
const button = await twd.get("button");
// Single click
await user.click(button.el);
// Double click
await user.dblClick(button.el);
// Right click
await user.pointer({ target: button.el, keys: '[MouseRight]' });
```
### Typing and Input
```ts
const user = userEvent.setup();
const input = await twd.get("input#username");
// Type text
await user.type(input.el, "john_doe");
// Clear and type
await user.clear(input.el);
await user.type(input.el, "new_username");
// Type special characters
await user.keyboard(input.el, "Hello{Enter}World{Tab}");
```
### Form Interactions
```ts
const user = userEvent.setup();
// Select dropdown options
const select = await twd.get("select#country");
await user.selectOptions(select.el, "US");
// Multiple selections
await user.selectOptions(select.el, ["US", "CA", "MX"]);
// Checkbox interactions
const checkbox = await twd.get("input[type='checkbox']");
await user.click(checkbox.el); // Toggle
// Radio button selection
const radio = await twd.get("input[value='premium']");
await user.click(radio.el);
```
### File Upload
```ts
const user = userEvent.setup();
const fileInput = await twd.get("input[type='file']");
// Create a mock file
const file = new File(['hello'], 'hello.png', { type: 'image/png' });
// Upload file
await user.upload(fileInput.el, file);
// Multiple files
const files = [
new File(['file1'], 'file1.txt', { type: 'text/plain' }),
new File(['file2'], 'file2.txt', { type: 'text/plain' })
];
await user.upload(fileInput.el, files);
```
## Navigation
### Page Navigation
```ts
// Navigate to different routes
await twd.visit("/");
await twd.visit("/login");
await twd.visit("/dashboard");
// Navigate with query parameters
await twd.visit("/search?q=testing");
// Navigate with hash
await twd.visit("/docs#getting-started");
```
### Waiting
```ts
// Wait for a specific time
await twd.wait(1000); // Wait 1 second
// Wait for element to appear
const element = await twd.get(".loading-spinner");
element.should("be.visible");
// Wait for element to disappear
await twd.wait(500);
const spinner = await twd.get(".loading-spinner");
spinner.should("not.be.visible");
```
## State Management & Test Isolation
TWD runs tests directly in the browser **without page reloads**. The `twd.visit()` command simulates SPA navigation using the History API, which means your SPA router re-renders but **in-memory application state is preserved** between tests.
This is a deliberate trade-off: it keeps tests fast and deterministic, but it means state from tools like Zustand, Redux, Jotai, or plain module-level variables will **leak between tests** unless you explicitly reset it.
### What TWD resets for you
TWD provides built-in reset methods for its own managed state:
```ts
beforeEach(() => {
twd.clearRequestMockRules(); // Clears API mock rules
twd.clearComponentMocks(); // Clears component mocks
});
```
### What you need to reset manually
Any state that lives in your application's JavaScript memory persists across tests:
| State type | Example | How to reset |
|---|---|---|
| State managers | Zustand, Redux, Jotai, Pinia | Call your store's reset method |
| Browser storage | localStorage, sessionStorage | `localStorage.clear()` |
| Module singletons | Caches, counters, flags | Re-assign to initial value |
| Global event listeners | `window.addEventListener(...)` | Remove in `afterEach` |
| Timers | `setInterval`, `setTimeout` | Clear in `afterEach` |
Most state management libraries provide a way to reset stores to their initial state. Expose a reset method on your stores and call it in `beforeEach`:
```ts
import { resetMyStore } from "../../store";
describe("My feature", () => {
beforeEach(() => {
twd.clearRequestMockRules();
twd.clearComponentMocks();
resetMyStore();
localStorage.clear();
});
it("should start with clean state", async () => {
await twd.visit("/my-page");
// State is fresh for every test
});
});
```
### Why not just reload the page?
TWD's test runner, sidebar UI, mock service worker, and all test definitions live in the same browser page as your app. A full page reload (`window.location.reload()`) would destroy the test runner itself, losing all test results and state. This is the fundamental constraint of in-browser testing — and the same trade-off other in-browser tools face.
## Best Practices
### 1. Group Related Tests
Organize tests logically with nested describes:
```ts
describe("Shopping Cart", () => {
describe("Adding Items", () => {
it("should add item to cart", async () => {
// Test adding items
});
});
describe("Removing Items", () => {
it("should remove item from cart", async () => {
// Test removing items
});
});
});
```
### 2. Clean Up After Tests
Use `beforeEach` to ensure clean state. See [State Management & Test Isolation](#state-management-test-isolation) above for full details.
```ts
beforeEach(() => {
twd.clearRequestMockRules();
twd.clearComponentMocks();
localStorage.clear();
// Reset your app's state managers too (Zustand, Redux, etc.)
});
```
### 3. Write Descriptive Test Names
```ts
// Good ✅
it("should show validation error when email is invalid", async () => {
// Test implementation
});
// Bad ❌
it("should validate email", async () => {
// Test implementation
});
```
### 4. Test User Workflows
Test complete user workflows rather than isolated functions:
```ts
describe("User Registration Flow", () => {
it("should register new user and redirect to dashboard", async () => {
await twd.visit("/register");
const user = userEvent.setup();
// Fill registration form
const emailInput = await twd.get("#email");
const passwordInput = await twd.get("#password");
const confirmPasswordInput = await twd.get("#confirmPassword");
await user.type(emailInput.el, "user@example.com");
await user.type(passwordInput.el, "securePassword123");
await user.type(confirmPasswordInput.el, "securePassword123");
// Submit form
const submitButton = await twd.get("button[type='submit']");
await user.click(submitButton.el);
// Verify redirect and welcome message
await twd.url().should("contain.url", "/dashboard");
const welcome = await twd.get("h1");
welcome.should("contain.text", "Welcome");
});
});
```
## Next Steps
- Learn about [API Mocking](/api-mocking) for testing with external APIs
- Follow the [Tutorial](/tutorial/) for comprehensive testing scenarios
- Check the [API Reference](/api/) for complete method documentation
# API Mocking
Source: https://twd.dev/api-mocking
TWD provides API mocking through its own mock service worker integration, allowing you to isolate your frontend from external systems and validate UI behavior against deterministic network boundaries.
::: tip Cross-origin requests
The mock service worker intercepts **all** requests made from the page, including cross-origin URLs (e.g., third-party APIs like payment providers or analytics services). You can mock any URL your frontend calls, regardless of domain.
:::
## Setup
### 1. Install the service worker
First, set up the mock service worker in your project:
```bash
npx twd-js init public
```
This command copies the required `mock-sw.js` file to your public directory.
### 2. Remove Service Worker from Production Builds
The service worker file (`mock-sw.js`) is only needed during development for API mocking. To automatically remove it from production builds, add the `removeMockServiceWorker` Vite plugin to your configuration:
```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { twd, removeMockServiceWorker } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
twd(), // dev: discovery + sidebar + request mocking
removeMockServiceWorker(), // build: strip mock-sw.js from prod dist
],
});
```
This plugin will automatically remove `mock-sw.js` from your `dist` folder during production builds.
::: tip
The plugin only runs during build time (`apply: 'build'`) and will not affect your development workflow.
:::
### 3. Initialize Mocking
The `twd()` Vite plugin (recommended) initializes request mocking automatically — no entry-file changes required. Mocking is enabled by default (`serviceWorker: true`).
```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { twd } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
twd({
serviceWorker: true, // default — request mocking enabled
serviceWorkerUrl: '/mock-sw.js', // default
}),
],
});
```
For non-Vite projects, initialize manually in your entry file. Both `initTWD` and the standard setup register the service worker for you:
```ts
// Bundled (recommended for non-Vite projects)
if (import.meta.env.DEV) {
const { initTWD } = await import('twd-js/bundled');
const tests = import.meta.glob('./**/*.twd.test.ts');
initTWD(tests, { serviceWorker: true });
}
```
```ts
// Standard (React-only, 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, , createRoot);
twd.initRequestMocking().catch(console.error);
}
```
::: tip
You only need to register request mocking once (via the plugin or `initTWD`/`initRequestMocking`), not per test.
:::
## Basic Mocking
### Simple GET Request
```ts
import { twd, userEvent } from "twd-js";
import { describe, it } from "twd-js/runner";
describe("User Profile", () => {
it("should load user data", async () => {
// Mock the API request
await twd.mockRequest("getUser", {
method: "GET",
url: "https://api.example.com/user/123",
response: {
id: 123,
name: "John Doe",
email: "john@example.com"
}
});
await twd.visit("/profile");
// Trigger the request
const loadButton = await twd.get("button[data-testid='load-profile']");
await userEvent.click(loadButton.el);
// Wait for the mock to be called
await twd.waitForRequest("getUser");
// Verify the UI updated
const userName = await twd.get("[data-testid='user-name']");
userName.should("have.text", "John Doe");
});
});
```
### POST Request with Body
```ts
it("should create new user", async () => {
await twd.mockRequest("createUser", {
method: "POST",
url: "https://api.example.com/users",
response: {
id: 456,
name: "Jane Smith",
email: "jane@example.com",
created: true
},
status: 201
});
await twd.visit("/users/new");
const user = userEvent.setup();
// Fill form
await user.type(await twd.get("#name"), "Jane Smith");
await user.type(await twd.get("#email"), "jane@example.com");
// Submit form
await user.click(await twd.get("button[type='submit']"));
// Wait for request and verify
const rule = await twd.waitForRequest("createUser");
// Check the request body
expect(rule.request).to.deep.equal({
name: "Jane Smith",
email: "jane@example.com"
});
});
```
## Advanced Mocking
### URL Patterns with RegExp
```ts
it("should handle dynamic user IDs", async () => {
// Mock any user ID
await twd.mockRequest("getUserById", {
method: "GET",
url: /\/api\/users\/\d+/, // Matches /api/users/123, /api/users/456, etc.
response: {
id: 123,
name: "Dynamic User"
}
});
// This will match the pattern
await twd.visit("/users/123");
// Trigger request and verify
const loadButton = await twd.get("button[data-testid='load-user']");
await userEvent.click(loadButton.el);
await twd.waitForRequest("getUserById");
});
```
### URL Matching with Strings
When you provide a string URL (not a RegExp), TWD uses **boundary-aware matching**. The mock triggers when the request URL contains the mock URL followed by a valid boundary character: `?`, `#`, `&`, or end of string.
This prevents similar URLs from accidentally matching each other:
```ts
await twd.mockRequest("getUsers", {
method: "GET",
url: "/api/users",
response: [{ id: 1, name: "John" }],
});
// ✅ Matches: /api/users
// ✅ Matches: /api/users?page=1&limit=10
// ❌ Does NOT match: /api/users/123 (different resource)
// ❌ Does NOT match: /api/users-settings
// ❌ Does NOT match: /api/username
```
This means you can safely mock similar endpoints and nested resources without conflicts:
```ts
// Similar endpoint names
await twd.mockRequest("getOrders", {
method: "GET",
url: "/api/orders",
response: [{ id: 1 }],
});
await twd.mockRequest("getOrdersSummary", {
method: "GET",
url: "/api/orders-summary",
response: { total: 100 },
});
// Nested resources
await twd.mockRequest("travelerDetail", {
method: "GET",
url: `v1/travelers/${travelerId}`,
response: mockTravelerDetail,
});
await twd.mockRequest("billingDetails", {
method: "GET",
url: `v1/travelers/${travelerId}/billing-details`,
response: mockBillingDetails,
});
// Each request matches only its intended mock
```
::: tip Query String Matching
Boundary checking only applies to the **path** portion of the URL. Once the match extends into the query string, substring matching is used. This lets you provide partial query strings to match any value:
```ts
// Matches any search query
await twd.mockRequest("search", {
method: "GET",
url: "https://api.example.com/search?q=",
response: [{ id: 1, title: "Result" }],
});
// ✅ Matches: /search?q=laptops
// ✅ Matches: /search?q=phones&category=electronics
```
:::
If you need more flexible matching, use RegExp patterns instead.
### Custom Status Codes and Headers
```ts
it("should handle API errors", async () => {
await twd.mockRequest("getUserError", {
method: "GET",
url: "https://api.example.com/user/999",
response: {
error: "User not found",
code: "USER_NOT_FOUND"
},
status: 404,
responseHeaders: {
"Content-Type": "application/json",
"X-Error-Code": "USER_NOT_FOUND"
}
});
await twd.visit("/user/999");
const loadButton = await twd.get("button[data-testid='load-user']");
await userEvent.click(loadButton.el);
await twd.waitForRequest("getUserError");
// Verify error handling
const errorMessage = await twd.get(".error-message");
errorMessage.should("contain.text", "User not found");
});
```
### Multiple Requests
```ts
it("should handle multiple API calls", async () => {
// Mock multiple endpoints
await twd.mockRequest("getUser", {
method: "GET",
url: "/api/user/123",
response: { id: 123, name: "John Doe" }
});
await twd.mockRequest("getUserPosts", {
method: "GET",
url: "/api/user/123/posts",
response: [
{ id: 1, title: "First Post" },
{ id: 2, title: "Second Post" }
]
});
await twd.visit("/user/123");
const loadButton = await twd.get("button[data-testid='load-all']");
await userEvent.click(loadButton.el);
// Wait for both requests
const rules = await twd.waitForRequests(["getUser", "getUserPosts"]);
expect(rules).to.have.length(2);
// Verify UI shows both user and posts
const userName = await twd.get("[data-testid='user-name']");
userName.should("have.text", "John Doe");
const posts = await twd.getAll(".post-item");
expect(posts).to.have.length(2);
});
```
## Simulating Network Delay
You can simulate network latency by adding a `delay` option (in milliseconds) to any mock rule. This is useful for testing loading states, spinners, timeouts, and other UX that depends on slow responses.
### Basic Delay
```ts
it("should show loading state while waiting for API", async () => {
// Mock a slow API response (1 second delay)
await twd.mockRequest("getUser", {
method: "GET",
url: "/api/user/123",
response: { id: 123, name: "John Doe" },
delay: 1000, // 1 second delay
});
await twd.visit("/profile");
// Loading indicator should be visible while waiting
const spinner = await twd.get("[data-testid='loading-spinner']");
spinner.should("be.visible");
// Wait for the request to complete
await twd.waitForRequest("getUser");
// After the response arrives, loading should be gone
await twd.notExists("[data-testid='loading-spinner']");
const userName = await twd.get("[data-testid='user-name']");
userName.should("have.text", "John Doe");
});
```
::: tip
The `delay` only affects how long the browser waits for the HTTP response. The `EXECUTED` notification still fires immediately, so `twd.waitForRequest()` resolves right away -- it does not wait for the delay. This mirrors real network behavior: the server receives the request instantly, but the response takes time to arrive.
:::
### Delay with Error Responses
```ts
it("should handle timeout-like errors", async () => {
await twd.mockRequest("slowError", {
method: "GET",
url: "/api/data",
response: { error: "Gateway Timeout" },
status: 504,
delay: 3000, // Simulate a 3-second timeout
});
await twd.visit("/data-page");
// Verify the app shows appropriate timeout messaging
await twd.waitForRequest("slowError");
await twd.wait(3100); // Wait for the delayed response to arrive
const errorMessage = await twd.get(".error-message");
errorMessage.should("contain.text", "Gateway Timeout");
});
```
## Asserting Request Count
TWD tracks how many times each mock rule has been matched. This lets you assert that an API was called the expected number of times.
### `getRequestCount(alias)`
Returns the number of times a specific mock rule was hit.
```ts
it("should call the API exactly twice", async () => {
await twd.mockRequest("getUser", {
method: "GET",
url: "/api/user",
response: { id: 1, name: "John" },
});
await twd.visit("/profile");
// Trigger two requests
const refreshButton = await twd.get("button[data-testid='refresh']");
await userEvent.click(refreshButton.el);
await twd.waitForRequest("getUser");
// Re-register to reset executed flag for second wait
await twd.mockRequest("getUser", {
method: "GET",
url: "/api/user",
response: { id: 1, name: "John" },
});
await userEvent.click(refreshButton.el);
await twd.waitForRequest("getUser");
// Assert the count
expect(twd.getRequestCount("getUser")).to.equal(2);
});
```
### `getRequestCounts()`
Returns a snapshot of all mock rule hit counts as an object.
```ts
it("should track counts for multiple endpoints", async () => {
await twd.mockRequest("getUsers", {
method: "GET",
url: "/api/users",
response: [],
});
await twd.mockRequest("getSettings", {
method: "GET",
url: "/api/settings",
response: { theme: "dark" },
});
await twd.visit("/dashboard");
await twd.waitForRequests(["getUsers", "getSettings"]);
const counts = twd.getRequestCounts();
expect(counts).to.deep.equal({
getUsers: 1,
getSettings: 1,
});
});
```
### Counter Reset
Counters are automatically reset when you call `twd.clearRequestMockRules()`. This happens naturally in `beforeEach` cleanup:
```ts
describe("API Tests", () => {
beforeEach(() => {
twd.clearRequestMockRules(); // Also resets all counters
});
it("starts with zero counts", () => {
expect(twd.getRequestCount("anyAlias")).to.equal(0);
expect(twd.getRequestCounts()).to.deep.equal({});
});
});
```
## Dynamic Mocking
### Updating Mocks Mid-Test
```ts
it("should handle changing API responses", async () => {
// Initial mock
await twd.mockRequest("getStatus", {
method: "GET",
url: "/api/status",
response: { status: "loading" }
});
await twd.visit("/dashboard");
const refreshButton = await twd.get("button[data-testid='refresh']");
await userEvent.click(refreshButton.el);
await twd.waitForRequest("getStatus");
let statusText = await twd.get("[data-testid='status']");
statusText.should("have.text", "loading");
// Update the mock
await twd.mockRequest("getStatus", {
method: "GET",
url: "/api/status",
response: { status: "completed" }
});
// Trigger another request
await userEvent.click(refreshButton.el);
await twd.waitForRequest("getStatus");
statusText = await twd.get("[data-testid='status']");
statusText.should("have.text", "completed");
});
```
### Conditional Responses
```ts
it("should handle authentication states", async () => {
// Mock unauthorized response first
await twd.mockRequest("getProfile", {
method: "GET",
url: "/api/profile",
response: { error: "Unauthorized" },
status: 401
});
await twd.visit("/profile");
// Should redirect to login
await twd.wait(100);
await twd.url().should("contain.url", "/login");
// Now mock successful login
await twd.mockRequest("login", {
method: "POST",
url: "/api/login",
response: {
token: "abc123",
user: { id: 1, name: "John Doe" }
}
});
// Mock authorized profile request
await twd.mockRequest("getProfile", {
method: "GET",
url: "/api/profile",
response: {
id: 1,
name: "John Doe",
email: "john@example.com"
}
});
// Login and verify
const user = userEvent.setup();
await user.type(await twd.get("#username"), "john");
await user.type(await twd.get("#password"), "password");
await user.click(await twd.get("button[type='submit']"));
await twd.waitForRequest("login");
// Should now access profile
await twd.visit("/profile");
await twd.waitForRequest("getProfile");
const profileName = await twd.get("[data-testid='profile-name']");
profileName.should("have.text", "John Doe");
});
```
## Request Inspection
### Verifying Request Data
```ts
it("should send correct form data", async () => {
await twd.mockRequest("submitForm", {
method: "POST",
url: "/api/contact",
response: { success: true }
});
await twd.visit("/contact");
const user = userEvent.setup();
// Fill form
await user.type(await twd.get("#email"), "test@example.com");
await user.type(await twd.get("#message"), "Hello world");
await user.click(await twd.get("#newsletter"));
// Submit
await user.click(await twd.get("button[type='submit']"));
// Verify request data
const rule = await twd.waitForRequest("submitForm");
expect(rule.request).to.deep.equal({
email: "test@example.com",
message: "Hello world",
newsletter: true
});
});
```
### Verifying Request Body
```ts
it("should send the correct request body", async () => {
await twd.mockRequest("authenticatedRequest", {
method: "POST",
url: "/api/protected",
response: { data: "secret data" }
});
await twd.visit("/protected");
const loadButton = await twd.get("button[data-testid='load-protected']");
await userEvent.click(loadButton.el);
const rule = await twd.waitForRequest("authenticatedRequest");
// rule.request IS the parsed body directly (not rule.request.body)
expect(rule.request).to.deep.equal({
token: "bearer-token-123"
});
});
```
::: warning
`rule.request` contains the parsed request body directly — **not** a request object with a `.body` property. Use `rule.request.fieldName`, not `rule.request.body.fieldName`.
:::
## Mock Management
### Clearing Mocks
::: tip
You can also clear all mocks (both API request mocks and component mocks) at any time by clicking the **Clear mocks** button in the TWD sidebar header, next to the "Run All" button. This is useful for quick manual resets during development without modifying test code.
:::
```ts
describe("User Management", () => {
// Clear mocks before each test
beforeEach(() => {
twd.clearRequestMockRules();
});
it("should handle user creation", async () => {
// This test starts with clean mocks
await twd.mockRequest("createUser", {
method: "POST",
url: "/api/users",
response: { id: 1, created: true }
});
// Test implementation...
});
// Mocks are automatically cleared before the next test
});
```
### Inspecting Active Mocks
```ts
it("should have correct mocks configured", async () => {
await twd.mockRequest("getUsers", {
method: "GET",
url: "/api/users",
response: []
});
await twd.mockRequest("createUser", {
method: "POST",
url: "/api/users",
response: { id: 1 }
});
// Check active mocks
const activeMocks = twd.getRequestMockRules();
expect(activeMocks).to.have.length(2);
const getUsersMock = activeMocks.find(mock => mock.alias === "getUsers");
expect(getUsersMock?.method).to.equal("GET");
});
```
## Common Patterns
### Error Handling
```ts
it("should display error message on API failure", async () => {
await twd.mockRequest("failedRequest", {
method: "GET",
url: "/api/data",
response: {
error: "Server error",
message: "Something went wrong"
},
status: 500
});
await twd.visit("/data-page");
const loadButton = await twd.get("button[data-testid='load-data']");
await userEvent.click(loadButton.el);
await twd.waitForRequest("failedRequest");
// Verify error display
const errorMessage = await twd.get(".error-message");
errorMessage.should("be.visible");
errorMessage.should("contain.text", "Something went wrong");
// Verify retry button appears
const retryButton = await twd.get("button[data-testid='retry']");
retryButton.should("be.visible");
});
```
### Pagination
```ts
it("should handle paginated results", async () => {
// Mock first page
await twd.mockRequest("getPage1", {
method: "GET",
url: "/api/users?page=1",
response: {
users: [
{ id: 1, name: "User 1" },
{ id: 2, name: "User 2" }
],
pagination: {
page: 1,
hasNext: true,
total: 3
}
}
});
// Mock second page
await twd.mockRequest("getPage2", {
method: "GET",
url: "/api/users?page=2",
response: {
users: [
{ id: 3, name: "User 3" },
],
pagination: {
page: 2,
hasNext: false,
total: 3
}
}
});
await twd.visit("/users");
// Load first page
await twd.waitForRequest("getPage1");
let users = await twd.getAll(".user-item");
expect(users).to.have.length(2);
// Load next page
const nextButton = await twd.get("button[data-testid='next-page']");
await userEvent.click(nextButton.el);
await twd.waitForRequest("getPage2");
// Should now have 4 users total
users = await twd.getAll(".user-item");
expect(users).to.have.length(1);
});
```
## Best Practices
### 1. Use Descriptive Aliases
```ts
// Good ✅
await twd.mockRequest("getUserProfile", { /* ... */ });
await twd.mockRequest("updateUserSettings", { /* ... */ });
// Bad ❌
twd.mockRequest("req1", { /* ... */ });
twd.mockRequest("api2", { /* ... */ });
```
### 2. Mock Realistic Data
```ts
// Good ✅ - Realistic user data
await twd.mockRequest("getUser", {
method: "GET",
url: "/api/user/123",
response: {
id: 123,
name: "John Doe",
email: "john.doe@example.com",
avatar: "https://example.com/avatar.jpg",
createdAt: "2024-01-15T10:30:00Z",
role: "user"
}
});
// Bad ❌ - Minimal/unrealistic data
twd.mockRequest("getUser", {
method: "GET",
url: "/api/user/123",
response: { name: "test" }
});
```
### 3. Mock before request event is fired
```ts
// Good ✅ - mock before request event is fired
await twd.mockRequest("saveUser", {
method: "POST",
url: "/api/users",
response: { id: 1, created: true }
});
await twd.visit("/users/new");
const user = userEvent.setup();
await user.type(await twd.get("#name"), "John Doe");
await user.type(await twd.get("#email"), "john.doe@example.com");
await user.click(await twd.get("button[type='submit']"));
await twd.waitForRequest("saveUser");
const userName = await twd.get("[data-testid='user-name']");
userName.should("have.text", "John Doe");
```
```ts
// Bad ❌ - mock after request event is fired
await twd.visit("/users/new");
const user = userEvent.setup();
await user.type(await twd.get("#name"), "John Doe");
await user.type(await twd.get("#email"), "john.doe@example.com");
await user.click(await twd.get("button[type='submit']"));
// Bad ❌ - mock after request event is fired
twd.mockRequest("saveUser", {
method: "POST",
url: "/api/users",
response: { id: 1 }
});
await twd.waitForRequest("saveUser");
```
### 3. Clean Up Mocks
```ts
describe("API Tests", () => {
// Always clean up after each test
afterEach(() => {
twd.clearRequestMockRules();
});
// Or clean up before each test
beforeEach(() => {
twd.clearRequestMockRules();
});
});
```
### 4. Test Error Scenarios
```ts
describe("Error Handling", () => {
it("should handle network errors", async () => {
twd.mockRequest("networkError", {
method: "GET",
url: "/api/data",
response: { error: "Network error" },
status: 0 // Simulate network failure
});
// Test your error handling...
});
it("should handle server errors", async () => {
twd.mockRequest("serverError", {
method: "GET",
url: "/api/data",
response: { error: "Internal server error" },
status: 500
});
// Test your error handling...
});
});
```
## Troubleshooting
### Mock Not Triggering
1. **Check in console mock-sw.js version** - Should log `[TWD] Mock Service Worker loaded - version x.x.x` the same version as your `twd-js` package
2. **Ensure mocking is initialized** - Call `twd.initRequestMocking()`
3. **Check the URL pattern** - Make sure it matches exactly
4. **Verify the HTTP method** - GET, POST, PUT, DELETE must match
5. **Check browser console** - Look for service worker errors
### Request Not Matching
```ts
// Use RegExp for flexible matching
await twd.mockRequest("flexibleMatch", {
method: "GET",
url: /\/api\/users\/\d+/, // Matches any user ID
response: { /* ... */ }
});
```
### Service Worker Issues
1. **Reinstall service worker**: Run `npx twd-js init public` again
2. **Check public directory**: Ensure `mock-sw.js` exists
3. **Browser cache**: Try hard refresh (Ctrl+Shift+R)
## Next Steps
- Learn about [User Events in the Tutorial](/tutorial/first-test) for form interactions
- Check the [API Reference](/api/twd-commands) for all mocking methods
# Component Testing
Source: https://twd.dev/component-testing
Call Testing Library's `render()` inside a TWD test and the component mounts into
your running app, in your real browser. Same Testing Library API you already use,
no simulated DOM underneath.
::: tip Not to be confused with Component Mocking
This page is about **rendering a component in isolation and testing it**. If you
want to **replace** a child component with a stub, see
[Component Mocking](/component-mocking).
:::
## Setup
### 1. Install Testing Library
TWD does not ship Testing Library's framework renderers. Install the one for your
framework as a dev dependency:
```bash
npm install --save-dev @testing-library/react
```
### 2. Make the test pattern match `.tsx`
Component tests are `.tsx`. The `twd()` plugin's default `testFilePattern` is
`'/**/*.twd.test.ts'`, which matches `.ts` only, so `.tsx` files are skipped
**silently**: no error, no warning, and nothing appears in the sidebar.
```ts
// vite.config.ts
import { twd } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
// ... your other plugins
twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}' }),
],
});
```
### 3. Exclude TWD tests from Vitest
If the same repo also runs Vitest, it matches `*.test.tsx` by default, collects
your TWD files, finds no `describe` it recognises, and fails the run with
`No test suite found in file`. Here is the complete config combining both steps:
```ts
// vite.config.ts (complete)
import { defineConfig, configDefaults } from 'vitest/config';
import { twd } from 'twd-js/vite-plugin';
export default defineConfig({
plugins: [
// ... your other plugins
twd({ testFilePattern: '/**/*.twd.test.{ts,tsx}' }),
],
test: {
exclude: [...configDefaults.exclude, '**/*.twd.test.*'],
},
});
```
### 4. Add the component host
`render()` appends its container to `document.body`, which puts your component
after the app root, a full viewport below the layout. The app's own DOM is also
still on the page, so `screen` matches its elements as well as the ones your test
rendered. One helper solves both, and your app does not change:
```ts
// twd-tests/support/componentHost.ts
const HOST_ID = 'twd-component-host';
const APP_ROOT_ID = 'root'; // 'app' in a default Vue app
let appRoot: HTMLElement | null = null;
let placeholder: Comment | null = null;
/** The element component tests render into: a blank div on an empty page. */
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;
}
/** Removes the host and puts the app back. Call it in afterEach. */
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;
}
```
Two details in there matter.
**Detaching the app root is not the same as emptying it.** `root.innerHTML = ''`
pulls the DOM out from under your framework while it still holds references to
those nodes, and the app does not come back. Moving the node out and putting it
back leaves those references intact, so `restorePage()` returns a live app.
**The host is prepended, not appended.** That puts the component at the top of the
page, where you can watch it run without scrolling, and keeps it in normal flow so
it sits inside the offset TWD applies for its sidebar.
The payoff is that `screen` behaves exactly as it does in jsdom: the only thing in
the document is what your test rendered. That also covers content your component
sends through a portal or a `Teleport`, which lands on `document.body` rather than
inside the host.
::: tip This replaces the blank-route approach
An earlier version of this page recommended declaring an empty route and visiting
it with `twd.visit()`. The host does the same job without a route, without
`twd.visit()`, and without touching your app.
:::
### 5. Clean up between tests
`render()` appends to the document and removes nothing on its own. In jsdom the
environment is torn down for you between files. In a real browser it is not, so
renders stack up and queries start finding duplicates.
```tsx
import { cleanup } from "@testing-library/react";
import { afterEach } from "twd-js/runner";
import { restorePage } from "./support/componentHost";
afterEach(() => {
cleanup();
restorePage();
});
```
Use `afterEach`, not `beforeEach`. TWD runs after-hooks in a `finally`, so this
still runs when a test fails, and it puts the app back before your flow tests need
it. If you also mock requests, `twd.clearRequestMockRules()` belongs in
`beforeEach` as usual.
That is the whole setup.
## Your first component test
```tsx
import { render, screen, cleanup } from "@testing-library/react";
import { describe, it, afterEach } from "twd-js/runner";
import { twd } from "twd-js";
import { AppProvider } from "@/context/AppContext";
import { Add } from "../Add";
import { componentHost, restorePage } from "./support/componentHost";
describe("Add Component", () => {
afterEach(() => {
cleanup();
restorePage();
});
it("renders the Add component", () => {
render(, { container: componentHost() });
twd.should(screen.getByText("Add Item"), "be.visible");
});
});
```
`AppProvider` here is the real provider, 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.
`twd.should` accepts any element you hand it, whether a query found it in your app
or in a component you just rendered.
## Queries: use `screen`, not `screenDom` {#queries}
::: warning `screenDom` will not find your rendered component
`render()` mounts outside the app root that `screenDom` scopes to, and while a
component test runs that root is not even in the document. Queries will fail.
:::
Every other page in these docs steers you to `screenDom`, because for flow tests
it is the right default: it excludes the TWD sidebar. Component tests are the
exception.
Use one of these instead:
- **Testing Library's own `screen`** (recommended). It queries `document.body`,
which is where `render()` put your component.
- **TWD's `screenDomGlobal`**, which also queries the whole document. If you pick
this one, keep queries specific, because it can also match elements inside the
TWD sidebar.
```ts
// Works: render() mounted into document.body
screen.getByText("Add Item");
screenDomGlobal.getByRole("button", { name: "Add Item" });
// Does not work: scoped to the app root, which is not where render() mounted
screenDom.getByText("Add Item");
```
## Mocking
`twd.mockRequest` still works and is still the right tool. It replaces the
network, which is a boundary you do not own, and everything on your side of it
still runs: component, hook, provider, router.
```ts
await twd.mockRequest("createCar", {
url: "/api/cars",
method: "POST",
status: 201,
response: { id: "test-1", model: "Golf", year: "2023" },
});
```
The rule this follows: **mock at boundaries you do not own, and nowhere else.**
The network, the clock, third-party services. When you stub a hook, a context, or
a component out of your own `src/`, the stub sits between the assertion and the
behaviour you meant to check.
## Choosing between component and flow tests {#choosing-between-component-and-flow-tests}
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 and 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.
Neither replaces the other. The useful change is that choosing between them is a
decision about scope, made per test.
## One run, one coverage report
Component tests and flow tests are files in the same project, running in the same
browser, in the same session, against the same instrumented bundle. 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
```
One coverage file comes out, covering both styles. There is nothing to merge,
because there was only ever one run.
## Other frameworks
The examples above use `@testing-library/react`, which is what has been verified.
`@testing-library/vue` and `@testing-library/solid` take the same `container`
option and default to `document.body` the same way, so the helper transfers with
one change: `APP_ROOT_ID` is `'app'` in a default Vue app rather than `'root'`.
Neither is verified end to end yet. If you try one,
[open an issue](https://github.com/BRIKEV/twd/issues) and tell us how it went.
`@testing-library/angular` is a different shape. It mounts through `TestBed` and
does not accept a `container`, so the helper does not apply as written. Not tried.
## Troubleshooting
**My tests do not appear in the sidebar.** Your `testFilePattern` probably ends in
`.ts`. Component tests are `.tsx`. See [step 2](#setup).
**Queries find two of everything.** You are rendering on top of the app. Pass
`componentHost()` as the `container`, and call `cleanup()` and `restorePage()` in
`afterEach`. See [step 4](#setup).
**My app is blank after the component tests run.** `restorePage()` is missing from
`afterEach`, so the app root was never put back. See [step 5](#setup).
**`screenDom` cannot find my component.** Expected. Use `screen` or
`screenDomGlobal`. See [Queries](#queries).
**Vitest fails with `No test suite found in file`.** Vitest is collecting your TWD
tests. Add the `exclude` entry from [step 3](#setup).
## Why this works
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 simply
the DOM most people hand it.
TWD already runs inside your app in the browser, so the real DOM is right there
and `render()` uses it. The component is laid out on a screen, at a real size and
a real position, with your CSS applied to it.
It also means the providers and the network around your component are the real
ones, so there is often nothing left to stand in for.
## Further reading
- [No More Fake DOM: Testing Library Unit Tests in the Real Browser](https://dev.to/kevinccbsg/no-more-fake-dom-testing-library-unit-tests-in-the-real-browser-3p77)
- [frontend-challenge](https://github.com/kevinccbsg/frontend-challenge), which tests the same component in jsdom and in the browser side by side
## Next Steps
- [Testing Library](/testing-library) for the full query and `userEvent` reference
- [API Mocking](/api-mocking) for the service worker setup
- [Coverage](/coverage) for collecting a report across both test styles
# Component Mocking
Source: https://twd.dev/component-mocking
TWD provides powerful component mocking capabilities, allowing you to replace React components with mock implementations during testing. This is especially useful for isolating components, testing edge cases, or replacing complex dependencies with simpler test doubles.
::: tip Looking to test a component in isolation?
This page is about **replacing** a component with a stub. To **render** a single
component and test it in a real browser, see [Component Testing](/component-testing).
:::
## Overview
Component mocking in TWD allows you to:
- Replace components with mock implementations for isolated testing
- Test how parent components handle different component behaviors
- Simplify complex component dependencies during testing
- Verify component prop passing and interaction
## Setup
### 1. Wrap Components with MockedComponent
To make a component mockable, wrap it with the `MockedComponent` component and provide a unique name:
```tsx
import { MockedComponent } from "twd-js/ui";
interface ButtonProps {
onClick: (count: number) => void;
count: number;
}
const Button = ({ onClick, count }: ButtonProps) => {
return (
);
};
export default function CounterPage() {
const [count, setCount] = useState(0);
return (
Count: {count}
);
}
```
::: tip
The `name` prop must be unique and match the name used in your test when calling `twd.mockComponent()`.
:::
### 2. Mock Components in Tests
Use `twd.mockComponent()` to replace the component with a mock implementation:
```ts
import { twd, userEvent } from "twd-js";
import { describe, it, beforeEach } from "twd-js/runner";
interface ButtonProps {
onClick: (count: number) => void;
count: number;
}
const Button = ({ onClick, count }: ButtonProps) => {
return (
);
};
describe("Component Mocking", () => {
beforeEach(() => {
twd.clearComponentMocks();
});
it("should mock a component", async () => {
// Mock the Button component to increment by 2 instead of 1
twd.mockComponent("Button", ({ onClick, count }: ButtonProps) => (
