feather-testing-core 0.1.0 → 0.1.1

package/README.md

@@ -23,6 +23,8 @@ Inspired by [Phoenix Test](https://hexdocs.pm/phoenix_test/PhoenixTest.html) —
 npm install feather-testing-core
 ```
 
+> **Note:** This package is ESM-only (`"type": "module"`). It works with modern bundlers and test runners out of the box. If your project uses CommonJS `require()`, you'll need to update your config to support ESM imports.
+
 All test framework dependencies are optional peers — install only what you use:
 
 ```bash
@@ -111,15 +113,65 @@ Every method returns `this` for chaining. A single `await` at the start of the c
 | `selectOption(label, option)` | Select dropdown option by label |
 | `check(label)` / `uncheck(label)` | Toggle checkbox by label |
 | `choose(label)` | Select radio button by label |
-| `submit()` | Submit the most recently interacted form |
+| `submit()` | Submit the most recently interacted form (see below) |
+
+#### How `submit()` finds the submit button
+
+`submit()` tracks the `<form>` element from the last `fillIn`, `selectOption`, `check`, `uncheck`, or `choose` call, then uses this strategy:
+
+1. **By accessible name** — looks for a `<button>` whose name contains "submit" (case-insensitive)
+2. **By `type="submit"`** — looks for `<button type="submit">` or `<input type="submit">`
+3. **Enter key fallback** — presses Enter on the last form field
+
+If no form was previously interacted with, `submit()` throws an error.
 
 ### Assertions
 
 | Method | Description |
 |--------|-------------|
 | `assertText(text)` / `refuteText(text)` | Assert text is visible / not visible |
-| `assertHas(selector, opts?)` / `refuteHas(...)` | Assert element exists (Playwright only) |
-| `assertPath(path, opts?)` / `refutePath(path)` | Assert URL path (Playwright only) |
+| `assertHas(selector, opts?)` / `refuteHas(...)` | Assert element exists (Playwright only, see options below) |
+| `assertPath(path, opts?)` / `refutePath(path)` | Assert URL path (Playwright only, see options below) |
+
+#### `assertHas` / `refuteHas` options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `text` | `string` | Filter elements to those containing this text |
+| `count` | `number` | Assert exact number of matching elements |
+| `exact` | `boolean` | When `true`, `text` matches as an exact substring. When `false` (default), matches as a regex |
+| `timeout` | `number` | Custom timeout in milliseconds (overrides Playwright default) |
+
+```ts
+// Assert at least one .card element is visible
+await session.assertHas(".card");
+
+// Assert a .card containing specific text
+await session.assertHas(".card", { text: "Overdue" });
+
+// Assert exact count
+await session.assertHas("li.todo-item", { count: 3 });
+
+// Assert with custom timeout
+await session.assertHas(".loaded", { timeout: 10000 });
+
+// Refute: assert no matching elements exist
+await session.refuteHas(".spinner");
+await session.refuteHas(".card", { text: "Deleted Item" });
+```
+
+#### `assertPath` / `refutePath` options
+
+```ts
+// Assert path (ignores query params)
+await session.assertPath("/projects");
+
+// Assert path with specific query params
+await session.assertPath("/search", { queryParams: { q: "hello", page: "1" } });
+
+// Refute: assert you are NOT on this path
+await session.refutePath("/login");
+```
 
 ### Scoping
 
@@ -127,11 +179,21 @@ Every method returns `this` for chaining. A single `await` at the start of the c
 |--------|-------------|
 | `within(selector, fn)` | Scope actions to a container element |
 
+```ts
+// All actions inside the callback are scoped to the matched element
+await session
+  .visit("/dashboard")
+  .within(".sidebar", (s) =>
+    s.clickLink("Settings").assertText("Preferences")
+  )
+  .assertText("Dashboard"); // back to full-page scope after within()
+```
+
 ### Debug
 
 | Method | Description |
 |--------|-------------|
-| `debug()` | Screenshot (Playwright) or log DOM (RTL) |
+| `debug()` | Playwright: saves a full-page screenshot to `debug-{timestamp}.png` in the CWD. RTL: calls `screen.debug()` to log the current DOM to the console. |
 
 ## How It Works
 
@@ -210,7 +272,7 @@ The RTL adapter runs in JSDOM, which has no real browser. These methods are not
 ## Exports
 
 ```ts
-// Core types (for building custom drivers)
+// Core (Session class + types)
 import { Session, StepError, type TestDriver } from "feather-testing-core";
 
 // Playwright adapter
@@ -220,6 +282,13 @@ import { test, createSession, expect } from "feather-testing-core/playwright";
 import { createSession } from "feather-testing-core/rtl";
 ```
 
+Both adapter subpaths also re-export `Session` and `StepError`, so you can import everything from a single path:
+
+```ts
+import { test, Session, StepError } from "feather-testing-core/playwright";
+import { createSession, Session, StepError } from "feather-testing-core/rtl";
+```
+
 ## License
 
 MIT

package/dist/playwright/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/playwright/driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,qBAAa,gBAAiB,YAAW,UAAU;IAI/C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,KAAK;IAJf,OAAO,CAAC,eAAe,CAAwB;gBAGrC,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,IAAI,GAAG,OAAc;IAGhC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBvB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/playwright/driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AACnE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,qBAAa,gBAAiB,YAAW,UAAU;IAI/C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,KAAK;IAJf,OAAO,CAAC,eAAe,CAAwB;gBAGrC,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,IAAI,GAAG,OAAc;IAGhC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BvB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B"}

package/dist/playwright/driver.js

@@ -57,11 +57,21 @@ export class PlaywrightDriver {
             throw new Error("submit() called but no form was previously interacted with. " +
                 "Use fillIn(), selectOption(), check(), uncheck(), or choose() first.");
         }
+        // First try: find a button by accessible name containing "submit"
+        const byRole = this.lastFormLocator.getByRole("button", {
+            name: /submit/i,
+        });
+        if ((await byRole.count()) > 0) {
+            await byRole.first().click();
+            return;
+        }
+        // Second try: find an explicit type="submit" element
         const submitBtn = this.lastFormLocator.locator('button[type="submit"], input[type="submit"]');
         if ((await submitBtn.count()) > 0) {
             await submitBtn.first().click();
         }
         else {
+            // Last resort: press Enter on the last form field
             await this.lastFormLocator
                 .locator("input, textarea, select")
                 .last()
@@ -87,7 +97,9 @@ export class PlaywrightDriver {
     async refuteHas(selector, opts) {
         let locator = this.scope.locator(selector);
         if (opts?.text) {
-            locator = locator.filter({ hasText: opts.text });
+            locator = opts.exact
+                ? locator.filter({ hasText: opts.text })
+                : locator.filter({ hasText: new RegExp(opts.text) });
         }
         await expect(locator).toHaveCount(0, { timeout: opts?.timeout });
     }
@@ -108,10 +120,8 @@ export class PlaywrightDriver {
         }
     }
     async refutePath(path) {
-        const url = new URL(this.page.url());
-        if (url.pathname === path) {
-            throw new Error(`Expected path to NOT be '${path}', but it is.`);
-        }
+        const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        await expect(this.page).not.toHaveURL(new RegExp(`^[^?]*${escaped}(\\?.*)?$`));
     }
     async within(selector) {
         const scopedLocator = this.scope.locator(selector);

package/dist/rtl/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/rtl/driver.ts"],"names":[],"mappings":"AACA,OAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhE;;;GAGG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,eAAe,CAAgC;gBAE3C,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,WAAW;IAK/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBvB,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/rtl/driver.ts"],"names":[],"mappings":"AACA,OAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhE;;;GAGG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,eAAe,CAAgC;gBAE3C,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,WAAW;IAK/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBvB,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/rtl/driver.js

@@ -1,4 +1,4 @@
-import { screen, within as rtlWithin } from "@testing-library/react";
+import { screen, waitFor, within as rtlWithin } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 /**
  * RTL adapter implementing the subset of TestDriver that applies in JSDOM.
@@ -41,7 +41,11 @@ export class RTLDriver {
     }
     async selectOption(label, option) {
         const select = await this.container.findByLabelText(label);
-        await this.user.selectOptions(select, option);
+        const optionEl = Array.from(select.querySelectorAll("option")).find((o) => o.textContent?.trim() === option);
+        if (!optionEl) {
+            throw new Error(`selectOption('${label}', '${option}'): no <option> with text '${option}' found.`);
+        }
+        await this.user.selectOptions(select, optionEl);
         this.lastFormElement = select.closest("form");
     }
     async check(label) {
@@ -88,10 +92,12 @@ export class RTLDriver {
         await this.container.findByText(text);
     }
     async refuteText(text) {
-        const el = this.container.queryByText(text);
-        if (el) {
-            throw new Error(`Expected NOT to find text '${text}', but it was present.`);
-        }
+        await waitFor(() => {
+            const el = this.container.queryByText(text);
+            if (el) {
+                throw new Error(`Expected NOT to find text '${text}', but it was present.`);
+            }
+        });
     }
     async assertPath() {
         throw new Error("assertPath() is not available in the RTL adapter (no real URL in JSDOM).");

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "feather-testing-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/siraj-samsudeen/feather-testing-core"
+  },
   "keywords": [
     "testing",
     "playwright",
@@ -50,12 +54,22 @@
     }
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "vitest run",
+    "test:pw": "playwright test",
+    "test:all": "vitest run && playwright test"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.0",
-    "typescript": "~5.9.3"
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^28.1.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18"
   }
 }