twd-js 1.7.2 → 1.7.3

package/README.md

@@ -1,4 +1,4 @@
-# TWD
+# TWD (Testing while developing)
 
 [![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)
@@ -6,11 +6,11 @@
 [![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)
 
-<p>
-  <img src="./images/logo_full_sized.png" alt="TWD Logo" width="400">
+<p align="center">
+  <img src="./images/twd-skill.gif" alt="TWD running with an AI agent" width="800">
 </p>
 
-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.
+TWD 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](https://brikev.github.io/twd/) | 🚀 [Getting Started](https://brikev.github.io/twd/getting-started) | 📚 [API Reference](https://brikev.github.io/twd/api/)**
 
@@ -166,6 +166,28 @@ Each example includes a complete setup guide and demonstrates best practices for
 
 Contributions are welcome! Please open issues or pull requests on [GitHub](https://github.com/BRIKEV/twd).
 
+## Contributors ✨
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kevinccbsg"><img src="https://avatars.githubusercontent.com/u/12685053?v=4?s=100" width="100px;" alt="Kevin Julián Martínez Escobar"/><br /><sub><b>Kevin Julián Martínez Escobar</b></sub></a><br /><a href="https://github.com/BRIKEV/twd/commits?author=kevinccbsg" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/DamonCaos"><img src="https://avatars.githubusercontent.com/u/169996368?v=4?s=100" width="100px;" alt="Javier Rodriguez"/><br /><sub><b>Javier Rodriguez</b></sub></a><br /><a href="https://github.com/BRIKEV/twd/commits?author=DamonCaos" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/codesthenos"><img src="https://avatars.githubusercontent.com/u/166174180?v=4?s=100" width="100px;" alt="Guillermo Ruiz Arranz"/><br /><sub><b>Guillermo Ruiz Arranz</b></sub></a><br /><a href="https://github.com/BRIKEV/twd/commits?author=codesthenos" title="Code">💻</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome!
+
 ## License
 
 This project is licensed under the [MIT License](./LICENSE).

package/dist/asserts/index.d.ts

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

package/dist/bundled.d.ts

@@ -4,7 +4,7 @@ interface TestModule {
 }
 interface InitTWDOptions {
     open?: boolean;
-    position?: "left" | "right";
+    position?: 'left' | 'right';
     serviceWorker?: boolean;
     serviceWorkerUrl?: string;
     theme?: Partial<TWDTheme>;

package/dist/bundled.es.js

@@ -1,4 +1,4 @@
-var ln = Object.create, Or = Object.defineProperty, on = Object.getOwnPropertyDescriptor, sn = Object.getOwnPropertyNames, un = Object.getPrototypeOf, dn = Object.prototype.hasOwnProperty, w = (e, t) => () => (t || e((t = { exports: {} }).exports, t), t.exports), cn = (e, t, r, a) => {
+var ln = Object.create, Or = Object.defineProperty, on = Object.getOwnPropertyDescriptor, sn = Object.getOwnPropertyNames, un = Object.getPrototypeOf, dn = Object.prototype.hasOwnProperty, w = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t.exports), cn = (e, t, r, a) => {
   if (t && typeof t == "object" || typeof t == "function")
     for (var n = sn(t), i = 0, s = n.length, d; i < s; i++)
       d = n[i], !dn.call(e, d) && d !== r && Or(e, d, {
@@ -990,7 +990,9 @@ var In = () => /* @__PURE__ */ N("svg", {
       node: l,
       depth: c,
       id: l.id,
-      runTest: () => t(l.id)
+      runTest: () => {
+        t(l.id);
+      }
     }, l.id);
     const o = a[l.id];
     return /* @__PURE__ */ N("li", {
@@ -1287,7 +1289,7 @@ var Jn = (e) => {
   }
 };
 window.__testRunner = Gr;
-var $t = "1.7.2", Zn = () => typeof window < "u" ? (window.__TWD_MOCK_STATE__ || (window.__TWD_MOCK_STATE__ = {
+var $t = "1.7.3", Zn = () => typeof window < "u" ? (window.__TWD_MOCK_STATE__ || (window.__TWD_MOCK_STATE__ = {
   rules: [],
   counts: {}
 }), window.__TWD_MOCK_STATE__) : {
@@ -1530,7 +1532,9 @@ var il = (e) => e instanceof Error && "actual" in e && "expected" in e, Yr = (e)
               className: "twd-sidebar-header-buttons",
               children: [
                 /* @__PURE__ */ N("button", {
-                  onClick: R,
+                  onClick: () => {
+                    R();
+                  },
                   className: "twd-btn twd-btn-primary",
                   children: /* @__PURE__ */ N("span", {
                     "aria-live": "polite",

package/dist/cli.js

@@ -1,35 +1,35 @@
 #!/usr/bin/env node
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
+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-js init <public-dir> [--save]");
+if (command !== 'init') {
+  console.error('Usage: npx twd-js init <public-dir> [--save]');
   process.exit(1);
 }
 
 if (!targetDir) {
-  console.error("❌ You must provide a target public dir");
+  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");
+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('💡 Remember to register it in your app:');
   console.log(`
 if ("serviceWorker" in navigator) {
   navigator.serviceWorker.register("/mock-sw.js");
 }
   `);
-}
+}

package/dist/commands/mockBridge.d.ts

@@ -0,0 +1,117 @@
+export type Rule = {
+    /** HTTP method to match (e.g. `"GET"`, `"POST"`). */
+    method: string;
+    /** URL string or RegExp to match against the request URL. */
+    url: string | RegExp;
+    /** The mocked response body returned to the client. */
+    response: unknown;
+    /** Unique identifier for this mock rule, used with `waitForRequest`. */
+    alias: string;
+    /** Whether this rule has been matched by an actual request. Set automatically by the service worker. */
+    executed?: boolean;
+    /**
+     * The parsed request body sent by the client.
+     * For JSON requests this is the parsed object, for form data an object of key/value pairs, for text a string.
+     * Access fields directly: `rule.request.email`, **not** `rule.request.body.email`.
+     */
+    request?: any;
+    /** HTTP status code for the mocked response (default: `200`). */
+    status?: number;
+    /** Headers to include in the mocked response. */
+    responseHeaders?: Record<string, string>;
+    /** Whether the `url` field should be treated as a regex pattern. */
+    urlRegex?: boolean;
+    /** Delay in milliseconds before returning the mocked response. */
+    delay?: number;
+    /** Number of times this rule has been matched. Updated automatically by the service worker. */
+    hitCount?: number;
+};
+export interface Options {
+    /** HTTP method to match (e.g. `"GET"`, `"POST"`). */
+    method: string;
+    /** URL string or RegExp to match against the request URL. */
+    url: string | RegExp;
+    /** The mocked response body returned to the client. */
+    response: unknown;
+    /** HTTP status code for the mocked response (default: `200`). */
+    status?: number;
+    /** Headers to include in the mocked response. */
+    responseHeaders?: Record<string, string>;
+    /** Whether the `url` field should be treated as a regex pattern. */
+    urlRegex?: boolean;
+    /** Delay in milliseconds before returning the mocked response. */
+    delay?: number;
+}
+/**
+ * Initialize the mocking service worker.
+ * Call this once before using `mockRequest` or `waitFor`.
+ */
+export declare const initRequestMocking: (path?: string) => Promise<void>;
+/**
+ * Mock a network request.
+ *
+ * @param alias Identifier for the mock rule. Useful for `waitFor()`.
+ * @param options Options to configure the mock:
+ *  - `method`: HTTP method ("GET", "POST", …)
+ *  - `url`: URL string or RegExp to match
+ *  - `response`: Body of the mocked response
+ *  - `status`: (optional) HTTP status code (default: 200)
+ *  - `responseHeaders`: (optional) Response headers
+ *  - `urlRegex`: (optional) Whether the URL is a regex (default: false)
+ *  - `delay`: (optional) Delay in ms before returning the response
+ *
+ * @example
+ * ```ts
+ * mockRequest("getUser", {
+ *   method: "GET",
+ *   url: /\/api\/user\/\d+/,
+ *   response: { id: 1, name: "Kevin" },
+ *   status: 200,
+ *   responseHeaders: { "x-mock": "true" }
+ * });
+ * ```
+ */
+export declare const mockRequest: (alias: string, options: Options) => Promise<void>;
+/**
+ * wait for a list of mocked requests to be made.
+ * @param aliases The aliases of the mock rules to wait for
+ * @returns The matched rules (with body if applicable)
+ * @example
+ * ```ts
+ * await waitForRequests(["getUser", "postComment"]);
+ * ```
+ */
+export declare const waitForRequests: (aliases: string[]) => Promise<Rule[]>;
+/**
+ * Wait for a mocked request to be made.
+ * @param alias The alias of the mock rule to wait for
+ * @param retries The number of retries to make
+ * @param retryDelay The delay between retries
+ * @returns The matched rule (with body if applicable)
+ */
+export declare const waitForRequest: (alias: string, retries?: number, retryDelay?: number) => 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;
+/**
+ * Get the number of times a specific mock rule was hit.
+ * @param alias The alias of the mock rule
+ * @returns The number of times the rule was matched
+ */
+export declare const getRequestCount: (alias: string) => number;
+/**
+ * Get a snapshot of all mock rule hit counts.
+ * @returns An object mapping rule aliases to their hit counts
+ */
+export declare const getRequestCounts: () => Record<string, number>;
+/**
+ * Reset the initialized state. Only use in tests.
+ * @internal
+ */
+export declare const resetMockingState: () => 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, retries?: number) => Promise<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/commands/viewport.d.ts

@@ -0,0 +1,2 @@
+export declare const viewport: (width?: number, height?: number) => void;
+export declare const resetViewport: () => void;

package/dist/commands/visit.d.ts

@@ -0,0 +1 @@
+export declare const visit: (url: string, reload?: boolean) => Promise<void>;

package/dist/constants/version.d.ts

@@ -0,0 +1 @@
+export declare const TWD_VERSION = "1.7.3";

package/dist/global.d.ts

@@ -0,0 +1,20 @@
+// global.d.ts
+export {};
+
+declare global {
+  interface Window {
+    __testRunner?: any;
+    __TWD_STATE__?: any;
+    __TWD_MOCK_STATE__?: any;
+    __twdCollectMock?: (mock: {
+      alias: string;
+      url: string;
+      method: string;
+      status: number;
+      response: unknown;
+      responseHeaders?: Record<string, string>;
+      urlRegex: boolean;
+      testId: string;
+    }) => void;
+  }
+}