TWD

TWD (Testing Web Development) is a library designed to seamlessly integrate testing into your web development workflow. It streamlines the process of writing, running, and managing tests directly in your application, with a modern UI and powerful mocking capabilities.

📖 Full Documentation | 🚀 Getting Started | 📚 API Reference

Features

• 🧪 In-browser test runner with a beautiful sidebar UI
• ⚡ Instant feedback as you develop
• 🔥 Mock Service Worker integration for API/request mocking
• 📝 Simple, readable test syntax (inspired by popular test frameworks)
• 🧩 Automatic test discovery with Vite support
• 🎯 Testing Library support - Use screenDom for semantic, accessible queries
• 🛠️ Works with React (support for more frameworks coming)

Installation

npm install twd-js
# or
yarn add twd-js
# or
pnpm add twd-js

Quick Start

React / Vue / Angular / Other Frameworks (Bundled / recommended)

TWD now supports any framework via its bundled version.

// 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");
  
  // Initialize TWD with tests and optional configuration
  // Request mocking is automatically initialized by default
  initTWD(tests, { 
    open: true, 
    position: 'left',
    serviceWorker: true,           // Enable request mocking (default: true)
    serviceWorkerUrl: '/mock-sw.js' // Custom service worker path (default: '/mock-sw.js')
  });
}

Set Up Mock Service Worker

If you plan to use API mocking, set up the mock service worker:

npx twd-js init public

Check the Framework Integration Guide for more details.

Writing Tests

// src/app.twd.test.ts
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("/");
    
    // Use Testing Library queries (Recommended - semantic & accessible)
    const title = screenDom.getByRole("heading", { name: /welcome to twd/i });
    twd.should(title, "be.visible");
    twd.should(title, "have.text", "Welcome to TWD");
    
    const counterButton = screenDom.getByRole("button", { name: /count is/i });
    twd.should(counterButton, "be.visible");
    twd.should(counterButton, "have.text", "Count is 0");
    
    const user = userEvent.setup();
    await user.click(counterButton);
    twd.should(counterButton, "have.text", "Count is 1");

    // Alternative: Use TWD's native selectors for direct element access
    // const title = await twd.get("h1");
    // title.should("be.visible").should("have.text", "Welcome to TWD");
  });
});

3. Run your app - The TWD sidebar will appear automatically in development mode!

Key Concepts

Element Selection

TWD supports two approaches:

Testing Library Queries (Recommended):

const button = screenDom.getByRole("button", { name: /submit/i });
twd.should(button, "be.visible");

Native Selectors:

const button = await twd.get("button");
button.should("be.visible");

User Interactions

const user = userEvent.setup();
await user.click(button);
await user.type(input, "Hello World");

API Mocking

twd.mockRequest("getUser", {
  method: "GET",
  url: "/api/user",
  response: { id: 1, name: "John" }
});

const rule = await twd.waitForRequest("getUser");

Documentation

Full documentation is available at twd.dev (coming soon) or in the docs folder.

• Getting Started
• Framework Integration
• Writing Tests
• API Mocking

Examples

Check out our working examples for various frameworks:

• Examples Directory - Local examples for React, Vue, and Astro
• Vue Example - Vue 3 with advanced scenarios
• Solid Example - Solid.js integration
• Angular Example - Angular setup

Each example includes a complete setup guide and demonstrates best practices for testing with TWD including ci integration.

Contributing

Contributions are welcome! Please open issues or pull requests on GitHub.

License

This project is licensed under the MIT License.