DEV Community: Kevin Julián Martínez Escobar

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

Kevin Julián Martínez Escobar — Tue, 17 Mar 2026 22:35:17 +0000

Now that AI is generating a big portion of our frontend code, speed is no longer the main bottleneck.

Confidence is.

We’ve seen this before: when teams wanted to move fast, the real enabler wasn’t “more code” — it was having a solid testing strategy that allowed safe refactoring and iteration.

That hasn’t changed. If anything, it’s more important now.

In previous posts, I talked about the TWD philosophy, but one idea is key here:

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

With this mindset, TWD (Test While Developing) lets you create deterministic UI tests, where you fully control the environment, simulate any scenario, and avoid flaky behavior.

The Problem: Allow AI Know Your Project

AI can write tests… but not your tests.

It doesn’t know:

how your project is structured
what should be mocked
how your auth works
what “good tests” look like in your codebase

So even if it generates tests, they often:

don’t follow your patterns
mock the wrong things
miss important flows

The Solution: TWD + Skills

To solve this, we introduced TWD skills inside a Claude Code plugin.

These skills give the AI:

context about your project
rules to follow
patterns to reuse

So instead of generic tests, you get tests that actually fit your codebase.

/twd:setup — The Most Important First Step

Everything starts here:

/twd:setup

This is an interactive setup that analyzes your project and creates:

.claude/twd-patterns.md

This file becomes the source of truth for how tests should be written.

What /twd:setup Does

Detects your framework, Vite config, entry points, CSS setup
Asks about:
- auth & permissions
- API structure
- third-party dependencies
- state management
Generates a project-specific testing config
Optionally installs and configures TWD for you

How It Looks in Practice

You just run:

/twd:setup

And the agent starts understanding your project:

It will ask the right questions to understand how your app works and detect your frontend configuration:

What should be mocked?
How does auth behave?
Where are your services?

Once completed, it generates your config file:

.claude/twd-patterns.md

This is critical — every future test uses this as context.

If something is outdated, it will even suggest improvements:

And when it's done, it guides you to the next step:

Why This Matters

Without this step, AI-generated tests are:

generic
inconsistent
sometimes useless

With /twd:setup, tests become aligned with your architecture.

The plugin also includes skills for:

automatic test generation
CI setup
test quality analysis
test gap detection
flow visualisation

We’ll cover those in future posts.

Final Thought

AI can make you faster.

But tests are what let you keep that speed without breaking everything.

If you care about frontend quality in the AI era, don’t just generate code:

Generate confidence.

Agent conversation:

TWD setup skill claude-opus-4-6

You

<command-message>twd:setup</command-message>
<command-name>/twd:setup</command-name>

You

Base directory for this skill: [REDACTED]/.claude/plugins/cache/twd-ai/twd/1.1.0/skills/setup

TWD Project Setup

You are configuring TWD (Test While Developing) for this project. Your job is to detect project settings, ask questions for what can't be auto-detected, and generate a .claude/twd-patterns.md configuration file.

Step 1: Auto-Detect Project Settings

Read these files to pre-fill answers (read all in parallel):

package.json — detect framework from dependencies:
- react / react-dom → React
- vue → Vue
- @angular/core → Angular
- solid-js → Solid
- Also detect CSS/component libraries: @mui/material, @chakra-ui/react, antd, @mantine/core, vuetify, primevue, element-plus, @angular/material
vite.config.ts (or .js, .mjs) — detect:
- base field (Vite base path, default /)
- server.port (dev server port, default 5173)
index.html — detect entry point from <script> src attribute
Glob for src/services/, src/api/, src/lib/api — detect API/services folder
Check if public/ directory exists — confirm public folder name
Detect state management from package.json dependencies:
- zustand → Zustand
- @reduxjs/toolkit or redux → Redux
- jotai → Jotai
- pinia → Pinia
Check if .claude/twd-patterns.md already exists — offer to update vs overwrite

Step 2: Ask Questions

IMPORTANT: Use the AskUserQuestion tool for ALL questions. This provides an interactive UI experience. Never dump questions as a plain numbered list in text output.

Present auto-detected values as a summary first, then ask questions in two batches:

Batch 1: Project basics (confirm auto-detected values)

Do NOT ask individual questions for values you already detected. Show a single summary of all detected values and ask "Does anything look wrong?" using AskUserQuestion. The user only needs to respond if something is incorrect. Example:

Here's what I detected:
- Framework: React
- Vite base path: /
- Dev server port: 5173
- Entry point: src/main.tsx
- Public folder: public/
- API services: src/services/
- CSS library: MUI
- State management: Zustand

Does anything look wrong, or should I continue?

Batch 2: Testing concerns (need user input)

After confirming batch 1, use AskUserQuestion for each of these that requires user input:

CSS library docs (only if a CSS library was detected): Where are the docs? (URL, local path, or "skip")
Auth middleware: Does your project have route-based auth/permissions? If yes, briefly describe the pattern.
Third-party modules: Does your project use external services that need mocking in tests? (e.g., Auth0, Stripe, analytics)
- If yes: Which modules and how are they imported?
- The agent needs this to know what to Sinon-stub in tests — "test what you own, mock what you don't"
State reset (only if state management was detected): How do you reset the store? (e.g., useStore.setState(initialState), store.$reset())
- TWD runs without page reloads — store state persists between tests and must be reset in beforeEach

Step 3: Generate `.claude/twd-patterns.md`

Create the .claude/ directory if it doesn't exist, then write .claude/twd-patterns.md with the following sections. Only include sections that are relevant — omit sections that don't apply.

# TWD Project Patterns

## Project Configuration

- **Framework**: FRAMEWORK
- **Vite base path**: BASE_PATH
- **Dev server port**: PORT
- **Entry point**: ENTRY_FILE
- **Public folder**: PUBLIC_DIR

### Relay Commands

```bash
# Run all tests (default — use this if base path is / and port is 5173)
npx twd-relay run

# Run all tests (custom config)
npx twd-relay run --port PORT --path "BASE_PATH__twd/ws"

Standard Imports

import { twd, userEvent, screenDom, expect } from "twd-js";
import { describe, it, beforeEach, afterEach } from "twd-js/runner";
// Project-specific imports go here (added by user)

Visit Paths

All twd.visit() calls must include the base path prefix:

await twd.visit("BASE_PATH");
await twd.visit("BASE_PATHsome-page");

Standard beforeEach / afterEach

beforeEach(() => {
  twd.clearRequestMockRules();
  twd.clearComponentMocks();
  Sinon.restore();
  // STORE_RESET (if applicable — e.g., useStore.setState(initialState), store.$reset())
  // AUTH_SETUP (if applicable)
  // THIRD_PARTY_STUBS (if applicable — e.g., Sinon.stub(authModule, 'useAuth').returns(...))
});

afterEach(() => {
  twd.clearRequestMockRules();
});

API Service Types

Service/API types are located in: API_FOLDER

Read files in this folder to understand endpoint URLs and response shapes when writing mock data.

CSS / Component Library

Library: CSS_LIB
Docs: CSS_DOCS_LOCATION

When writing tests, refer to library docs for correct ARIA roles and component structure.

Auth Middleware

AUTH_DESCRIPTION

Route → Permission Mapping

Route	Required Permissions
(to be filled by developer)

Third-Party Modules

"Test what you own, mock what you don't." These external modules should be stubbed in tests:

Module	Import Pattern	Stub Strategy
MODULE_NAME	`import { hook } from 'package'`	`Sinon.stub(moduleObj, 'hook').returns(...)`
(to be filled by developer)

See the test-writing reference for the default-export object pattern required for ESM stubbing.

Portals and Dialogs

Use screenDomGlobal instead of screenDom for elements rendered in portals (modals, dropdowns, tooltips):

import { screenDomGlobal } from "twd-js";
const modal = screenDomGlobal.getByRole("dialog");


### Template rules:
- If base path is `/`, simplify visit paths to just `await twd.visit("/page")`
- If port is `5173` and base path is `/`, use `npx twd-relay run` (no flags)
- Omit the "Auth Middleware" section entirely if no auth
- Omit the "Third-Party Modules" section entirely if no external modules
- Omit the "CSS / Component Library" section if none detected
- Omit the "API Service Types" section if no services folder found
- Omit the `STORE_RESET` comment in beforeEach if no state management library
- Omit the `AUTH_SETUP` comment in beforeEach if no auth middleware
- Omit the `THIRD_PARTY_STUBS` comment in beforeEach if no third-party modules

## Step 4: Optionally Run Setup

After generating the config file, check if TWD is already installed. If not, ask the user if they want to run setup now:

1. `npm install twd-js`
2. `npm install --save-dev twd-relay`
3. `npx twd-js init PUBLIC_DIR --save`
4. Configure entry point — **insert this DEV block BEFORE the existing app mount code** (before `createRoot`, `createApp`, etc.). The import is **`twd-js/bundled`**, NOT `twd-js`:

```typescript
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',
    serviceWorker: true,
    serviceWorkerUrl: '/mock-sw.js',
  });

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

Adjustments: If Vite base is not /, update serviceWorkerUrl to '/BASE/mock-sw.js' and relay URL to `${window.location.origin}/BASE/__twd/ws`.

Add Vite plugins:

import { twdHmr } from 'twd-js/vite-plugin';
import { twdRemote } from 'twd-relay/vite';
import type { PluginOption } from 'vite';

// Add to plugins array:
plugins: [
  // ... other plugins
  twdHmr(),
  twdRemote() as PluginOption,
]

Write a first test file

Only run steps the user approves. Show what each step does before executing.

Output

When done, summarize:
- Where the config file was written
- What values were detected vs asked
- What setup steps were completed (if any)
- Next steps for the user (e.g., "Run npm run dev to see the TWD sidebar")

Agent

Setting up TWD for your project. Let me detect your project settings first.

8 messages not shown

Agent

Here's what I detected from your project:

Framework: React 19 + TypeScript
Vite base path: / (default)
Dev server port: 5173 (default)
Entry point: src/main.tsx
Public folder: public/
API services: src/api/ (found todos.ts)
CSS: Tailwind CSS v4 + Radix UI + shadcn/ui pattern (CVA, clsx, tailwind-merge)
State management: Zustand

No auth middleware or third-party modules detected. Let me confirm this with you.

1 message not shown

Agent

Now let me ask about the remaining items that need your input.

1 message not shown

Agent

Got it. Let me generate the configuration file.

2 messages not shown

Agent

Config file written. Now let me check if TWD is already installed.

1 message not shown

Agent

TWD is not installed yet. Let me ask if you'd like to run the setup.

1 message not shown

Agent

Let's start with installing the packages and initializing TWD.

2 messages not shown

Agent

Good. Now let me configure the entry point and Vite plugins.

2 messages not shown

Agent

Now add the Vite plugins.

1 message not shown

Agent

Now let me read the API file to write a meaningful first test.

4 messages not shown

Agent

Now let me create a first test file for the Helloworld page.

1 message not shown

Agent

TWD setup is complete. Here's a summary:

Config file: .claude/twd-patterns.md

Auto-detected values: React 19, Vite defaults (/, 5173), src/main.tsx, public/, src/api/, Tailwind + Radix UI, Zustand

Setup steps completed:
1. Installed twd-js and twd-relay
2. Initialized service worker in public/mock-sw.js
3. Added TWD dev block to src/main.tsx (before app mount)
4. Added twdHmr() and twdRemote() Vite plugins to vite.config.ts
5. Created first test: src/pages/Helloworld/Helloworld.twd.test.ts

Next steps:
- Run npm run dev to start the dev server — you'll see the TWD sidebar on the left
- Run npx twd-relay run in a separate terminal to execute tests from CLI

Are Developers Still Learning, or Just Using AI?

Kevin Julián Martínez Escobar — Tue, 10 Mar 2026 22:10:52 +0000

AI is changing the way we work as developers.

We are moving from writing code to writing specifications. Instead of implementing features ourselves, we rely more on agent modes and tools like Claude Code, Codex, or Gemini CLI.

This works incredibly well. Productivity increases, repetitive work disappears, and we can ship features faster.

But there is something I’ve started noticing.

Developers are not necessarily learning more.
We are just doing the same things faster.

AI Cannot Replace Understanding

When you rely heavily on AI tools, something subtle happens.

You stop exploring new solutions yourself.
You stop experimenting.
You stop learning new paradigms.

Many developers simply apply the same solutions they always used, just faster because AI writes the code.

When a new approach or development practice appears, it often does not get adopted well because the developer does not really understand it.

AI can generate code.

But it cannot give you knowledge you never built.

The Knowledge Gap

A simple example.

I am not an expert in:

load testing
monitoring
observability

I know these areas are important. But if I do not understand the concepts, how am I supposed to apply them correctly?

Even with the best prompts and agents, the result will still be shallow.

AI helps execute ideas. It does not replace learning them.

Where This Shows the Most

I notice this especially in two areas.

testing
accessibility

Testing

Recently I have heard things like:

Why write tests if AI generates almost perfect code?

or:

We run Playwright tests with AI after the feature. That is enough.

But testing is not about validating one run. It exists to prevent regressions, catch old bugs, and protect systems as they evolve.

AI can generate tests.

But testing strategy still requires understanding.

Accessibility

Accessibility has always been ignored in many projects.

AI has not changed that.

You can add an accessibility agent, but accessibility is not just adding attributes. It requires understanding how assistive technologies behave, how screen readers navigate, and how keyboard interaction works.

Without that knowledge, accessibility stays superficial.

The New Developer Loop

Something interesting is happening.

Developers spend more time writing Markdown specs for AI than learning new technical concepts.

Instead of experimenting, breaking things, and learning through failure, we optimise prompts and agent workflows.

But not necessarily ourselves.

I Am Also In That Loop

To be fair, I am also part of this.

AI tools are powerful and it is easy to rely on them.

But recently I started asking myself a simple question.

Am I actually improving?

Or am I just getting faster?

So I am trying to go back to learning new concepts, experimenting more, and understanding systems deeper.

And only after that, delegating to AI.

Ask Yourself This

If AI makes you 10x more productive, ask yourself:

Are you doing something you would never do if you had infinite time?

Are you exploring areas you previously did not understand?

Or are you just shipping the same things faster?

And one more question.

If your productivity increases 10x, do you now have 10x more time?

More time to learn, exercise, spend time with family, or build deeper knowledge?

If the answer is no, then what is AI really doing for you?

Is it helping you become a better developer?

Or just a faster version of the same developer?

TWD Tip: Stub Auth0 Hooks and Mock React Modules

Kevin Julián Martínez Escobar — Mon, 12 Jan 2026 22:50:46 +0000

Authentication is one of the trickiest features to test in modern apps.

Tools like Auth0 help a lot, especially with React, providing hooks like useAuth0 to manage authentication.

However, automating these tests is tricky.

With Cypress, testing across domains requires special configuration.
With Vitest, you need to mock data, but your tests still only return a simple pass/fail in the terminal.
You also need real users created and validated

TWD (Testing While Developing) takes a different approach: it encourages testing behavior, not infrastructure. That means you don’t need to test the auth provider itself — you just need to simulate the authentication behavior your app depends on.

For React apps using Auth0 with PKCE flow, it’s a bit more complicated, because we rely on the hook rather than simple requests. Let’s see how we can fully control authentication in our tests.

Tool for spying and mocking

We’ll use Sinon, a classic library for spies, stubs, and mocks. Why Sinon? Because it works directly in the browser — which is essential for TWD.

Understand the Auth0 hook

Here’s the basic usage in a React component:

import { useAuth0 } from "@auth0/auth0-react";

// get info of user in the app
const { user, getAccessTokenSilently, loginWithRedirect, logout } = useAuth0();

These methods allow your app to:

Log in and log out users
Get user info
Get tokens to send to your API

Move auth logic to a separate file

To stub the hook in TWD tests, we create a small wrapper:

import { useAuth0 } from "@auth0/auth0-react";

const useAuth = () => useAuth0();

export default { useAuth };

Important: we export as default and as an object.

Why? Because ESModules are immutable by default. Named exports like export const useAuth = ... cannot be mocked at runtime, but an object property can. This small tradeoff gives us complete control during tests.

Stub the hook in your tests

Now, in your TWD test, you can use Sinon to control authentication behavior:

import { beforeEach, describe, it, afterEach } from 'twd-js/runner';
import { twd, screenDom, userEvent, expect } from 'twd-js';
import authSession from '../hooks/useAuth';
import Sinon from 'sinon';
import userMock from './userMock.json';
import type { Auth0ContextInterface } from '@auth0/auth0-react';

describe('App tests', () => {
  beforeEach(() => {
    Sinon.resetHistory();
    Sinon.restore();
    twd.clearRequestMockRules();
  });

  afterEach(() => {
    twd.clearRequestMockRules();
  });

  it('should render home page for authenticated user', async () => {
    Sinon.stub(authSession, 'useAuth').returns({
      isAuthenticated: true,
      isLoading: false,
      user: userMock,
      getAccessTokenSilently: Sinon.stub().resolves('fake-token'),
      loginWithRedirect: Sinon.stub().resolves(),
      logout: Sinon.stub().resolves(),
    } as unknown as Auth0ContextInterface);

    await twd.visit('/');
    const welcomeText = await screenDom.findByRole('heading', { name: 'Authenticated area', level: 1 });
    twd.should(welcomeText, 'be.visible');
    const infoText = await screenDom.findByText('You are signed in with Auth0. Manage your profile and jot down quick notes below.');
    twd.should(infoText, 'be.visible');
  });
});

With this setup, you can test any scenario:

User is logged in or logged out
User has different roles or data
Authentication errors

Conclusion

Exporting hooks as mutable objects and stubbing them with Sinon lets you run browser tests in TWD with full control over authentication behavior. This allows you to focus on testing your app’s behavior, without worrying about the complexities of the auth provider itself.

Full example React app with this flow: twd-auth0-pkce
Auth flow with backend sessions example: twd-auth0
Official TWD documentation: twd.dev

This approach isn’t just for Auth0 — it works for any module you need to control in TWD browser tests.

TWD 1.4.x is out – focused on Developer Experience

Kevin Julián Martínez Escobar — Sun, 11 Jan 2026 17:50:51 +0000

We’ve just released TWD 1.4.x, and this version is all about improving the developer experience while testing.

What’s new?

Better testing flow

The sidebar now remembers whether it was open or closed using session storage.
When you reload the page while testing, TWD brings you back to the same test, so you can continue right where you left off.

Custom theming

You can now theme the sidebar to match your product or brand colors.
This makes TWD feel more integrated into your app instead of a foreign tool.

Theming docs: https://twd.dev/theming.html

New testing examples

We’ve added more real-world examples to show how TWD fits into modern apps:

React Router framework mode testing examples: https://twd.dev/frameworks.html#react-router-framework-mode
Auth0 authorization flow testing: https://github.com/BRIKEV/twd-auth0

shadcn/ui testing guide

If you’re using shadcn/ui, we also published a full guide showing how to test all its components using TWD: https://brikev.github.io/twd-shadcn/

This isn’t a massive release in terms of features, but it includes several UX and DX improvements, plus a refreshed default theme, to make day-to-day testing smoother and more pleasant.

As always, feedback is welcome.

Modern Frontend Frameworks Are Failing at Testing

Kevin Julián Martínez Escobar — Sat, 27 Dec 2025 19:47:37 +0000

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

What works

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

What doesn’t

SSR frameworks make testing unnecessarily confusing.

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

The problem with SSR frameworks

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

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

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

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

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

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

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

“But you can unit test, right?”

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

What usually happens:

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

Eventually, you fall back to Playwright. And now:

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

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

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

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

React Router loaders and actions: an exception

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

This API is interesting because it allows you to:

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

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

The API design makes testing:

Straightforward
Explicit
Predictable

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

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

Using TWD with React Router

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

Instead of testing routes in isolation, we:

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

Here’s the setup.

Route configuration

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

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

Testing page

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

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

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

Example test

import { createRoot } from "react-dom/client";
import { twd, screenDomGlobal } from "twd-js";

let root: ReturnType<typeof createRoot> | undefined;

export async function setupReactRoot() {
  if (root) {
    root.unmount();
    root = undefined;
  }

  // Navigate to the empty test page
  await twd.visit('/testing');

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

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

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

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

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

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

Conclusion

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

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

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

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

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

An example on how to integrate twd + react router.

Testing shadcn/ui components with TWD

Kevin Julián Martínez Escobar — Tue, 23 Dec 2025 21:56:49 +0000

I’ve put together a small documentation site that shows how to test shadcn/ui components using TWD, built on top of Testing Library.

If you already use Testing Library, this means you can keep the same queries and assertions while gaining the benefits of Testing While Developing: running tests directly inside your real application as you build UI.

This approach helps:

Validate real shadcn components in real screens
Turn manual UI checks into repeatable tests
Keep tests close to real user interactions
Reuse Testing Library knowledge and patterns

You can find the docs and examples here: https://brikev.github.io/twd-shadcn/

The goal is not to replace existing testing tools, but to make UI testing part of the everyday development workflow.

Example: testing a Collapsible component

Given a simple shadcn/ui Collapsible component:

import { Button } from "@/components/ui/button";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible";

export function CollapsibleDemo() {
  return (
    <Collapsible>
      <CollapsibleTrigger asChild>
        <Button variant="outline">Toggle content</Button>
      </CollapsibleTrigger>
      <CollapsibleContent>
        <div className="mt-4 p-4 border rounded-md">
          Here is some hidden content
        </div>
      </CollapsibleContent>
    </Collapsible>
  );
}

With TWD, the test focuses on real user behavior and uses familiar Testing Library-style queries:

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

describe('Collapsible Component', () => {
  it('toggles content visibility on trigger click', async () => {
    await twd.visit('/collapsible');

    const toggleButton = await screenDom.findByRole('button', { name: 'Toggle content' });
    twd.should(toggleButton, 'be.visible');

    // Initially collapsed (content not in DOM)
    let content = screenDom.queryByText('Here is some hidden content');
    expect(content).eql(null);

    // Open
    await userEvent.click(toggleButton);
    const opened = await screenDom.findByText('Here is some hidden content');
    twd.should(opened, 'be.visible');

    // Close
    await userEvent.click(toggleButton);
    const closed = screenDom.queryByText('Here is some hidden content');
    expect(closed).eql(null);
  });
});

The test runs inside the real application, validating the component exactly as a user would interact with it.

TWD 1.3.x release - Multiple framework support

Kevin Julián Martínez Escobar — Mon, 08 Dec 2025 22:15:39 +0000

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

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

At its simplest, all you need is this:

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

  initTWD(tests, { open: true, position: 'left' });
}

React

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

Standard Setup (full control)

if (import.meta.env.DEV) {
  const testModules = import.meta.glob("./**/*.twd.test.ts");
  const { initTests, twd, TWDSidebar } = await import('twd-js');

  initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
  twd.initRequestMocking().catch(console.error);
}

Simplified Setup (bundled)

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

  initTWD(tests, { open: true, position: 'left' });
}

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

Vue

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

Vue Example Repository - Complete working example with advanced scenarios.

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

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

  // Request mocking is automatically initialized
  initTWD(tests);
}

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

Solid

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

Solid Example Repository - Complete Solid.js integration example.

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

import App from './App';

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

  // Request mocking is automatically initialized
  initTWD(tests);
}

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

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

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

Notes for Solid

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

Angular

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

Angular Example Repository - Working Angular integration example.

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

if (isDevMode()) {
  const { initTWD } = await import('twd-js/bundled');

  // Define your test files manually or use a compatible glob importer
  const tests = {
    './twd-tests/helloWorld.twd.test.ts': () => import('./twd-tests/helloWorld.twd.test'),
    './twd-tests/todoList.twd.test.ts': () => import('./twd-tests/todoList.twd.test'),
  };

  // Request mocking is automatically initialized
  initTWD(tests);
}

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

Summary

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

You get the full TWD experience in every environment:

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

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

TWD 1.2.x release - Component mocking, test and ci improvements

Kevin Julián Martínez Escobar — Wed, 26 Nov 2025 23:17:15 +0000

We have some amazing news in the TWD ecosystem! The new v1.2.x release brings several powerful and much-requested features:

describe.only and describe.skip
A brand-new CI tool to simplify integration
Component mocking to test scenarios that normally require external hardware or APIs

Let’s dive into the details

New Describe Methods

As you may know, many test runners let you run only specific describe blocks or skip them entirely. TWD now includes the same functionality.

In the sidebar, you’ll see (only) next to any describe block that is scoped with describe.only.

CI Improvements

Previously, running TWD in CI required Puppeteer and a custom script (still supported if you want full control). But to make the process easier, we’ve moved all of that into a new CLI tool:

twd-cli

Now your entire CI step is just:

npx twd-cli run

By default, this will run tests using the following configuration:

{
  "url": "http://localhost:5173",
  "timeout": 10000,
  "coverage": true,
  "coverageDir": "./coverage",
  "nycOutputDir": "./.nyc_output",
  "headless": true,
  "puppeteerArgs": ["--no-sandbox", "--disable-setuid-sandbox"]
}

You can override any of these by adding a twd.config.json file in your project root.

Example GitHub Action

# Example GitHub Actions workflow
- name: Install dependencies
  run: npm ci

- name: Cache Puppeteer browsers
  uses: actions/cache@v4
  with:
    path: ~/.cache/puppeteer
    key: ${{ runner.os }}-puppeteer-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-puppeteer-

- name: Install Chrome for Puppeteer
  run: npx puppeteer browsers install chrome

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

Component Mocking

To explain this feature properly, I recommend downloading the tutorial repo:

git clone git@github.com:BRIKEV/twd-docs-tutorial.git
cd twd-docs-tutorial
git checkout 07-component-mocking
npm i
# install twd-js version higher or equal than 1.2.1

Then visit: http://localhost:5173/qr-scanner you’ll see this page:

The page includes a QR reader. But how do we test something that relies on external factors like:

A real camera
A real QR code
Browser permissions

What do we actually need to test?

That the UI behaves correctly when the QR is valid
And behaves correctly when errors occur

If we look at the component:

const handleScan = (detectedCodes: Array<{ rawValue: string }>) => {
};

const handleError = (error: Error) => {
};

<Scanner
  onScan={handleScan}
  onError={(error: unknown) => handleError(error as Error)}
/>

So… shouldn’t there be a way to force those events from our test?

Yes. And now TWD allows exactly that.

Adding the Component Mock

Create a test file: qrScanner.twd.test.tsx

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

describe("QR Scanner Page", () => {
  it("should display the QR scanner page", async () => {
    await twd.visit("/qr-scanner");

    const qrScanner = await screenDom.getByText("QR Scanner");
    twd.should(qrScanner, "be.visible");

    const qrScannerButton = await screenDom.getByText("Scan QR Code");
    twd.should(qrScannerButton, "be.visible");

    const detectedCodes = await screenDom.getByText("No codes detected yet");
    twd.should(detectedCodes, "be.visible");
  });
});

Since it's a TSX file, remember to update:
const testModules = import.meta.glob("./**/*.twd.test.{ts,tsx}");

Up to this point we’re just testing UI text. But the important part is the scanner, so let’s mock it.

Mark the component as mockable

In the source code, wrap the scanner:

<MockedComponent name="qrScanner">
  <Scanner
    onScan={handleScan}
    onError={(error: unknown) => handleError(error as Error)}
  />
</MockedComponent>

Add the mock in our test

We'll replace the scanner with a button that triggers the onScan event:

twd.mockComponent("qrScanner", ({
  onScan,
}: {
  onScan: (detectedCodes: Array<{ rawValue: string }>) => void;
}) => {
  return <div>
    <button onClick={() => onScan([{ rawValue: "1234567890" }])}>QR code scanned</button>
  </div>;
});

Now we can test everything that depends on the scan result:

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

describe("QR Scanner Page", () => {
  it("should display the QR scanner page", async () => {
    twd.mockComponent("qrScanner", ({
      onScan,
    }: {
      onScan: (detectedCodes: Array<{ rawValue: string }>) => void;
    }) => {
      return <div>
        <button onClick={() => onScan([{ rawValue: "1234567890" }])}>QR code scanned mocked</button>
      </div>;
    });
    await twd.visit("/qr-scanner");

    const qrScanner = await screenDom.getByText("QR Code Scanner");
    twd.should(qrScanner, "be.visible");

    const qrScannerHeading = await screenDom.getByText("Scan QR Code");
    twd.should(qrScannerHeading, "be.visible");

    let detectedCodes = await screenDom.getByText("No codes detected yet");
    twd.should(detectedCodes, "be.visible");

    const qrCodeScannedButton = await screenDom.getByText("QR code scanned mocked");
    twd.should(qrCodeScannedButton, "be.visible");
    await userEvent.click(qrCodeScannedButton);

    detectedCodes = await screenDom.getByText("1 code(s) detected");
    twd.should(detectedCodes, "be.visible");
    const detectedCode = await screenDom.getByText("1234567890");
    twd.should(detectedCode, "be.visible");
  });
});

Some people might think this isn't testing the “real” feature — but it absolutely is.
We’re validating that:

When a scan succeeds, the UI updates correctly
We don’t depend on external hardware
Our feature behaves as expected under all scenarios

This is exactly what TWD is designed for:
Focus on your features, not on third-party constraints.

Final Thoughts

We hope you love these new features. We’ll continue improving TWD to make UI testing simpler, more powerful, and more enjoyable.

If you have ideas, issues, or suggestions, feel free to open a discussion or PR. Happy testing!

Testing While Developing (Part 6): Using Testing Library Selectors

Kevin Julián Martínez Escobar — Sat, 15 Nov 2025 10:59:43 +0000

In this part, we’ll look at a new feature in TWD: support for Testing Library–style selectors.
These selectors are widely known in the community, and while you could technically use them before (TWD is very flexible), now they’re fully integrated — including visual selection in the sidebar.

Before You Start

If you’re following along from Part 5, you can continue as is. But if you want to reset your repo or make sure you're on the correct branch:

# Repo git clone git@github.com:BRIKEV/twd-docs-tutorial.git
git reset --hard
git clean -d -f
git checkout 06-selectors-testing-library
npm run serve:dev

Let’s Begin

We’re going to migrate our current twd.get calls (which uses querySelector and we were using data-testid in previous post) to the new Testing Library selectors.

Using screenDom

First, update your src/twd-tests/helloWorld.twd.test.ts file.

// We will change this
const title = await twd.get("[data-testid='welcome-title']");
// to this
const title = await screenDom.getByText("Welcome to TWD");

For assertions, we’ll use a new command: twd.should.
It works exactly like element.should, but can be used with any element returned by screenDom.

Your updated test will look like this:

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

describe("Hello World Page", () => {
  it("should display the welcome title and counter button", async () => {
    await twd.visit("/");

    const title = await screenDom.getByText("Welcome to TWD");
    twd.should(title, 'be.visible');

    const counterButton = await screenDom.getByText("Count is 0");
    twd.should(counterButton, 'be.visible');

    await userEvent.click(counterButton);
    twd.should(counterButton, 'have.text', 'Count is 1');

    await userEvent.click(counterButton);
    twd.should(counterButton, 'have.text', 'Count is 2');

    await userEvent.click(counterButton);
    twd.should(counterButton, 'have.text', 'Count is 3');
  });
});

You can mix both approaches.
twd.get includes a built-in .should, while screenDom lets you use familiar Testing Library selectors, combined with twd.should.

Todo list Tests

Here’s how the Todo tests look after migrating to testing-library selectors:

import { twd, expect, userEvent, screenDom } from "twd-js";
import { describe, it, beforeEach } from "twd-js/runner";
import todoListMock from "./mocks/todoList.json";

describe("Todo List Page", () => {
  beforeEach(() => {
    twd.clearRequestMockRules();
  });

  it("should display the todo list", async () => {
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: todoListMock,
      status: 200,
    });
    await twd.visit("/todos");
    await twd.waitForRequest("getTodoList");

    const todo1Title = await screenDom.getByText("Learn TWD");
    twd.should(todo1Title, "be.visible");

    const todo2Title = await screenDom.getByText("Build Todo App");
    twd.should(todo2Title, "be.visible");

    const todo1Description = await screenDom.getByText("Understand how to use TWD for testing web applications");
    twd.should(todo1Description, "be.visible");

    const todo2Description = await screenDom.getByText("Create a todo list application to demonstrate TWD features");
    twd.should(todo2Description, "be.visible");

    const todo1Date = await screenDom.getByText("Date: 2024-12-20");
    twd.should(todo1Date, "be.visible");

    const todo2Date = await screenDom.getByText("Date: 2024-12-25");
    twd.should(todo2Date, "be.visible");
  });

  it("should create a todo", async () => {
    await twd.mockRequest("createTodo", {
      method: "POST",
      url: "/api/todos",
      response: todoListMock[0],
      status: 200,
    });
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: [],
      status: 200,
    });
    await twd.visit("/todos");
    await twd.waitForRequest("getTodoList");

    const noTodosMessage = await screenDom.getByText("No todos yet. Create one above!");
    twd.should(noTodosMessage, "be.visible");

    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: [
        todoListMock[0]
      ],
      status: 200,
    });

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

    const descriptionInput = await screenDom.getByLabelText("Description");
    await userEvent.type(descriptionInput, "Test Description");

    const dateInput = await screenDom.getByLabelText("Date");
    await userEvent.type(dateInput, "2024-12-20");

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

    await twd.waitForRequest("getTodoList");
    const rule = await twd.waitForRequest("createTodo");
    expect(rule.request).to.deep.equal({
      title: "Test Todo",
      description: "Test Description",
      date: "2024-12-20",
    });

    const todoList = await screenDom.getAllByText(/Learn TWD|Build Todo App|Test Todo/);
    expect(todoList).to.have.length(1);
  });

  it("should delete a todo", async () => {
    await twd.mockRequest("deleteTodo", {
      method: "DELETE",
      url: "/api/todos/1",
      response: null,
      status: 200,
    });
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: todoListMock,
      status: 200,
    });
    await twd.visit("/todos");

    // Find the delete button for the first todo (Learn TWD)
    // Since there are multiple delete buttons, we'll get all and use the first one
    // which corresponds to the first todo item
    const deleteButtons = await screenDom.getAllByRole("button", { name: "Delete" });
    const deleteButton = deleteButtons[0];

    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: todoListMock.filter((todo) => todo.id !== "1"),
      status: 200,
    });

    await userEvent.click(deleteButton);
    await twd.waitForRequest("deleteTodo");
    await twd.waitForRequest("getTodoList");

    const todoList = await screenDom.getAllByText(/Learn TWD|Build Todo App/);
    expect(todoList).to.have.length(1);
    twd.should(todoList[0], "be.visible");
  });
});

Conclusion

As you can see, TWD is flexible enough to support both styles of selectors.
And remember: these tests run inside your actual application, so anything your app can access—stores, utilities, helpers—can be used to set up your scenarios.

TWD is all about keeping testing close to development, while staying simple, flexible, and intuitive.

More posts coming soon. More info in our official docs.

Testing While Developing (Part 5): Collecting Coverage

Kevin Julián Martínez Escobar — Mon, 10 Nov 2025 00:09:09 +0000

TWD still has many more advanced features — such as function mocking — but with what we’ve covered so far, you already have everything a solid testing tool needs.
In this step, we’ll see how to collect code coverage from your TWD tests and visualize it locally or in CI.

Before You Start

If you’re following along from Part 4, you can continue as is. But if you want to reset your repo or make sure you're on the correct branch:

# Repo git clone git@github.com:BRIKEV/twd-docs-tutorial.git
git reset --hard
git clean -d -f
git checkout 05-coverage
npm run serve:dev

Instrumenting the Vite App

We’ll use the vite-plugin-istanbul plugin to instrument our code and generate coverage data.

npm i --save-dev vite-plugin-istanbul

Then, open your vite.config.ts and add the plugin:

/// <reference types="vitest" />
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// add plugin for code coverage
import istanbul from 'vite-plugin-istanbul';

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    // configure istanbul plugin
    istanbul({
      include: 'src/**/*',
      exclude: ['node_modules', 'tests/'],
      extension: ['.ts', '.tsx'],
      requireEnv: process.env.CI ? true : false,
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  server: {
    watch: {
      ignored: ["**/data/data.json", "**data/routes.json"],
    },
  },
})

This plugin automatically adds coverage data to window.__coverage__, which means we can later extract it from Puppeteer during our CI run.

Using twd-cli

You only need to run a command

npx twd-cli run

Updating the Puppeteer Script (Manual setup)

Let’s update our scripts/run-tests-ci.js script to collect that coverage and save it locally:

import fs from 'fs';
import path from 'path';
import puppeteer from "puppeteer";
import { reportResults } from 'twd-js/runner-ci';

// Determine project root
let __dirname = path.resolve();

const browser = await puppeteer.launch({
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
});
const page = await browser.newPage();
console.time('Total Test Time');
try {
  // Navigate to your development server
  console.log('Navigating to http://localhost:5173 ...');
  await page.goto('http://localhost:5173');
  // wait to load data-testid="twd-sidebar"
  await page.waitForSelector('[data-testid="twd-sidebar"]', { timeout: 10000 });
  console.log('Page loaded. Starting tests...');
  // reload page
  // Execute all tests
  const { handlers, testStatus } = await page.evaluate(async () => {
    const TestRunner = window.__testRunner;
    const testStatus = [];
    const runner = new TestRunner({
      onStart: () => {},
      onPass: (test) => {
        testStatus.push({ id: test.id, status: "pass" });
      },
      onFail: (test, err) => {
        testStatus.push({ id: test.id, status: "fail", error: err.message });
      },
      onSkip: (test) => {
        testStatus.push({ id: test.id, status: "skip" });
      },
    });
    const handlers = await runner.runAll();
    return { handlers: Array.from(handlers.values()), testStatus };
  });
  console.log(`Tests to report: ${testStatus.length}`);

  // Display results in console
  reportResults(handlers, testStatus);

  // --- Collect coverage ---
  const coverage = await page.evaluate(() => window.__coverage__);
  if (coverage) {
    console.log('Collecting code coverage data...');
    const coverageDir = path.resolve(__dirname, './coverage');
    const nycDir = path.resolve(__dirname, './.nyc_output');
    if (!fs.existsSync(nycDir)) {
      fs.mkdirSync(nycDir);
    }
    if (!fs.existsSync(coverageDir)) {
      fs.mkdirSync(coverageDir);
    }
    const coveragePath = path.join(nycDir, 'out.json');
    fs.writeFileSync(coveragePath, JSON.stringify(coverage));
    console.log(`Code coverage data written to ${coveragePath}`);
  } else {
    console.log('No code coverage data found.');
  }

  // Exit with appropriate code
  const hasFailures = testStatus.some(test => test.status === 'fail');
  console.timeEnd('Total Test Time');
  process.exit(hasFailures ? 1 : 0);

} catch (error) {
  console.error('Error running tests:', error);
  process.exit(1);
} finally {
  console.log('Closing browser...');
  await browser.close();
}

Updating package.json Scripts

{
  "scripts": {
    // ...
    "dev:ci": "CI=true VITE_COVERAGE=true vite",
    "test:ci": "node scripts/run-tests-ci.js",
    "collect:coverage:html": "npx nyc report --reporter=html --report-dir=coverage",
    "collect:coverage:lcov": "npx nyc report --reporter=lcov --report-dir=coverage",
    "collect:coverage:text": "npx nyc report --reporter=text --report-dir=coverage"
  }
}

Now, run these in two terminals:

npm run dev:ci

And in another terminal:

npm run test:ci

Once the tests complete, you can generate coverage reports in different formats:

npm run collect:coverage:html
npm run collect:coverage:lcov
npm run collect:coverage:text

You’ll see something like this:

Adding Coverage to GitHub Actions

To include the coverage output in your GitHub Action, just update your existing CI workflow:

name: CI - PR Tests

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Start Vite dev server
        run: |
          nohup npm run dev:ci > vite.log 2>&1 &
          npx wait-on http://localhost:5173
        env:
          CI: true

      - name: Run Puppeteer tests (test:ci)
        run: npm run test:ci
        env:
          CI: true

      - name: Display coverage
        run: |
          npm run collect:coverage:text

With the new Display coverage step, you’ll see the coverage summary directly in your GitHub Action logs:

Having this basic configuration, it’s entirely up to you how you want to handle the coverage results.
You can publish them to a service like Codecov or Coveralls, display them as badges in your README, or even use them in your CI pipeline to fail a build if coverage drops below a threshold.
What matters is that the library gives you the flexibility to collect and track coverage directly from your browser tests, without relying on a separate test runner.

Conclusion

And that’s it — we’ve reached the end of the TWD tutorial series!

Throughout these five parts, we’ve built a complete workflow from zero to production-ready testing:

Setup and first visit test
Selectors, assertions, and user events
Network mocking
CI integration with Puppeteer
Code coverage collection and reporting

With this foundation, you can now test your apps as you develop them, keeping your environment close to what your users actually see — which is what TWD (Test While Developing) is all about.

Thanks for following along, and happy testing!
You can always explore more in our official docs.

Testing While Developing (Part 4): Running Tests in CI

Kevin Julián Martínez Escobar — Mon, 10 Nov 2025 00:06:43 +0000

In Part 3, we explored one of TWD’s core features — network mocking — and completed our first full set of tests.
Now, it’s time to take the next step: running those tests in the terminal so we can integrate them into a CI workflow.

To do this, we’ll use Puppeteer and one of TWD’s utilities, reportResults, to display test results directly in the console.

Before You Start

If you’re following along from Part 3, you can continue as is. But if you want to reset your repo or make sure you're on the correct branch:

# Repo git clone git@github.com:BRIKEV/twd-docs-tutorial.git
git reset --hard
git clean -d -f
git checkout 04-ci-integration
npm run serve:dev

Running Tests in the Terminal

TWD exposes its runner on the window object, which means you can programmatically execute your tests from any environment — including tools like Puppeteer.

Here’s the basic version of that script:

import { reportResults } from 'twd-js/runner-ci';

const TestRunner = window.__testRunner;
const testStatus = [];
const runner = new TestRunner({
  onStart: () => {},
  onPass: (test) => {
    testStatus.push({ id: test.id, status: "pass" });
  },
  onFail: (test, err) => {
    testStatus.push({ id: test.id, status: "fail", error: err.message });
  },
  onSkip: (test) => {
    testStatus.push({ id: test.id, status: "skip" });
  },
});
const handlers = await runner.runAll();
// report results
reportResults(handlers, testStatus);

That’s the core logic we need to run TWD tests headlessly — but we still need a way to access the window context.
Let’s do that by using Puppeteer.

This was simplified to only use twd-cli command.

npx twd-cli run

Step 1. Install Dependencies (manual setup)

npm install --save-dev puppeteer

Step 2. Create a CI Script

Let’s create a new file: scripts/run-tests-ci.js:

import puppeteer from "puppeteer";
import { reportResults } from 'twd-js/runner-ci';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox'],
});
const page = await browser.newPage();
console.time('Total Test Time');
try {
  // Navigate to your development server
  console.log('Navigating to http://localhost:5173 ...');
  await page.goto('http://localhost:5173');
  // wait to load data-testid="twd-sidebar"
  await page.waitForSelector('[data-testid="twd-sidebar"]', { timeout: 10000 });
  console.log('Page loaded. Starting tests...');
  // reload page
  // Execute all tests
  const { handlers, testStatus } = await page.evaluate(async () => {
    const TestRunner = window.__testRunner;
    const testStatus = [];
    const runner = new TestRunner({
      onStart: () => {},
      onPass: (test) => {
        testStatus.push({ id: test.id, status: "pass" });
      },
      onFail: (test, err) => {
        testStatus.push({ id: test.id, status: "fail", error: err.message });
      },
      onSkip: (test) => {
        testStatus.push({ id: test.id, status: "skip" });
      },
    });
    const handlers = await runner.runAll();
    return { handlers: Array.from(handlers.values()), testStatus };
  });
  console.log(`Tests to report: ${testStatus.length}`);

  // Display results in console
  reportResults(handlers, testStatus);

  // Exit with appropriate code
  const hasFailures = testStatus.some(test => test.status === 'fail');
  console.timeEnd('Total Test Time');
  process.exit(hasFailures ? 1 : 0);

} catch (error) {
  console.error('Error running tests:', error);
  process.exit(1);
} finally {
  console.log('Closing browser...');
  await browser.close();
}

Step 3. Add the Script to package.json

{
  "scripts": {
    // ...
    "test:ci": "node scripts/run-tests-ci.js"
  }
}

Now, with your development server running in another terminal, execute:

npm run test:ci

And you should see something like this:

GitHub Actions Integration

We’re still working on a built-in CI solution, but for now you can easily integrate TWD with GitHub Actions using Puppeteer.

Create a file at .github/workflows/ci.yml:

name: CI - PR Tests

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Start Vite dev server
        run: |
          nohup npm run dev > vite.log 2>&1 &
          npx wait-on http://localhost:5173
        env:
          CI: true

      - name: Run Puppeteer tests (test:ci)
        run: npm run test:ci
        env:
          CI: true

And that’s it — your tests will now run automatically in CI.

What’s Next

We’ve learned how TWD integrates smoothly into CI workflows.
The next step is to collect code coverage, the last missing piece of most testing setups — and that’s exactly what we’ll cover in the next post.

You can always check out our official docs to learn more.

Testing While Developing (Part 3): Mocking API Requests

Kevin Julián Martínez Escobar — Mon, 10 Nov 2025 00:04:48 +0000

In Part 2, we explored assertions, selectors, and user interactions in TWD.
We used those tools to test the homepage, which only had a single button.

Now, it’s time to move to the /todos page — which brings more realistic functionality:

Display Todos
Create Todos
Remove Todos

This page uses an API created with json-server.
We could run our tests directly against the real API like before, but that would modify local data and require resetting the database between tests. That’s not ideal — we want each test to be fully independent.

That’s where mocking comes in.

In TWD, we recommend mocking your network requests so you can test your frontend without backend dependencies. This approach brings several advantages:

You can simulate any scenario: success, errors, or missing data.
You can validate the UX for those edge cases.
You can reproduce bugs easily by mocking the exact request that caused them.

To achieve this, TWD provides utilities for mocking requests using Service Workers that intercept network traffic.

Let’s dive in.

Before You Start

If you’re following along from Part 2, you can continue as is. But if you want to reset your repo or make sure you're on the correct branch:

# Repo git clone git@github.com:BRIKEV/twd-docs-tutorial.git
git reset --hard
git clean -d -f
git checkout 03-network-mocking
npm run serve:dev

Installing the Service Worker

We have a command to install the Service Worker that handles request interception:

npx twd-js init public --save

This command creates a mock-sw.js file in the folder you specify.
Since we’re using Vite, it will be stored inside the public folder.

After that, initialize the worker in your src/main.tsx file:

if (import.meta.env.DEV) {
  // You choose how to load the tests; this example uses Vite's glob import
  const testModules = import.meta.glob("./**/*.twd.test.ts");
  const { initTests, twd, TWDSidebar } = await import('twd-js');
  // You need to pass the test modules, the sidebar component, and createRoot function
  initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
  // if you want to use mock requests, you can initialize it here
  twd.initRequestMocking()
    .then(() => {
      console.log("Request mocking initialized");
    })
    .catch((err) => {
      console.error("Error initializing request mocking:", err);
    });
}

Displaying Todos

Create a new file src/twd-tests/todoList.twd.test.ts and start with a basic test:

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

describe("Todo List Page", () => {
  it("should display the todo list", async () => {
    await twd.visit("/todos");
  });
});

This test simply visits the /todos page and loads the real API data:

Now let’s mock the request so we can control the response.

await twd.mockRequest("getTodoList", {
  method: "GET",
  url: "/api/todos",
  response: [],
  status: 200,
});

This method receives an alias and a configuration object — including the HTTP method, URL, mocked response, and status code.
There are more options (check our docs for all available fields).

Now the complete test looks like this:

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

describe("Todo List Page", () => {
  it("should display the todo list", async () => {
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: [],
      status: 200,
    });
    await twd.visit("/todos");
  });
});

This will show an empty list — exactly what we defined:

This is extremely powerful because it lets you simulate all possible frontend scenarios — from successful responses to errors — without relying on your backend.
You can even capture real requests from bugs and replay them as tests.

Now let’s build a complete test with real data.

Mocking with Real Data

Create a mock file: src/twd-tests/mocks/todoList.json

[
  {
    "id": "1",
    "title": "Learn TWD",
    "description": "Understand how to use TWD for testing web applications",
    "date": "2024-12-20"
  },
  {
    "id": "2",
    "title": "Build Todo App",
    "description": "Create a todo list application to demonstrate TWD features",
    "date": "2024-12-25"
  }
]

And now the complete test:

import { twd } from "twd-js";
import { describe, it } from "twd-js/runner";
import todoListMock from "./mocks/todoList.json";

describe("Todo List Page", () => {
  it("should display the todo list", async () => {
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: todoListMock,
      status: 200,
    });
    await twd.visit("/todos");
    await twd.waitForRequest("getTodoList");
    const todo1Title = await twd.get("[data-testid='todo-title-1']");
    todo1Title.should("have.text", "Learn TWD");
    const todo2Title = await twd.get("[data-testid='todo-title-2']");
    todo2Title.should("have.text", "Build Todo App");
    const todo1Description = await twd.get("[data-testid='todo-description-1']");
    todo1Description.should("have.text", "Understand how to use TWD for testing web applications");
    const todo2Description = await twd.get("[data-testid='todo-description-2']");
    todo2Description.should("have.text", "Create a todo list application to demonstrate TWD features");
    const todo1Date = await twd.get("[data-testid='todo-date-1']");
    todo1Date.should("have.text", "Date: 2024-12-20");
    const todo2Date = await twd.get("[data-testid='todo-date-2']");
    todo2Date.should("have.text", "Date: 2024-12-25");
  });
});

The new command here is:

await twd.waitForRequest("getTodoList");

It waits until the mocked request is triggered — useful when you need to ensure data is rendered before asserting UI state.

Always define mockRequest before triggering the request (clicks, submits, or navigation).
If you mock it too late, it might not intercept properly.

Creating a Todo

When testing the “create todo” feature, we need to verify:

The form is filled correctly
The correct data is sent
The list refreshes after submission
The new element appears in the list

Let’s define our request mocks first:

// request of creating a todo
await twd.mockRequest("createTodo", {
  method: "POST",
  url: "/api/todos",
  response: todoListMock[0],
  status: 200,
});
// empty list on first load
await twd.mockRequest("getTodoList", {
  method: "GET",
  url: "/api/todos",
  response: [],
  status: 200,
});

Then visit the page and confirm it’s empty:

await twd.visit("/todos");
await twd.waitForRequest("getTodoList");
const noTodosMessage = await twd.get("[data-testid='no-todos-message']");
noTodosMessage.should("be.visible");

Next, update the mock to include a new todo after creation:

await twd.mockRequest("getTodoList", {
  method: "GET",
  url: "/api/todos",
  response: [todoListMock[0]],
  status: 200,
});

Fill and submit the form:

const title = await twd.get("input[name='title']");
await userEvent.type(title.el, "Test Todo");
const description = await twd.get("input[name='description']");
await userEvent.type(description.el, "Test Description");
const date = await twd.get("input[name='date']");
await userEvent.type(date.el, "2024-12-20");
const submitButton = await twd.get("button[type='submit']");
// submit
await userEvent.click(submitButton.el);
// we wait for the list request to be made
await twd.waitForRequest("getTodoList");

Finally, we validate both the request body and updated list:

import { twd, expect, userEvent } from "twd-js";

// all waits return the rule with the definition and request made
const rule = await twd.waitForRequest("createTodo");
// we can validate the request sent to the backend
expect(rule.request).to.deep.equal({
  title: "Test Todo",
  description: "Test Description",
  date: "2024-12-20",
});
const todoList = await twd.getAll("[data-testid='todo-item']");
expect(todoList).to.have.length(1);

expect assertions (from Chai) only show up in the sidebar on failure — unlike .should which always displays. We use Chai as these tests execute in the browser

Full Example

Here’s the complete file, including a best practice: use twd.clearRequestMockRules() in a beforeEach() to ensure every test runs independently.

import { twd, expect, userEvent } from "twd-js";
import { describe, it, beforeEach } from "twd-js/runner";
import todoListMock from "./mocks/todoList.json";

describe("Todo List Page", () => {
  beforeEach(() => {
    twd.clearRequestMockRules();
  });

  // ... display test ...

  it("should create a todo", async () => {
    await twd.mockRequest("createTodo", {
      method: "POST",
      url: "/api/todos",
      response: todoListMock[0],
      status: 200,
    });
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: [],
      status: 200,
    });
    await twd.visit("/todos");
    await twd.waitForRequest("getTodoList");
    await twd.mockRequest("getTodoList", {
      method: "GET",
      url: "/api/todos",
      response: [todoListMock[0]],
      status: 200,
    });
    const noTodosMessage = await twd.get("[data-testid='no-todos-message']");
    noTodosMessage.should("be.visible");
    const title = await twd.get("input[name='title']");
    await userEvent.type(title.el, "Test Todo");
    const description = await twd.get("input[name='description']");
    await userEvent.type(description.el, "Test Description");
    const date = await twd.get("input[name='date']");
    await userEvent.type(date.el, "2024-12-20");
    const submitButton = await twd.get("button[type='submit']");
    await userEvent.click(submitButton.el);
    await twd.waitForRequest("getTodoList");
    const rule = await twd.waitForRequest("createTodo");
    expect(rule.request).to.deep.equal({
      title: "Test Todo",
      description: "Test Description",
      date: "2024-12-20",
    });
    const todoList = await twd.getAll("[data-testid='todo-item']");
    expect(todoList).to.have.length(1);
  });
});

Removing Todos

For deleting todos, we reuse what we’ve learned — mocking, waiting, and validating.

it("should delete a todo", async () => {
  await twd.mockRequest("deleteTodo", {
    method: "DELETE",
    url: "/api/todos/1",
    response: null,
    status: 200,
  });
  await twd.mockRequest("getTodoList", {
    method: "GET",
    url: "/api/todos",
    response: todoListMock,
    status: 200,
  });
  await twd.visit("/todos");
  const deleteButton = await twd.get("[data-testid='delete-todo-1']");
  await twd.mockRequest("getTodoList", {
    method: "GET",
    url: "/api/todos",
    response: todoListMock.filter((todo) => todo.id !== "1"),
    status: 200,
  });
  await userEvent.click(deleteButton.el);
  await twd.waitForRequest("deleteTodo");
  await twd.waitForRequest("getTodoList");
  const todoList = await twd.getAll("[data-testid='todo-item']");
  expect(todoList).to.have.length(1);
});

What's next

We’ve covered one of the most important parts of the TWD approach — mocking.
This is where the framework truly shines.

A few closing thoughts:

Use mocks to test what you’re building — your frontend. Don’t worry about backend or third-party services during development.
These mocks only intercept client-side requests (SSR is out of scope).
You’ll have all possible scenarios documented as runnable tests — no setup, no servers, just npm i.

We strongly believe this is the most efficient way to develop and test modern SPAs.
It keeps your workflow fast, predictable, and resilient to backend changes.

In the next post, we’ll take things further by adding terminal execution for CI.

DEV Community: Kevin Julián Martínez Escobar

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

The Problem: Allow AI Know Your Project

The Solution: TWD + Skills

/twd:setup — The Most Important First Step

What /twd:setup Does

How It Looks in Practice

Why This Matters

Final Thought

TWD Project Setup

Step 1: Auto-Detect Project Settings

Step 2: Ask Questions

Batch 1: Project basics (confirm auto-detected values)

Batch 2: Testing concerns (need user input)

Step 3: Generate .claude/twd-patterns.md

Standard Imports

Visit Paths

Standard beforeEach / afterEach

API Service Types

CSS / Component Library

Auth Middleware

Route → Permission Mapping

Third-Party Modules

Portals and Dialogs

Output

Are Developers Still Learning, or Just Using AI?

AI Cannot Replace Understanding

The Knowledge Gap

Where This Shows the Most

Testing

Accessibility

The New Developer Loop

I Am Also In That Loop

Ask Yourself This

TWD Tip: Stub Auth0 Hooks and Mock React Modules

Tool for spying and mocking

Understand the Auth0 hook

Move auth logic to a separate file

Stub the hook in your tests

Conclusion

TWD 1.4.x is out – focused on Developer Experience

What’s new?

Better testing flow

Custom theming

New testing examples

shadcn/ui testing guide

Modern Frontend Frameworks Are Failing at Testing

What works

What doesn’t

The problem with SSR frameworks

“But you can unit test, right?”

React Router loaders and actions: an exception

Using TWD with React Router

Route configuration

Testing page

Example test

Conclusion

Testing shadcn/ui components with TWD

Example: testing a Collapsible component

TWD 1.3.x release - Multiple framework support

React

Standard Setup (full control)

Simplified Setup (bundled)

Vue

Solid

Notes for Solid

Angular

Summary

TWD 1.2.x release - Component mocking, test and ci improvements

New Describe Methods

CI Improvements

Example GitHub Action

Component Mocking

Adding the Component Mock

Mark the component as mockable

Add the mock in our test

Final Thoughts

Testing While Developing (Part 6): Using Testing Library Selectors

Before You Start

Let’s Begin

Step 3: Generate `.claude/twd-patterns.md`