twd-js 0.1.1 → 0.2.0

package/README.md

@@ -3,12 +3,26 @@
 [![CI](https://github.com/BRIKEV/twd/actions/workflows/ci.yml/badge.svg)](https://github.com/BRIKEV/twd/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/twd-js.svg)](https://www.npmjs.com/package/twd-js)
 [![license](https://img.shields.io/github/license/brikev/twd.svg)](./LICENSE)
+[![Maintainability](https://qlty.sh/gh/BRIKEV/projects/twd/maintainability.svg)](https://qlty.sh/gh/BRIKEV/projects/twd)
+[![Code Coverage](https://qlty.sh/gh/BRIKEV/projects/twd/coverage.svg)](https://qlty.sh/gh/BRIKEV/projects/twd)
 
 > ⚠️ This is a **beta release** – expect frequent updates and possible breaking changes.
 
-TWD (Testing Web Development) is a tool designed to help integrating testing while developing web applications. It aims to streamline the testing process and make it easier for developers to write and run tests as they build their applications.
 
-Right now we only support React, but we plan to add support for other frameworks in the future.
+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.
+
+Currently, TWD supports React, with plans to add more frameworks soon.
+
+---
+
+## 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
+- 🛠️ **Works with React** (support for more frameworks coming)
 
 ## Installation
 
@@ -25,74 +39,132 @@ yarn add twd-js
 pnpm add twd-js
 ```
 
-## How to use
 
-Add the our React Sidebar component to your application:
+## Quick Start
+
+1. **Add the TWD Sidebar to your React app:**
+
+   ```tsx
+   import { StrictMode } from 'react';
+   import { createRoot } from 'react-dom/client';
+   import App from './App';
+   import './index.css';
+   import { TWDSidebar } from 'twd-js';
+
+   createRoot(document.getElementById('root')!).render(
+     <StrictMode>
+       <App />
+       <TWDSidebar />
+     </StrictMode>,
+   );
+   ```
+
+2. **Write your tests:**
+
+   Create files ending with `.twd.test.ts` (or any extension you prefer):
+
+   ```ts
+   // src/app.twd.test.ts
+   import { describe, it, twd } from "twd-js";
+
+   beforeEach(() => {
+     // Reset state before each test
+   });
+
+   describe("App interactions", () => {
+     it("clicks the button", async () => {
+       twd.visit("/");
+       const btn = await twd.get("button");
+       btn.click();
+       const message = await twd.get("#message");
+       message.should("have.text", "Hello");
+     });
+   });
+   ```
+
+3. **Auto-load your tests:**
+
+   - With Vite:
+
+     ```ts
+     // src/loadTests.ts
+     const modules = import.meta.glob("./**/*.twd.test.ts", { eager: true });
+     // No need to export anything
+     ```
+
+   - Or manually:
+
+     ```ts
+     // src/loadTests.ts
+     import "./app.twd.test";
+     import "./another-test-file.twd.test";
+     ```
+
+   Import `loadTests.ts` in your main entry (e.g., `main.tsx`):
 
-```tsx
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import './index.css'
-import { TWDSidebar } from 'twd-js'
-import router from './routes.ts'
-import { RouterProvider } from 'react-router'
+   ```tsx
+   import './loadTests';
+   ```
 
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <RouterProvider router={router} />
-    <TWDSidebar />
-  </StrictMode>,
-)
+4. **Run your app and open the TWD sidebar** to see and run your tests in the browser.
+
+---
+
+## Mock Service Worker (API Mocking)
+
+
+TWD provides a CLI to easily set up a mock service worker for API/request mocking in your app. You do **not** need to manually register the service worker in your app—TWD handles this automatically when you use `twd.initRequestMocking()` in your tests.
+
+### Install the mock service worker
+
+Run the following command in your project root:
+
+```bash
+npx twd-mock init <public-dir> [--save]
 ```
 
-Then, create test files with the `twd.test.ts` or any extension you want. For example:
+- Replace `<public-dir>` with the path to your app's public/static directory (e.g., `public/` or `dist/`).
+- Use `--save` to print a registration snippet for your app.
 
-```ts
-// src/app.twd.test.ts
-import { describe, it, twd } from "twd-js";
+This will copy `mock-sw.js` to your public directory.
 
-beforeEach(() => {
-  console.log("Reset state before each test");
-});
 
-describe("App interactions", () => {
-  it("clicks the button", async () => {
-    twd.visit("/"); // Visit the root URL
-    const btn = await twd.get("button");
-    btn.click();
-    const message = await twd.get("#message");
-    // have.text
-    const haveText = await twd.get("#message");
-    haveText.should("have.text", "Hello");
+### How to use request mocking in your tests
+
+Just call `await twd.initRequestMocking()` at the start of your test, then use `twd.mockRequest` to define your mocks. Example:
+
+```ts
+it("fetches a message", async () => {
+  await twd.initRequestMocking();
+  await twd.mockRequest("message", {
+    method: "GET",
+    url: "https://api.example.com/message",
+    response: {
+      value: "Mocked message!",
+    },
   });
+  const btn = await twd.get("button[data-twd='message-button']");
+  btn.click();
+  await twd.waitForRequest("message");
+  const messageText = await twd.get("p[data-twd='message-text']");
+  messageText.should("have.text", "Mocked message!");
 });
 ```
 
-After you create your test you need to load them in your application. You can do this by creating a `loadTests.ts` file and importing all your test files there:
+---
 
-```ts
-// src/loadTests.ts
-import "./app.twd.test";
-import "./another-test-file.twd.test";
-// Import other test files here
-```
+## More Usage Examples
 
-Or if you're using vite you can use Vite's `import.meta.glob` to automatically import all test files in a directory:
+See the [examples](https://github.com/BRIKEV/twd/tree/main/examples) directory for more scenarios and advanced usage.
 
-```ts
-// This automatically imports all files ending with .twd.test.ts
-const modules = import.meta.glob("./**/*.twd.test.ts", { eager: true });
+---
 
-// You don't need to export anything; simply importing this in App.tsx
-// will cause the test files to execute and register their tests.
-```
+## Contributing
 
-Then, import the `loadTests.ts` file in your main application file (e.g., `main.tsx` or `App.tsx`):
+Contributions are welcome! Please open issues or pull requests on [GitHub](https://github.com/BRIKEV/twd).
 
-```tsx
-import './loadTests' // Import test files
-```
+---
 
-Finally, run your application and open the TWD sidebar to see and run your tests.
+## License
 
-You can check the [examples](https://github.com/BRIKEV/twd/tree/main/examples) directory for more usage scenarios.
+This project is licensed under the [MIT License](./LICENSE).

package/dist/asserts/index.d.ts

@@ -1,2 +1,2 @@
 import { AnyAssertion } from '../twd-types';
-export declare const runAssertion: (el: Element, name: AnyAssertion, ...args: any[]) => void;
+export declare const runAssertion: (el: Element, name: AnyAssertion, ...args: any[]) => string;

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const [, , command, targetDir, ...flags] = process.argv;
+
+if (command !== "init") {
+  console.error("Usage: npx twd-mock init <public-dir> [--save]");
+  process.exit(1);
+}
+
+if (!targetDir) {
+  console.error("❌ You must provide a target public dir");
+  process.exit(1);
+}
+
+const save = flags.includes("--save");
+const src = path.join(__dirname, "../dist/mock-sw.js");
+const dest = path.resolve(process.cwd(), targetDir, "mock-sw.js");
+
+fs.mkdirSync(path.dirname(dest), { recursive: true });
+fs.copyFileSync(src, dest);
+
+console.log(`✅ mock-sw.js copied to ${dest}`);
+if (save) {
+  console.log("💡 Remember to register it in your app:");
+  console.log(`
+if ("serviceWorker" in navigator) {
+  navigator.serviceWorker.register("/mock-sw.js?v=1");
+}
+  `);
+}

package/dist/commands/{mockResponses.d.ts → mockBridge.d.ts}

@@ -2,7 +2,7 @@ export type Rule = {
     method: string;
     url: string | RegExp;
     response: unknown;
-    alias?: string;
+    alias: string;
     executed?: boolean;
     request?: unknown;
     status?: number;
@@ -15,6 +15,11 @@ export interface Options {
     status?: number;
     headers?: Record<string, string>;
 }
+/**
+ * Initialize the mocking service worker.
+ * Call this once before using `mockRequest` or `waitFor`.
+ */
+export declare const initRequestMocking: () => Promise<void>;
 /**
  * Mock a network request.
  *
@@ -37,10 +42,19 @@ export interface Options {
  * });
  * ```
  */
-export declare const mockRequest: (alias: string, options: Options) => void;
+export declare const mockRequest: (alias: string, options: Options) => Promise<void>;
 /**
  * Wait for a mocked request to be made.
  * @param alias The alias of the mock rule to wait for
  * @returns The matched rule (with body if applicable)
  */
-export declare const waitFor: (alias: string) => Promise<Rule>;
+export declare const waitForRequest: (alias: string) => Promise<Rule>;
+/**
+ * Get the current list of request mock rules.
+ * @returns The current list of request mock rules.
+ */
+export declare const getRequestMockRules: () => Rule[];
+/**
+ * Clear all request mock rules.
+ */
+export declare const clearRequestMockRules: () => void;

package/dist/commands/url.d.ts

@@ -0,0 +1,33 @@
+/**
+ * All supported assertion names for the `should` function in url command
+ *
+ * @example
+ * twd.url().should("contain.url", "/new-page");
+ * twd.url().should("eq", "http://localhost:3000/new-page");
+ */
+export type URLAssertionName = "eq" | "contain.url";
+/**
+ * Negatable assertion names (e.g., 'not.have.text').
+ */
+export type Negatable<T extends string> = T | `not.${T}`;
+/**
+ * All assertion names, including negated ones.
+ */
+export type AnyURLAssertion = Negatable<URLAssertionName>;
+export type URLCommandAPI = {
+    location: Location;
+    should: (name: AnyURLAssertion, value: string) => URLCommandAPI | string;
+};
+/**
+ * Argument types for each assertion.
+ */
+export type URLAssertionArgs = {
+    (name: "contain.url", urlPart: string): URLCommandAPI;
+    (name: "not.contain.url", urlPart: string): URLCommandAPI;
+};
+/**
+ * URL command for assertions on the current URL.
+ * @returns URLCommandAPI
+ */
+declare const urlCommand: () => URLCommandAPI;
+export default urlCommand;

package/dist/mock-sw.js

@@ -0,0 +1 @@
+function i(t,n,s){return s.find(e=>e.method===t&&(typeof e.url=="string"?e.url===n:new RegExp(e.url).test(n)))}function r(t,n,s){t.forEach(e=>e.postMessage({type:"EXECUTED",alias:n.alias,request:s}))}let l=[];self.addEventListener("fetch",t=>{const{method:n}=t.request,s=t.request.url,e=i(n,s,l);e&&(console.log("Mock hit:",e.alias,n,s),t.respondWith((async()=>{let a=null;try{a=await t.request.clone().text()}catch{}return self.clients.matchAll().then(o=>{r(o,e,a)}),new Response(JSON.stringify(e.response),{status:e.status||200,headers:e.headers||{"Content-Type":"application/json"}})})()))});self.addEventListener("message",t=>{const{type:n,rule:s}=t.data||{};n==="ADD_RULE"&&(l=l.filter(e=>e.alias!==s.alias),l.push(s),console.log("Rule added:",s))});

package/dist/twd-types.d.ts

@@ -50,16 +50,25 @@ export type ArgsFor<A extends AnyAssertion> = A extends `not.${infer Base extend
  */
 export type ShouldFn = {
     (name: "have.text", expected: string): TWDElemAPI;
+    (name: "not.have.text", expected: string): TWDElemAPI;
     (name: "contain.text", expected: string): TWDElemAPI;
+    (name: "not.contain.text", expected: string): TWDElemAPI;
     (name: "be.empty"): TWDElemAPI;
+    (name: "not.be.empty"): TWDElemAPI;
     (name: "have.attr", attr: string, value: string): TWDElemAPI;
+    (name: "not.have.attr", attr: string, value: string): TWDElemAPI;
     (name: "have.value", value: string): TWDElemAPI;
+    (name: "not.have.value", value: string): TWDElemAPI;
     (name: "be.disabled"): TWDElemAPI;
+    (name: "not.be.disabled"): TWDElemAPI;
     (name: "be.enabled"): TWDElemAPI;
+    (name: "not.be.enabled"): TWDElemAPI;
     (name: "be.checked"): TWDElemAPI;
     (name: "not.be.checked"): TWDElemAPI;
     (name: "be.selected"): TWDElemAPI;
+    (name: "not.be.selected"): TWDElemAPI;
     (name: "be.focused"): TWDElemAPI;
+    (name: "not.be.focused"): TWDElemAPI;
     (name: "be.visible"): TWDElemAPI;
     (name: "not.be.visible"): TWDElemAPI;
     (name: "have.class", className: string): TWDElemAPI;
@@ -122,7 +131,7 @@ export interface TWDElemAPI {
     text: () => string;
     /**
      * Asserts something about the element.
-     * @param anyAssertion The assertion to run.
+     * @param name The name of the assertion.
      * @param args Arguments for the assertion.
      * @returns The same API for chaining.
      *

package/dist/twd.d.ts

@@ -1,5 +1,6 @@
-import { Options, Rule } from './commands/mockResponses';
+import { Options, Rule } from './commands/mockBridge';
 import { TWDElemAPI } from './twd-types';
+import { URLCommandAPI } from './commands/url';
 /**
  * Stores the function to run before each test.
  */
@@ -94,7 +95,49 @@ interface TWDAPI {
      *
      * ```
      */
-    waitFor: (alias: string) => Promise<Rule>;
+    waitForRequest: (alias: string) => Promise<Rule>;
+    /**
+     * URL-related assertions.
+     *
+     * @example
+     * ```ts
+     * twd.url().should("eq", "http://localhost:3000/contact");
+     * twd.url().should("contain.url", "/contact");
+     *
+     * ```
+     */
+    url: () => URLCommandAPI;
+    /**
+     * Initializes request mocking (registers the service worker).
+     * Must be called before using `twd.mockRequest()`.
+     *
+     * @example
+     * ```ts
+     * await twd.initRequestMocking();
+     *
+     * ```
+     */
+    initRequestMocking: () => Promise<void>;
+    /**
+     * Clears all request mock rules.
+     *
+     * @example
+     * ```ts
+     * twd.clearRequestMockRules();
+     *
+     * ```
+     */
+    clearRequestMockRules: () => void;
+    /**
+     * Gets all current request mock rules.
+     *
+     * @example
+     * ```ts
+     * const rules = twd.getRequestMockRules();
+     * console.log(rules);
+     * ```
+     */
+    getRequestMockRules: () => Rule[];
 }
 /**
  * Mini Cypress-style helpers for DOM testing.