feather-testing-core 0.1.1 → 0.2.0

package/README.md

@@ -1,20 +1,75 @@
 # feather-testing-core
 
+A readable testing DSL that turns async test boilerplate into fluent, chainable steps.
+
 Part of the [Feather Framework](https://github.com/siraj-samsudeen/feather-framework) ecosystem.
 
-Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library.
+## The Core Idea
+
+This DSL defines a universal vocabulary — `fillIn`, `clickButton`, `assertText`, and more — that can be backed by **any** test framework. Playwright and React Testing Library are just the first two adapters. You write your tests once in a fluent, chainable style; the adapter handles the framework-specific details.
 
-Write browser tests that read like user stories:
+### Before / After — Playwright E2E
 
+**Before (Vanilla Playwright):**
 ```ts
-await session
-  .visit("/projects")
-  .clickLink("New Project")
-  .fillIn("Name", "My Project")
-  .submit()
-  .assertText("My Project");
+test("sign up", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByText("Hello, Anonymous!")).toBeVisible();
+  await page.getByText("Sign up instead").click();
+  await page.getByLabel("Email").fill("e2e@example.com");
+  await page.getByLabel("Password").fill("password123");
+  await page.getByRole("button", { name: "Sign up" }).click();
+  await expect(page.getByText("Hello! You are signed in.")).toBeVisible();
+});
+```
+
+**After:**
+```ts
+test("sign up", async ({ session }) => {
+  await session
+    .visit("/")
+    .assertText("Hello, Anonymous!")
+    .click("Sign up instead")
+    .fillIn("Email", "e2e@example.com")
+    .fillIn("Password", "password123")
+    .clickButton("Sign up")
+    .assertText("Hello! You are signed in.");
+});
+```
+
+### Before / After — React Testing Library
+
+**Before (Vanilla RTL):**
+```ts
+test("form submission", async () => {
+  render(<App />);
+  const user = userEvent.setup();
+
+  await user.type(screen.getByLabelText("Email"), "test@example.com");
+  await user.type(screen.getByLabelText("Password"), "password123");
+  await user.click(screen.getByRole("button", { name: "Sign in" }));
+  expect(await screen.findByText("Hello! You are signed in.")).toBeInTheDocument();
+});
 ```
 
+**After:**
+```ts
+test("form submission", async () => {
+  render(<App />);
+  const session = createSession();
+
+  await session
+    .fillIn("Email", "test@example.com")
+    .fillIn("Password", "password123")
+    .clickButton("Sign in")
+    .assertText("Hello! You are signed in.");
+});
+```
+
+### Same DSL, Any Backend
+
+Notice both examples use the **exact same methods** — `fillIn`, `clickButton`, `assertText`. The DSL is framework-agnostic. Playwright and React Testing Library are just the first two adapters. You can implement the `TestDriver` interface for any testing library and get the same fluent syntax.
+
 Inspired by [Phoenix Test](https://hexdocs.pm/phoenix_test/PhoenixTest.html) — Elixir's pipe-chain testing DSL.
 
 ## Installation
@@ -114,25 +169,74 @@ Every method returns `this` for chaining. A single `await` at the start of the c
 | `check(label)` / `uncheck(label)` | Toggle checkbox by label |
 | `choose(label)` | Select radio button by label |
 | `submit()` | Submit the most recently interacted form (see below) |
+| `upload(label, path)` | Set a file input (found by label) to the file at `path` |
+| `dropFile(selector, path)` | Dispatch a `DataTransfer` drop of the file onto a drop area |
 
 #### 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">`
+1. **By `type="submit"`** — looks for `<button type="submit">` or `<input type="submit">` (the DOM's ground truth)
+2. **By accessible name** — looks for a `<button>` whose name contains "submit" (case-insensitive)
 3. **Enter key fallback** — presses Enter on the last form field
 
 If no form was previously interacted with, `submit()` throws an error.
 
+#### File uploads
+
+```ts
+// Standard file input, found by its label
+await session.upload("Avatar", "fixtures/avatar.png");
+
+// Custom drop area (drag-and-drop upload zones)
+await session.dropFile("#dropzone", "fixtures/report.pdf");
+```
+
+In Playwright, `dropFile` reads the real file and dispatches a `drop` event with a `DataTransfer`. In RTL (JSDOM has no filesystem), both verbs synthesize an empty `File` named after the path's basename — assert on the file name, not its contents.
+
 ### Assertions
 
 | Method | Description |
 |--------|-------------|
 | `assertText(text)` / `refuteText(text)` | Assert text is visible / not visible |
+| `assertValue(label, value)` | Assert a field (by label or placeholder) has this value |
+| `assertChecked(label)` / `refuteChecked(label)` | Assert a checkbox is checked / not checked |
+| `assertSelected(label, optionLabel)` | Assert the select's currently selected option |
+| `assertOptions(label, [labels])` | Assert a select offers exactly these options, in order |
 | `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) |
 
+#### Form-state assertions
+
+```ts
+await session
+  .fillIn("Email", "a@b.com")
+  .assertValue("Email", "a@b.com")
+  .check("Subscribe")
+  .assertChecked("Subscribe")
+  .refuteChecked("Receive ads")
+  .selectOption("Plan", "Pro")
+  .assertSelected("Plan", "Pro")
+  .assertOptions("Plan", ["Free", "Pro", "Enterprise"]);
+```
+
+In Playwright these are backed by `toHaveValue` / `toBeChecked` / `toHaveText`, so they auto-retry. The RTL adapter polls the DOM with `waitFor` for the same retry semantics.
+
+#### Pair every refute with a positive assertion
+
+`refuteText` / `refuteHas` assert *absence* — and absence also holds when the page failed to render at all. A blank page passes `refuteHas(".delete-button")`. Always pair a refute with a positive assertion on the same region so the test proves the page actually rendered:
+
+```ts
+// ❌ Passes even if the action bar never rendered
+await session.refuteHas(".action-bar button", { text: "Delete" });
+
+// ✅ The positive complement proves the action bar rendered with exactly [Import]
+await session
+  .assertHas(".action-bar button", { count: 1 })
+  .assertHas(".action-bar button", { text: "Import" })
+  .refuteHas(".action-bar button", { text: "Delete" });
+```
+
 #### `assertHas` / `refuteHas` options
 
 | Option | Type | Description |
@@ -162,6 +266,8 @@ await session.refuteHas(".card", { text: "Deleted Item" });
 
 #### `assertPath` / `refutePath` options
 
+The path is compared against the URL's parsed `pathname` exactly — `assertPath("/import")` does **not** pass on `/re/import`.
+
 ```ts
 // Assert path (ignores query params)
 await session.assertPath("/projects");
@@ -189,6 +295,19 @@ await session
   .assertText("Dashboard"); // back to full-page scope after within()
 ```
 
+### Escape hatch: `step(name, fn)`
+
+When you need something the DSL doesn't cover, queue a named custom step instead of abandoning the chain. The callback receives the adapter's context — `{ page, scope }` for Playwright, `{ user, container }` for RTL — and the name shows up in `StepError` output like any built-in step:
+
+```ts
+await session
+  .visit("/board")
+  .step("drag card to Done column", async ({ page }) => {
+    await page.getByText("My card").dragTo(page.locator("#done"));
+  })
+  .assertText("Done (1)");
+```
+
 ### Debug
 
 | Method | Description |
@@ -261,6 +380,10 @@ Chain:
     [skipped] assertText('Hello! You are signed in.')
 ```
 
+The session keeps a history of executed steps, so when you break a flow into multiple chains (multiple `await`s), the `StepError` still shows the full walk — steps from earlier chains appear as `[ok]` above the failing chain.
+
+With the Playwright adapter, each queued step is also wrapped in `test.step()`, so chains appear as named steps in the trace viewer and HTML report.
+
 ## RTL Adapter Limitations
 
 The RTL adapter runs in JSDOM, which has no real browser. These methods are not available and will throw:

package/dist/playwright/driver.d.ts

@@ -1,6 +1,12 @@
 import { type Page, type Locator } from "@playwright/test";
 import type { AssertHasOptions, AssertPathOptions, TestDriver } from "../types.js";
-export declare class PlaywrightDriver implements TestDriver {
+/** Context handed to custom step() callbacks in the Playwright adapter. */
+export interface PlaywrightStepContext {
+    page: Page;
+    /** Current scope: the page, or the container locator inside within(). */
+    scope: Page | Locator;
+}
+export declare class PlaywrightDriver implements TestDriver<PlaywrightStepContext> {
     private page;
     private scope;
     private lastFormLocator;
@@ -9,19 +15,29 @@ export declare class PlaywrightDriver implements TestDriver {
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
     clickButton(text: string): Promise<void>;
+    private fieldByLabelOrPlaceholder;
     fillIn(label: string, value: string): Promise<void>;
     selectOption(label: string, option: string): Promise<void>;
     check(label: string): Promise<void>;
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
+    upload(label: string, path: string): Promise<void>;
+    dropFile(selector: string, path: string): Promise<void>;
     assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     assertText(text: string): Promise<void>;
     refuteText(text: string): Promise<void>;
+    assertValue(label: string, value: string): Promise<void>;
+    assertChecked(label: string): Promise<void>;
+    refuteChecked(label: string): Promise<void>;
+    assertSelected(label: string, optionLabel: string): Promise<void>;
+    assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
     refutePath(path: string): Promise<void>;
-    within(selector: string): Promise<TestDriver>;
+    step(fn: (context: PlaywrightStepContext) => Promise<unknown>): Promise<void>;
+    within(selector: string): Promise<TestDriver<PlaywrightStepContext>>;
     debug(): Promise<void>;
+    wrapStep(name: string, fn: () => Promise<void>): Promise<void>;
 }
 //# sourceMappingURL=driver.d.ts.map

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;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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/playwright/driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAgB,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,IAAI,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC;CACvB;AAED,qBAAa,gBAAiB,YAAW,UAAU,CAAC,qBAAqB,CAAC;IAItE,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;IAI9C,OAAO,CAAC,yBAAyB;IAW3B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD,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,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD,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,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAajE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvC,IAAI,CACR,EAAE,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC;IAIV,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC;IAMpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAUrE"}

package/dist/playwright/driver.js

@@ -1,4 +1,6 @@
-import { expect } from "@playwright/test";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { expect, test } from "@playwright/test";
 export class PlaywrightDriver {
     page;
     scope;
@@ -19,18 +21,20 @@ export class PlaywrightDriver {
     async clickButton(text) {
         await this.scope.getByRole("button", { name: text }).click();
     }
+    fieldByLabelOrPlaceholder(label) {
+        // .or() lets Playwright auto-wait on whichever appears, so
+        // async-rendered labeled fields don't fall through to the
+        // placeholder branch. Placeholder matching is exact — substring
+        // matching would collide with labels ("Name" vs placeholder
+        // "Nickname") and trip strict mode.
+        return this.scope
+            .getByLabel(label)
+            .or(this.scope.getByPlaceholder(label, { exact: true }));
+    }
     async fillIn(label, value) {
-        const byLabel = this.scope.getByLabel(label);
-        if ((await byLabel.count()) > 0) {
-            await byLabel.fill(value);
-            this.lastFormLocator = this.scope.locator("form", { has: byLabel });
-            return;
-        }
-        const byPlaceholder = this.scope.getByPlaceholder(label);
-        await byPlaceholder.fill(value);
-        this.lastFormLocator = this.scope.locator("form", {
-            has: byPlaceholder,
-        });
+        const field = this.fieldByLabelOrPlaceholder(label);
+        await field.fill(value);
+        this.lastFormLocator = this.scope.locator("form", { has: field });
     }
     async selectOption(label, option) {
         const select = this.scope.getByLabel(label);
@@ -57,18 +61,18 @@ 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"
+        // First try: an explicit type="submit" element — the DOM's ground truth
+        const submitBtn = this.lastFormLocator.locator('button[type="submit"], input[type="submit"]');
+        if ((await submitBtn.count()) > 0) {
+            await submitBtn.first().click();
+            return;
+        }
+        // Second try: a button whose accessible name contains "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
@@ -78,6 +82,22 @@ export class PlaywrightDriver {
                 .press("Enter");
         }
     }
+    async upload(label, path) {
+        const input = this.scope.getByLabel(label);
+        await input.setInputFiles(path);
+        this.lastFormLocator = this.scope.locator("form", { has: input });
+    }
+    async dropFile(selector, path) {
+        const content = await readFile(path);
+        const name = basename(path);
+        const dataTransfer = await this.page.evaluateHandle(([fileName, base64]) => {
+            const dt = new DataTransfer();
+            const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+            dt.items.add(new File([bytes], fileName));
+            return dt;
+        }, [name, content.toString("base64")]);
+        await this.scope.locator(selector).dispatchEvent("drop", { dataTransfer });
+    }
     async assertHas(selector, opts) {
         let locator = this.scope.locator(selector);
         if (opts?.text) {
@@ -109,19 +129,45 @@ export class PlaywrightDriver {
     async refuteText(text) {
         await expect(this.scope.getByText(text)).toHaveCount(0);
     }
+    async assertValue(label, value) {
+        await expect(this.fieldByLabelOrPlaceholder(label)).toHaveValue(value);
+    }
+    async assertChecked(label) {
+        await expect(this.scope.getByLabel(label)).toBeChecked();
+    }
+    async refuteChecked(label) {
+        await expect(this.scope.getByLabel(label)).not.toBeChecked();
+    }
+    async assertSelected(label, optionLabel) {
+        const select = this.scope.getByLabel(label);
+        await expect(select.locator("option:checked")).toHaveText(optionLabel);
+    }
+    async assertOptions(label, optionLabels) {
+        const select = this.scope.getByLabel(label);
+        await expect(select.locator("option")).toHaveText(optionLabels);
+    }
     async assertPath(path, opts) {
         if (opts?.queryParams) {
             const params = new URLSearchParams(opts.queryParams).toString();
             await expect(this.page).toHaveURL(`${path}?${params}`);
         }
         else {
-            const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-            await expect(this.page).toHaveURL(new RegExp(`^[^?]*${escaped}(\\?.*)?$`));
+            await expect
+                .poll(() => new URL(this.page.url()).pathname, {
+                message: `assertPath('${path}')`,
+            })
+                .toBe(path);
         }
     }
     async refutePath(path) {
-        const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        await expect(this.page).not.toHaveURL(new RegExp(`^[^?]*${escaped}(\\?.*)?$`));
+        await expect
+            .poll(() => new URL(this.page.url()).pathname, {
+            message: `refutePath('${path}')`,
+        })
+            .not.toBe(path);
+    }
+    async step(fn) {
+        await fn({ page: this.page, scope: this.scope });
     }
     async within(selector) {
         const scopedLocator = this.scope.locator(selector);
@@ -134,4 +180,15 @@ export class PlaywrightDriver {
             fullPage: true,
         });
     }
+    async wrapStep(name, fn) {
+        try {
+            // Throws when not running inside @playwright/test — fall back to
+            // executing the step directly.
+            test.info();
+        }
+        catch {
+            return fn();
+        }
+        return test.step(name, fn);
+    }
 }

package/dist/playwright/index.d.ts

@@ -1,12 +1,13 @@
 import { type Page } from "@playwright/test";
 import { Session } from "../session.js";
+import { type PlaywrightStepContext } from "./driver.js";
 export { Session } from "../session.js";
 export { StepError } from "../errors.js";
-export { PlaywrightDriver } from "./driver.js";
+export { PlaywrightDriver, type PlaywrightStepContext } from "./driver.js";
 export type { AssertHasOptions, AssertPathOptions, TestDriver, } from "../types.js";
-export declare function createSession(page: Page): Session;
+export declare function createSession(page: Page): Session<PlaywrightStepContext>;
 export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
-    session: Session;
+    session: Session<PlaywrightStepContext>;
 }, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;
 export { expect } from "@playwright/test";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playwright/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAEjD;AAED,eAAO,MAAM,IAAI;aAA0B,OAAO;sGAIhD,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playwright/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAoB,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAExE;AAED,eAAO,MAAM,IAAI;aAA0B,OAAO,CAAC,qBAAqB,CAAC;sGAIvE,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/rtl/driver.d.ts

@@ -1,14 +1,23 @@
+import { screen, within as rtlWithin } from "@testing-library/react";
 import { type UserEvent } from "@testing-library/user-event";
 import type { AssertHasOptions, TestDriver } from "../types.js";
+/** Context handed to custom step() callbacks in the RTL adapter. */
+export interface RTLStepContext {
+    user: UserEvent;
+    /** Current scope: `screen`, or a within()-scoped query container. */
+    container: ReturnType<typeof rtlWithin> | typeof screen;
+}
 /**
  * RTL adapter implementing the subset of TestDriver that applies in JSDOM.
  * Navigation methods (visit, assertPath, refutePath) are not supported.
  */
-export declare class RTLDriver implements TestDriver {
+export declare class RTLDriver implements TestDriver<RTLStepContext> {
     private user;
     private container;
     private lastFormElement;
     constructor(user?: UserEvent, container?: HTMLElement);
+    private rootElement;
+    private findFieldByLabelOrPlaceholder;
     visit(): Promise<void>;
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
@@ -19,13 +28,21 @@ export declare class RTLDriver implements TestDriver {
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
+    upload(label: string, path: string): Promise<void>;
+    dropFile(selector: string, path: string): Promise<void>;
     assertHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
     refuteHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
     assertText(text: string): Promise<void>;
     refuteText(text: string): Promise<void>;
+    assertValue(label: string, value: string): Promise<void>;
+    assertChecked(label: string): Promise<void>;
+    refuteChecked(label: string): Promise<void>;
+    assertSelected(label: string, optionLabel: string): Promise<void>;
+    assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(): Promise<void>;
     refutePath(): Promise<void>;
-    within(selector: string): Promise<TestDriver>;
+    step(fn: (context: RTLStepContext) => Promise<unknown>): Promise<void>;
+    within(selector: string): Promise<TestDriver<RTLStepContext>>;
     debug(): Promise<void>;
 }
 //# sourceMappingURL=driver.d.ts.map

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;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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/rtl/driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAEN,MAAM,IAAI,SAAS,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO,MAAM,CAAC;CACzD;AAOD;;;GAGG;AACH,qBAAa,SAAU,YAAW,UAAU,CAAC,cAAc,CAAC;IAC1D,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;IAKrD,OAAO,CAAC,WAAW;YAOL,6BAA6B;IAUrC,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;IAOnD,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;IAsBvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvD,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,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAItE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IAM7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/rtl/driver.js

@@ -1,4 +1,4 @@
-import { screen, waitFor, within as rtlWithin } from "@testing-library/react";
+import { fireEvent, 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.
@@ -12,6 +12,20 @@ export class RTLDriver {
         this.user = user ?? userEvent.setup();
         this.container = container ? rtlWithin(container) : screen;
     }
+    rootElement() {
+        return this.container === screen
+            ? document.body
+            : (this.container
+                .container ?? document.body);
+    }
+    async findFieldByLabelOrPlaceholder(label) {
+        try {
+            return await this.container.findByLabelText(label);
+        }
+        catch {
+            return await this.container.findByPlaceholderText(label);
+        }
+    }
     async visit() {
         throw new Error("visit() is not available in the RTL adapter. Render the desired component directly.");
     }
@@ -28,13 +42,7 @@ export class RTLDriver {
         await this.user.click(button);
     }
     async fillIn(label, value) {
-        let input;
-        try {
-            input = await this.container.findByLabelText(label);
-        }
-        catch {
-            input = await this.container.findByPlaceholderText(label);
-        }
+        const input = await this.findFieldByLabelOrPlaceholder(label);
         await this.user.clear(input);
         await this.user.type(input, value);
         this.lastFormElement = input.closest("form");
@@ -71,10 +79,12 @@ export class RTLDriver {
         if (!this.lastFormElement) {
             throw new Error("submit() called but no form was previously interacted with.");
         }
-        const submitBtn = rtlWithin(this.lastFormElement).queryByRole("button", {
-            name: /submit/i,
-        }) ??
-            this.lastFormElement.querySelector('button[type="submit"], input[type="submit"]');
+        // Prefer an explicit type="submit" element (the DOM's ground truth),
+        // then a button whose accessible name contains "submit".
+        const submitBtn = this.lastFormElement.querySelector('button[type="submit"], input[type="submit"]') ??
+            rtlWithin(this.lastFormElement).queryByRole("button", {
+                name: /submit/i,
+            });
         if (submitBtn) {
             await this.user.click(submitBtn);
         }
@@ -82,6 +92,29 @@ export class RTLDriver {
             this.lastFormElement.requestSubmit();
         }
     }
+    async upload(label, path) {
+        const input = await this.container.findByLabelText(label);
+        // JSDOM has no filesystem access; synthesize a File from the basename.
+        const name = path.split(/[\\/]/).pop() ?? path;
+        const file = new File([""], name);
+        await this.user.upload(input, file);
+        this.lastFormElement = input.closest("form");
+    }
+    async dropFile(selector, path) {
+        const target = this.rootElement().querySelector(selector);
+        if (!target) {
+            throw new Error(`dropFile('${selector}'): element not found`);
+        }
+        const name = path.split(/[\\/]/).pop() ?? path;
+        const file = new File([""], name);
+        fireEvent.drop(target, {
+            dataTransfer: {
+                files: [file],
+                items: [{ kind: "file", type: file.type, getAsFile: () => file }],
+                types: ["Files"],
+            },
+        });
+    }
     async assertHas(_selector, _opts) {
         throw new Error("assertHas() with CSS selectors is not recommended in RTL. Use assertText() instead.");
     }
@@ -99,18 +132,62 @@ export class RTLDriver {
             }
         });
     }
+    async assertValue(label, value) {
+        const field = await this.findFieldByLabelOrPlaceholder(label);
+        await waitFor(() => {
+            const actual = field.value;
+            if (actual !== value) {
+                throw new Error(`assertValue('${label}', '${value}'): expected value '${value}', but found '${actual}'.`);
+            }
+        });
+    }
+    async assertChecked(label) {
+        const checkbox = await this.container.findByLabelText(label);
+        await waitFor(() => {
+            if (!checkbox.checked) {
+                throw new Error(`assertChecked('${label}'): expected checkbox to be checked, but it was not.`);
+            }
+        });
+    }
+    async refuteChecked(label) {
+        const checkbox = await this.container.findByLabelText(label);
+        await waitFor(() => {
+            if (checkbox.checked) {
+                throw new Error(`refuteChecked('${label}'): expected checkbox NOT to be checked, but it was.`);
+            }
+        });
+    }
+    async assertSelected(label, optionLabel) {
+        const select = (await this.container.findByLabelText(label));
+        await waitFor(() => {
+            const selected = select.selectedOptions[0]?.textContent?.trim();
+            if (selected !== optionLabel) {
+                throw new Error(`assertSelected('${label}', '${optionLabel}'): expected selected option '${optionLabel}', but found '${selected ?? "(none)"}'.`);
+            }
+        });
+    }
+    async assertOptions(label, optionLabels) {
+        const select = (await this.container.findByLabelText(label));
+        await waitFor(() => {
+            const actual = Array.from(select.querySelectorAll("option")).map((o) => o.textContent?.trim() ?? "");
+            const matches = actual.length === optionLabels.length &&
+                actual.every((text, i) => text === optionLabels[i]);
+            if (!matches) {
+                throw new Error(`assertOptions('${label}'): expected options [${optionLabels.join(", ")}], but found [${actual.join(", ")}].`);
+            }
+        });
+    }
     async assertPath() {
         throw new Error("assertPath() is not available in the RTL adapter (no real URL in JSDOM).");
     }
     async refutePath() {
         throw new Error("refutePath() is not available in the RTL adapter (no real URL in JSDOM).");
     }
+    async step(fn) {
+        await fn({ user: this.user, container: this.container });
+    }
     async within(selector) {
-        const root = this.container === screen
-            ? document.body
-            : (this.container
-                .container ?? document.body);
-        const element = root.querySelector(selector);
+        const element = this.rootElement().querySelector(selector);
         if (!element)
             throw new Error(`within('${selector}'): element not found`);
         return new RTLDriver(this.user, element);

package/dist/rtl/index.d.ts

@@ -1,6 +1,7 @@
 import { Session } from "../session.js";
+import { type RTLStepContext } from "./driver.js";
 export { Session } from "../session.js";
 export { StepError } from "../errors.js";
-export { RTLDriver } from "./driver.js";
-export declare function createSession(): Session;
+export { RTLDriver, type RTLStepContext } from "./driver.js";
+export declare function createSession(): Session<RTLStepContext>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rtl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rtl/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7D,wBAAgB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CAEvD"}

package/dist/session.d.ts

@@ -1,9 +1,10 @@
 import type { AssertHasOptions, AssertPathOptions, TestDriver } from "./types.js";
-export declare class Session implements PromiseLike<void> {
+export declare class Session<TContext = unknown> implements PromiseLike<void> {
     private driver;
     private steps;
+    private executedSteps;
     private stepIndex;
-    constructor(driver: TestDriver);
+    constructor(driver: TestDriver<TContext>);
     then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeSteps;
     private enqueue;
@@ -17,13 +18,27 @@ export declare class Session implements PromiseLike<void> {
     uncheck(label: string): this;
     choose(label: string): this;
     submit(): this;
+    upload(label: string, path: string): this;
+    dropFile(selector: string, path: string): this;
     assertText(text: string): this;
     refuteText(text: string): this;
+    assertValue(label: string, value: string): this;
+    assertChecked(label: string): this;
+    refuteChecked(label: string): this;
+    assertSelected(label: string, optionLabel: string): this;
+    assertOptions(label: string, optionLabels: string[]): this;
     assertHas(selector: string, opts?: AssertHasOptions): this;
     refuteHas(selector: string, opts?: AssertHasOptions): this;
     assertPath(path: string, opts?: AssertPathOptions): this;
     refutePath(path: string): this;
-    within(selector: string, fn: (scoped: Session) => Session): this;
+    /**
+     * Queue a named custom step. `fn` receives the adapter's context
+     * ({ page, scope } for Playwright, { user, container } for RTL), so a
+     * missing verb never forces abandoning the chain. The name shows up in
+     * StepError output like any built-in step.
+     */
+    step(name: string, fn: (context: TContext) => Promise<unknown>): this;
+    within(selector: string, fn: (scoped: Session<TContext>) => Session<TContext>): this;
     debug(): this;
 }
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,qBAAa,OAAQ,YAAW,WAAW,CAAC,IAAI,CAAC;IAInC,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,SAAS,CAAK;gBAEF,MAAM,EAAE,UAAU;IAEtC,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,KAAK,EACpC,WAAW,CAAC,EACR,CAAC,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACnD,IAAI,EACR,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACvD,IAAI,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAIjB,YAAY;IAa1B,OAAO,CAAC,OAAO;IAOf,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMzB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM/B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAM1C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMjD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM3B,MAAM,IAAI,IAAI;IAMd,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAO1D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAO1D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAMxD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI;IAUhE,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAEjB,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,qBAAa,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAE,YAAW,WAAW,CAAC,IAAI,CAAC;IAKvD,OAAO,CAAC,MAAM;IAJ1B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,aAAa,CAAoB;IACzC,OAAO,CAAC,SAAS,CAAK;gBAEF,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC;IAEhD,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,KAAK,EACpC,WAAW,CAAC,EACR,CAAC,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACnD,IAAI,EACR,UAAU,CAAC,EACP,CAAC,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GACvD,IAAI,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAIjB,YAAY;IAuB1B,OAAO,CAAC,OAAO;IAOf,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMzB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM/B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAM1C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMjD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM5B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM3B,MAAM,IAAI,IAAI;IAId,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAM/C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMlC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMlC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAOxD,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI;IAO1D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAO1D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAO1D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAMxD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAMrE,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,GACnD,IAAI;IAUP,KAAK,IAAI,IAAI;CAGd"}

package/dist/session.js

@@ -2,6 +2,7 @@ import { StepError } from "./errors.js";
 export class Session {
     driver;
     steps = [];
+    executedSteps = [];
     stepIndex = 0;
     constructor(driver) {
         this.driver = driver;
@@ -12,12 +13,16 @@ export class Session {
     async executeSteps() {
         const steps = [...this.steps];
         this.steps = [];
-        for (const step of steps) {
+        const wrap = this.driver.wrapStep?.bind(this.driver) ?? ((_name, fn) => fn());
+        for (const [i, step] of steps.entries()) {
             try {
-                await step.action();
+                await wrap(step.name, step.action);
+                this.executedSteps.push(step);
             }
             catch (error) {
-                throw new StepError(step, steps, error);
+                // Include steps executed in earlier chains so the full walk is
+                // visible even when the user broke the chain across multiple awaits.
+                throw new StepError(step, [...this.executedSteps, ...steps.slice(i)], error);
             }
         }
     }
@@ -57,6 +62,12 @@ export class Session {
     submit() {
         return this.enqueue("submit()", () => this.driver.submit());
     }
+    upload(label, path) {
+        return this.enqueue(`upload('${label}', '${path}')`, () => this.driver.upload(label, path));
+    }
+    dropFile(selector, path) {
+        return this.enqueue(`dropFile('${selector}', '${path}')`, () => this.driver.dropFile(selector, path));
+    }
     // --- Assertions ---
     assertText(text) {
         return this.enqueue(`assertText('${text}')`, () => this.driver.assertText(text));
@@ -64,6 +75,22 @@ export class Session {
     refuteText(text) {
         return this.enqueue(`refuteText('${text}')`, () => this.driver.refuteText(text));
     }
+    assertValue(label, value) {
+        return this.enqueue(`assertValue('${label}', '${value}')`, () => this.driver.assertValue(label, value));
+    }
+    assertChecked(label) {
+        return this.enqueue(`assertChecked('${label}')`, () => this.driver.assertChecked(label));
+    }
+    refuteChecked(label) {
+        return this.enqueue(`refuteChecked('${label}')`, () => this.driver.refuteChecked(label));
+    }
+    assertSelected(label, optionLabel) {
+        return this.enqueue(`assertSelected('${label}', '${optionLabel}')`, () => this.driver.assertSelected(label, optionLabel));
+    }
+    assertOptions(label, optionLabels) {
+        const list = optionLabels.map((l) => `'${l}'`).join(", ");
+        return this.enqueue(`assertOptions('${label}', [${list}])`, () => this.driver.assertOptions(label, optionLabels));
+    }
     assertHas(selector, opts) {
         const desc = opts?.text
             ? `assertHas('${selector}', text: '${opts.text}')`
@@ -82,6 +109,16 @@ export class Session {
     refutePath(path) {
         return this.enqueue(`refutePath('${path}')`, () => this.driver.refutePath(path));
     }
+    // --- Escape hatch ---
+    /**
+     * Queue a named custom step. `fn` receives the adapter's context
+     * ({ page, scope } for Playwright, { user, container } for RTL), so a
+     * missing verb never forces abandoning the chain. The name shows up in
+     * StepError output like any built-in step.
+     */
+    step(name, fn) {
+        return this.enqueue(`step('${name}')`, () => this.driver.step(fn));
+    }
     // --- Scoping ---
     within(selector, fn) {
         return this.enqueue(`within('${selector}')`, async () => {

package/dist/types.d.ts

@@ -12,7 +12,11 @@ export interface QueuedStep {
     action: () => Promise<void>;
     index: number;
 }
-export interface TestDriver {
+/**
+ * TContext is the adapter-specific context handed to custom step() callbacks
+ * (e.g. { page, scope } for Playwright, { user, container } for RTL).
+ */
+export interface TestDriver<TContext = unknown> {
     visit(path: string): Promise<void>;
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
@@ -23,13 +27,26 @@ export interface TestDriver {
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
+    upload(label: string, path: string): Promise<void>;
+    dropFile(selector: string, path: string): Promise<void>;
     assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     assertText(text: string): Promise<void>;
     refuteText(text: string): Promise<void>;
+    assertValue(label: string, value: string): Promise<void>;
+    assertChecked(label: string): Promise<void>;
+    refuteChecked(label: string): Promise<void>;
+    assertSelected(label: string, optionLabel: string): Promise<void>;
+    assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
     refutePath(path: string): Promise<void>;
-    within(selector: string): Promise<TestDriver>;
+    step(fn: (context: TContext) => Promise<unknown>): Promise<void>;
+    within(selector: string): Promise<TestDriver<TContext>>;
     debug(): Promise<void>;
+    /**
+     * Optional hook: wrap a queued step's execution (e.g. in Playwright's
+     * test.step()) so chains appear in trace viewers and reporters.
+     */
+    wrapStep?(name: string, fn: () => Promise<void>): Promise<void>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,QAAQ,GAAG,OAAO;IAC5C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feather-testing-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library",
   "license": "MIT",
   "repository": {
@@ -64,6 +64,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.0",
+    "@types/node": "^26.1.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "jsdom": "^28.1.0",