twd-js 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,7 @@
 # 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)
 [![license](https://img.shields.io/github/license/brikev/twd.svg)](./LICENSE)
 
 > ⚠️ This is a **beta release** – expect frequent updates and possible breaking changes.
@@ -15,13 +16,13 @@ You can install TWD via npm:
 
 ```bash
 # with npm
-npm install twd
+npm install twd-js
 
 # with yarn
-yarn add twd
+yarn add twd-js
 
 # with pnpm
-pnpm add twd
+pnpm add twd-js
 ```
 
 ## How to use
@@ -32,7 +33,7 @@ Add the our React Sidebar component to your application:
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import './index.css'
-import { TWDSidebar } from '../../../src'
+import { TWDSidebar } from 'twd-js'
 import router from './routes.ts'
 import { RouterProvider } from 'react-router'
 
@@ -44,11 +45,11 @@ createRoot(document.getElementById('root')!).render(
 )
 ```
 
-Then, create test files with the `.test.ts` or any extension you want. For example:
+Then, create test files with the `twd.test.ts` or any extension you want. For example:
 
-```tsx
-// src/app.twd-test.ts
-import { describe, it, twd } from "../../../src/twd";
+```ts
+// src/app.twd.test.ts
+import { describe, it, twd } from "twd-js";
 
 beforeEach(() => {
   console.log("Reset state before each test");
@@ -56,8 +57,13 @@ beforeEach(() => {
 
 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");
   });
 });
 ```
@@ -66,8 +72,8 @@ After you create your test you need to load them in your application. You can do
 
 ```ts
 // src/loadTests.ts
-import "./app.twd-test";
-import "./another-test-file.twd-test";
+import "./app.twd.test";
+import "./another-test-file.twd.test";
 // Import other test files here
 ```
 
@@ -89,4 +95,4 @@ import './loadTests' // Import test files
 
 Finally, run your application and open the TWD sidebar to see and run your tests.
 
-
+You can check the [examples](https://github.com/BRIKEV/twd/tree/main/examples) directory for more usage scenarios.

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/commands/mockResponses.d.ts

@@ -0,0 +1,46 @@
+export type Rule = {
+    method: string;
+    url: string | RegExp;
+    response: unknown;
+    alias?: string;
+    executed?: boolean;
+    request?: unknown;
+    status?: number;
+    headers?: Record<string, string>;
+};
+export interface Options {
+    method: string;
+    url: string | RegExp;
+    response: unknown;
+    status?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * 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)
+ *  - `headers`: (optional) Response headers
+ *
+ * @example
+ * ```ts
+ * mockRequest("getUser", {
+ *   method: "GET",
+ *   url: /\/api\/user\/\d+/,
+ *   response: { id: 1, name: "Kevin" },
+ *   status: 200,
+ *   headers: { "x-mock": "true" }
+ * });
+ * ```
+ */
+export declare const mockRequest: (alias: string, options: Options) => 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>;

package/dist/commands/type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Simulates typing text into an input or textarea element, character by character,
+ * dispatching keydown, keypress, input, and keyup events for each character.
+ * This more closely mimics real user input and works with React's state updates.
+ *
+ * @param el The input or textarea element
+ * @param text The text to type
+ * @returns The input element after typing
+ */
+declare const simulateType: (el: HTMLInputElement | HTMLTextAreaElement, text: string) => HTMLInputElement | HTMLTextAreaElement;
+export { simulateType };

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/index.d.ts

@@ -0,0 +1,2 @@
+export * from './twd';
+export { TWDSidebar } from './ui/TWDSidebar';

package/dist/twd-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Types and interfaces for the TWD testing library.
+ *
+ * @module twd-types
+ */
+/**
+ * All supported assertion names for the `should` function.
+ *
+ * @example
+ * api.should("have.text", "Hello");
+ * api.should("be.empty");
+ */
+export type AssertionName = "have.text" | "contain.text" | "be.empty" | "have.attr" | "have.value" | "be.disabled" | "be.enabled" | "be.checked" | "be.selected" | "be.focused" | "be.visible" | "have.class";
+/**
+ * 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 AnyAssertion = Negatable<AssertionName>;
+/**
+ * Argument types for each assertion.
+ */
+export type AssertionArgs = {
+    "have.text": [expected: string];
+    "contain.text": [expected: string];
+    "be.empty": [];
+    "have.attr": [attr: string, value: string];
+    "have.value": [value: string];
+    "be.disabled": [];
+    "be.enabled": [];
+    "be.checked": [];
+    "be.selected": [];
+    "be.focused": [];
+    "be.visible": [];
+    "have.class": [className: string];
+};
+/**
+ * Maps assertion name to its argument tuple.
+ */
+export type ArgsFor<A extends AnyAssertion> = A extends `not.${infer Base extends AssertionName}` ? AssertionArgs[Base] : A extends AssertionName ? AssertionArgs[A] : never;
+/**
+ * Overloads for the `should` function, for best IntelliSense.
+ *
+ * @example
+ * twd.should("have.text", "Hello");
+ * twd.should("be.empty");
+ * twd.should("have.class", "active");
+ */
+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;
+    (name: "not.have.class", className: string): TWDElemAPI;
+};
+/**
+ * The main API returned by `twd.get()`.
+ *
+ * @example
+ * ```ts
+ * const btn = await twd.get("button");
+ * btn.should("have.text", "Clicked").click();
+ *
+ * ```
+ *
+ */
+export interface TWDElemAPI {
+    /** The underlying DOM element. */
+    el: Element;
+    /**
+     * Simulates a user click on the element.
+     * Returns the same API so you can chain more actions.
+     *
+     * @example
+     * ```ts
+     * const button = await twd.get("button");
+     * button.click();
+     *
+     * ```
+     *
+     */
+    click: () => void;
+    /**
+     * Types text into an input element.
+     * @param text The text to type.
+     * @returns The input element.
+     *
+     * @example
+     * ```ts
+     * const email = await twd.get("input#email");
+     * email.type("test@example.com");
+     *
+     * ```
+     *
+     */
+    type: (text: string) => HTMLInputElement | HTMLTextAreaElement;
+    /**
+     * Gets the text content of the element.
+     * @returns The text content.
+     *
+     * @example
+     * ```ts
+     * const para = await twd.get("p");
+     * const content = para.text();
+     * console.log(content);
+     *
+     * ```
+     *
+     */
+    text: () => string;
+    /**
+     * Asserts something about the element.
+     * @param name The name of the assertion.
+     * @param args Arguments for the assertion.
+     * @returns The same API for chaining.
+     *
+     * @example
+     * ```ts
+     * const btn = await twd.get("button");
+     * btn.should("have.text", "Click me").should("not.be.disabled");
+     *
+     * ```
+     *
+     */
+    should: ShouldFn;
+}

package/dist/twd.d.ts

@@ -0,0 +1,116 @@
+import { Options, Rule } from './commands/mockResponses';
+import { TWDElemAPI } from './twd-types';
+import { URLCommandAPI } from './commands/url';
+/**
+ * Stores the function to run before each test.
+ */
+declare let beforeEachFn: (() => void | Promise<void>) | null;
+/**
+ * Registers a function to run before each test.
+ * @example
+ * beforeEach(() => { ... });
+ */
+export declare const beforeEach: (fn: typeof beforeEachFn) => void;
+/**
+ * Groups related tests together.
+ * @example
+ * describe("My group", () => { ... });
+ */
+export declare const describe: (name: string, fn: () => void) => void;
+/**
+ * Defines a test case.
+ * @example
+ * it("does something", async () => { ... });
+ */
+export declare const it: (name: string, fn: () => Promise<void> | void) => void;
+/**
+ * Defines an exclusive test case (only this runs).
+ * @example
+ * itOnly("runs only this", async () => { ... });
+ */
+export declare const itOnly: (name: string, fn: () => Promise<void> | void) => void;
+/**
+ * Skips a test case.
+ * @example
+ * itSkip("skipped test", () => { ... });
+ */
+export declare const itSkip: (name: string, _fn: () => Promise<void> | void) => void;
+interface TWDAPI {
+    /**
+     * Finds an element by selector and returns the TWD API for it.
+     * @param selector CSS selector
+     * @returns {Promise<TWDElemAPI>} The TWD API for the element
+     *
+     * @example
+     * ```ts
+     * const btn = await twd.get("button");
+     *
+     * ```
+     *
+     */
+    get: (selector: string) => Promise<TWDElemAPI>;
+    /**
+     * Simulates visiting a URL (SPA navigation).
+     * @param url The URL to visit
+     *
+     * @example
+     * ```ts
+     * twd.visit("/contact");
+     *
+     * ```
+     */
+    visit: (url: string) => 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)
+     *  - `headers`: (optional) Response headers
+     *
+     * @example
+     * ```ts
+     * mockRequest("getUser", {
+     *   method: "GET",
+     *   url: /\/api\/user\/\d+/,
+     *   response: { id: 1, name: "Kevin" },
+     *   status: 200,
+     *   headers: { "x-mock": "true" }
+     * });
+     * ```
+     */
+    mockRequest: (alias: string, options: Options) => void;
+    /**
+     * Wait for a mocked request to be made.
+     * @param alias The alias of the mock rule to wait for
+     * @return The matched rule (with body if applicable)
+     *
+     * @example
+     * ```ts
+     * const rule = await twd.waitFor("aliasId");
+     * console.log(rule.body);
+     *
+     * ```
+     */
+    waitFor: (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;
+}
+/**
+ * Mini Cypress-style helpers for DOM testing.
+ * @namespace twd
+ */
+export declare const twd: TWDAPI;
+export {};