twd-js 0.4.0 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# twd
+# TWD
 
 [![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)
@@ -12,7 +12,27 @@ TWD (Testing Web Development) is a library designed to seamlessly integrate test
 
 Currently, TWD supports React, with plans to add more frameworks soon.
 
----
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Writing Tests](#writing-tests)
+  - [Test Structure](#test-structure)
+  - [Element Selection](#element-selection)
+  - [Assertions](#assertions)
+  - [User Interactions](#user-interactions)
+- [API Mocking](#api-mocking)
+  - [Setup](#setup)
+  - [Mock Requests](#mock-requests)
+  - [Wait for Requests](#wait-for-requests)
+- [API Reference](#api-reference)
+  - [Test Functions](#test-functions)
+  - [TWD Commands](#twd-commands)
+  - [Assertions](#assertions-1)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
@@ -47,16 +67,39 @@ pnpm add twd-js
    import { createRoot } from "react-dom/client";
    import App from "./App";
    import "./index.css";
-   import { TWDSidebar } from "twd-js";
+
+   // Only load the test sidebar and tests in development mode
+    if (import.meta.env.DEV) {
+      // Use Vite's glob import to find all test files
+      const testModules = import.meta.glob("./**/*.twd.test.ts");
+      const { initViteLoadTests, twd } = await import('twd-js');
+      // Initialize the TWD sidebar and load tests
+      initViteLoadTests(testModules, { open: true, position: 'left' });
+      // Optionally initialize request mocking
+      twd.initRequestMocking()
+        .then(() => {
+          console.log("Request mocking initialized");
+        })
+        .catch((err) => {
+          console.error("Error initializing request mocking:", err);
+        });
+    }
 
    createRoot(document.getElementById("root")!).render(
      <StrictMode>
        <App />
-       <TWDSidebar />
+       <TWDSidebar open={false} />
      </StrictMode>
    );
    ```
 
+   **TWDSidebar Props**
+
+    | Prop      | Type                | Default | Description                                 |
+    |-----------|---------------------|---------|---------------------------------------------|
+    | open      | boolean             | true    | Whether the sidebar is open by default       |
+    | position  | "left" \| "right"   | "left" | Sidebar position (left or right side)
+
 2. **Write your tests:**
 
    Create files ending with `.twd.test.ts` (or any extension you prefer):
@@ -82,47 +125,159 @@ pnpm add twd-js
 
 3. **Auto-load your tests:**
 
-   - With Vite:
+
+   - With Vite and the new TWD loader:
 
      ```ts
-     import { twd } from "twd-js";
-     // src/loadTests.ts
-     import.meta.glob("./**/*.twd.test.ts", { eager: true });
-     // Initialize request mocking once
-     twd
-       .initRequestMocking()
-       .then(() => {
-         console.log("Request mocking initialized");
-       })
-       .catch((err) => {
-         console.error("Error initializing request mocking:", err);
-       });
-     // No need to export anything
+     // src/main.tsx (or your main entry file)
+     import { StrictMode } from 'react';
+     import { createRoot } from 'react-dom/client';
+     import './index.css';
+     import router from './routes.ts';
+     import { RouterProvider } from 'react-router';
+
+     // Only load the test sidebar and tests in development mode
+     if (import.meta.env.DEV) {
+       // Use Vite's glob import to find all test files
+       const testModules = import.meta.glob("./**/*.twd.test.ts");
+       const { initViteLoadTests, twd } = await import('twd-js');
+       // Initialize the TWD sidebar and load tests
+       initViteLoadTests(testModules, { open: true, position: 'left' });
+       // Optionally initialize request mocking
+       twd.initRequestMocking()
+         .then(() => {
+           console.log("Request mocking initialized");
+         })
+         .catch((err) => {
+           console.error("Error initializing request mocking:", err);
+         });
+     }
+     // ...rest of your app bootstrap
+     createRoot(document.getElementById('root')!).render(
+       <StrictMode>
+         <RouterProvider router={router} />
+       </StrictMode>,
+     );
      ```
 
-   - Or manually:
+   - Or manually (not recommended):
 
      ```ts
-     // src/loadTests.ts
-     import "./app.twd.test";
-     import "./another-test-file.twd.test";
+     // src/main.tsx
+     if (import.meta.env.DEV) {
+       const testModules = {
+         './app.twd.test.ts': () => import('./app.twd.test'),
+         './another-test-file.twd.test.ts': () => import('./another-test-file.twd.test'),
+       };
+       const { initViteLoadTests } = await import('twd-js');
+       initViteLoadTests(testModules);
+     }
      ```
 
-   Import `loadTests.ts` in your main entry (e.g., `main.tsx`):
+4. **Run your app and open the TWD sidebar** to see and run your tests in the browser.
 
-   ```tsx
-   import "./loadTests";
-   ```
+## Writing Tests
 
-4. **Run your app and open the TWD sidebar** to see and run your tests in the browser.
+### Test Structure
 
----
+TWD uses a familiar testing structure with `describe`, `it`, `beforeEach`, and other common testing functions:
 
-## Mock Service Worker (API Mocking)
+```ts
+import { describe, it, itSkip, itOnly, beforeEach, twd, userEvent } from "twd-js";
 
-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
+describe("User authentication", () => {
+  beforeEach(() => {
+    // Reset state before each test
+  });
+  it("should login successfully", async () => {
+    twd.visit("/login");
+    // Your test logic here
+  });
+  
+  itSkip("skipped test", () => {
+    // This test will be skipped
+  });
+  
+  itOnly("only this test runs", () => {
+    // Only this test will run when .only is present
+  });
+});
+```
+
+### Element Selection
+
+TWD provides two main methods for selecting elements:
+
+```ts
+// Select a single element
+const button = await twd.get("button");
+const input = await twd.get("input#email");
+
+// Select multiple elements
+const items = await twd.getAll(".item");
+items[0].should("be.visible");
+```
+
+### Assertions
+
+TWD includes a comprehensive set of assertions for testing element states:
+
+```ts
+// Text content
+element.should("have.text", "exact text");
+element.should("contain.text", "partial text");
+element.should("be.empty");
+
+// Attributes and values
+element.should("have.attr", "placeholder", "Type here");
+element.should("have.value", "input value");
+element.should("have.class", "active");
+
+// Element state
+element.should("be.disabled");
+element.should("be.enabled");
+element.should("be.checked");
+element.should("be.selected");
+element.should("be.focused");
+element.should("be.visible");
+
+// Negated assertions
+element.should("not.be.disabled");
+element.should("not.have.text", "wrong text");
+
+// URL assertions
+twd.url().should("eq", "http://localhost:3000/contact");
+twd.url().should("contain.url", "/contact");
+```
+
+### User Interactions
+
+TWD integrates with `@testing-library/user-event` for realistic user interactions:
+
+```ts
+import { userEvent } from "twd-js";
+
+const user = userEvent.setup();
+const button = await twd.get("button");
+const input = await twd.get("input");
+
+// Click interactions
+await user.click(button.el);
+await user.dblClick(button.el);
+
+// Typing
+await user.type(input.el, "Hello World");
+
+// Form interactions
+await user.selectOptions(selectElement.el, "option-value");
+```
+
+## API Mocking
+
+### Setup
+
+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.
 
 Run the following command in your project root:
 
@@ -135,45 +290,170 @@ npx twd-js init <public-dir> [--save]
 
 This will copy `mock-sw.js` to your public directory.
 
-### How to use request mocking in your tests
+### Mock Requests
 
-Just call `await twd.initRequestMocking()` at the start of your test, then use `twd.mockRequest` to define your mocks. Example:
+Use `twd.mockRequest()` to define API mocks in your tests:
 
 ```ts
-import { describe, it, twd, userEvent } from "twd-js";
+import { twd } from "twd-js";
 
-it("fetches a message", async () => {
-  twd.visit("/");
-  const user = userEvent.setup();
-  await twd.mockRequest("message", {
+// Initialize mocking when loading tests
+// await twd.initRequestMocking();
+
+it("fetches user data", async () => {
+  // Mock the API request
+  twd.mockRequest("getUser", {
     method: "GET",
-    url: "https://api.example.com/message",
+    url: "https://api.example.com/user/123",
     response: {
-      value: "Mocked message!",
+      id: 123,
+      name: "John Doe",
+      email: "john@example.com"
     },
+    status: 200,
+    headers: { "Content-Type": "application/json" }
+  });
+  
+  // Trigger the request in your app
+  const button = await twd.get("button[data-testid='load-user']");
+  await userEvent.click(button.el);
+  
+  // Wait for the mock to be called
+  const rule = await twd.waitForRequest("getUser");
+  console.log("Request body:", rule.request);
+  
+  // Clean up mocks after test
+  twd.clearRequestMockRules();
+});
+```
+
+### Wait for Requests
+
+TWD provides utilities to wait for mocked requests:
+
+```ts
+// Wait for a single request
+const rule = await twd.waitForRequest("getUserData");
+
+// Wait for multiple requests
+const rules = await twd.waitForRequests(["getUser", "getPosts"]);
+
+// Access request data
+console.log("Request body:", rule.request);
+console.log("Response:", rule.response);
+```
+
+## API Reference
+
+### Test Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `describe(name, fn)` | Groups related tests | `describe("User login", () => {...})` |
+| `it(name, fn)` | Defines a test case | `it("should login", async () => {...})` |
+| `itOnly(name, fn)` | Runs only this test | `itOnly("focused test", () => {...})` |
+| `itSkip(name, fn)` | Skips this test | `itSkip("broken test", () => {...})` |
+| `beforeEach(fn)` | Runs before each test | `beforeEach(() => {...})` |
+
+### TWD Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `twd.get(selector)` | Select single element | `await twd.get("button")` |
+| `twd.getAll(selector)` | Select multiple elements | `await twd.getAll(".item")` |
+| `twd.visit(url)` | Navigate to URL | `twd.visit("/contact")` |
+| `twd.wait(ms)` | Wait for specified time | `await twd.wait(500)` |
+| `twd.url()` | Get URL API for assertions | `twd.url().should("contain.url", "/home")` |
+
+### Assertions
+
+#### Element Content
+- `have.text` - Exact text match
+- `contain.text` - Partial text match  
+- `be.empty` - Element has no text content
+
+#### Element Attributes
+- `have.attr` - Has specific attribute value
+- `have.value` - Input/textarea value
+- `have.class` - Has CSS class
+
+#### Element State
+- `be.disabled` / `be.enabled` - Form element state
+- `be.checked` - Checkbox/radio state
+- `be.selected` - Option element state
+- `be.focused` - Element has focus
+- `be.visible` - Element is visible
+
+#### URL Assertions
+- `eq` - Exact URL match
+- `contain.url` - URL contains substring
+
+All assertions can be negated with `not.` prefix (e.g., `not.be.disabled`).
+
+## Examples
+
+### Basic Form Testing
+
+```ts
+import { describe, it, twd, userEvent } from "twd-js";
+
+describe("Contact form", () => {
+  it("submits form data", async () => {
+    twd.visit("/contact");
+    
+    const user = userEvent.setup();
+    const emailInput = await twd.get("input#email");
+    const messageInput = await twd.get("textarea#message");
+    const submitBtn = await twd.get("button[type='submit']");
+    
+    await user.type(emailInput.el, "test@example.com");
+    await user.type(messageInput.el, "Hello world");
+    
+    emailInput.should("have.value", "test@example.com");
+    messageInput.should("have.value", "Hello world");
+    
+    await user.click(submitBtn.el);
   });
-  const btn = await twd.get("button[data-twd='message-button']");
-  await user.click(btn.el);
-  await twd.waitForRequest("message");
-  const messageText = await twd.get("p[data-twd='message-text']");
-  messageText.should("have.text", "Mocked message!");
 });
 ```
 
----
+### API Mocking with Authentication
 
-## More Usage Examples
+```ts
+import { describe, it, twd, userEvent } from "twd-js";
 
-See the [examples](https://github.com/BRIKEV/twd/tree/main/examples) directory for more scenarios and advanced usage.
+describe("Protected routes", () => {
+  it("redirects to login when unauthorized", async () => {
+    twd.visit("/dashboard");
+    await twd.wait(100);
+    twd.url().should("contain.url", "/login");
+  });
+  
+  it("loads dashboard with valid session", async () => {
+    // Mock authentication check
+    twd.mockRequest("authCheck", {
+      method: "GET", 
+      url: "/api/auth/me",
+      response: { id: 1, name: "John Doe" }
+    });
+    
+    twd.visit("/dashboard");
+    await twd.waitForRequest("authCheck");
+    
+    const welcome = await twd.get("h1");
+    welcome.should("contain.text", "Welcome, John");
+    
+    twd.clearRequestMockRules();
+  });
+});
+```
 
----
+For more comprehensive examples, see the [examples](https://github.com/BRIKEV/twd/tree/main/examples) directory in the repository.
 
 ## Contributing
 
 Contributions are welcome! Please open issues or pull requests on [GitHub](https://github.com/BRIKEV/twd).
 
----
-
 ## License
 
 This project is licensed under the [MIT License](./LICENSE).