feather-testing-core 0.1.0

package/README.md

@@ -0,0 +1,225 @@
+# feather-testing-core
+
+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.
+
+Write browser tests that read like user stories:
+
+```ts
+await session
+  .visit("/projects")
+  .clickLink("New Project")
+  .fillIn("Name", "My Project")
+  .submit()
+  .assertText("My Project");
+```
+
+Inspired by [Phoenix Test](https://hexdocs.pm/phoenix_test/PhoenixTest.html) — Elixir's pipe-chain testing DSL.
+
+## Installation
+
+```bash
+npm install feather-testing-core
+```
+
+All test framework dependencies are optional peers — install only what you use:
+
+```bash
+# For Playwright E2E tests
+npm install @playwright/test
+
+# For React Testing Library integration tests
+npm install @testing-library/react @testing-library/user-event
+```
+
+## Usage
+
+### Playwright E2E
+
+```ts
+// e2e/fixtures.ts
+import { test as featherTest } from "feather-testing-core/playwright";
+export const test = featherTest;
+export { expect } from "@playwright/test";
+```
+
+```ts
+// e2e/auth.spec.ts
+import { test } from "./fixtures";
+
+test("full auth lifecycle", async ({ session }) => {
+  // Sign up
+  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.");
+
+  // Sign out
+  await session
+    .clickButton("Sign out")
+    .assertText("Hello, Anonymous!");
+
+  // Sign in
+  await session
+    .fillIn("Email", "e2e@example.com")
+    .fillIn("Password", "password123")
+    .clickButton("Sign in")
+    .assertText("Hello! You are signed in.");
+});
+```
+
+### React Testing Library
+
+```ts
+import { createSession } from "feather-testing-core/rtl";
+
+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.");
+});
+```
+
+## API
+
+Every method returns `this` for chaining. A single `await` at the start of the chain executes all steps sequentially.
+
+### Navigation
+
+| Method | Description |
+|--------|-------------|
+| `visit(path)` | Navigate to URL (Playwright only) |
+
+### Interactions
+
+| Method | Description |
+|--------|-------------|
+| `click(text)` | Find any element by text and click it |
+| `clickLink(text)` | Click `<a>` by accessible name |
+| `clickButton(text)` | Click `<button>` by accessible name |
+| `fillIn(label, value)` | Fill input by label or placeholder |
+| `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 |
+
+### 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) |
+
+### Scoping
+
+| Method | Description |
+|--------|-------------|
+| `within(selector, fn)` | Scope actions to a container element |
+
+### Debug
+
+| Method | Description |
+|--------|-------------|
+| `debug()` | Screenshot (Playwright) or log DOM (RTL) |
+
+## How It Works
+
+The `Session` class uses a **thenable action-queue pattern**. Each method pushes an async operation onto an internal queue and returns `this`. The class implements `PromiseLike<void>`, so `await` triggers execution of the entire queue.
+
+```
+session.visit("/").fillIn("Name", "x").clickButton("Go")
+       ↓              ↓                    ↓
+    [push thunk]  [push thunk]        [push thunk]
+                                           ↓
+                                    await triggers
+                                    sequential execution
+```
+
+This means you write one `await` per chain, not one per line.
+
+### Breaking chains
+
+If you need conditional logic mid-flow, break into multiple chains:
+
+```ts
+await session.visit("/").fillIn("Email", email);
+
+if (isNewUser) {
+  await session.click("Sign up instead").clickButton("Sign up");
+} else {
+  await session.clickButton("Sign in");
+}
+```
+
+### Composable helpers
+
+Functions that take and return a Session work as reusable steps:
+
+```ts
+function signIn(session: Session, email: string, password: string): Session {
+  return session
+    .fillIn("Email", email)
+    .fillIn("Password", password)
+    .clickButton("Sign in");
+}
+
+test("authenticated flow", async ({ session }) => {
+  await signIn(session.visit("/"), "test@example.com", "pass123")
+    .assertText("Welcome!");
+});
+```
+
+## Error Messages
+
+When a step fails, `StepError` shows the full chain with status markers:
+
+```
+feather-testing-core: Step 4 of 6 failed
+
+Failed at: clickButton('Sign up')
+Cause: locator.click: getByRole('button', { name: 'Sign up' }) resolved to 0 elements
+
+Chain:
+    [ok] visit('/')
+    [ok] assertText('Hello, Anonymous!')
+    [ok] fillIn('Email', 'e2e@example.com')
+>>> [FAILED] clickButton('Sign up')
+    [skipped] fillIn('Password', 'password123')
+    [skipped] assertText('Hello! You are signed in.')
+```
+
+## RTL Adapter Limitations
+
+The RTL adapter runs in JSDOM, which has no real browser. These methods are not available and will throw:
+
+- `visit()` — render the component directly instead
+- `assertPath()` / `refutePath()` — no URL in JSDOM
+- `assertHas()` / `refuteHas()` — RTL discourages CSS selectors; use `assertText()` instead
+
+## Exports
+
+```ts
+// Core types (for building custom drivers)
+import { Session, StepError, type TestDriver } from "feather-testing-core";
+
+// Playwright adapter
+import { test, createSession, expect } from "feather-testing-core/playwright";
+
+// RTL adapter
+import { createSession } from "feather-testing-core/rtl";
+```
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+import type { QueuedStep } from "./types.js";
+export declare class StepError extends Error {
+    constructor(failedStep: QueuedStep, allSteps: QueuedStep[], cause: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,qBAAa,SAAU,SAAQ,KAAK;gBAEhC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,OAAO;CA4BjB"}

package/dist/errors.js

@@ -0,0 +1,21 @@
+export class StepError extends Error {
+    constructor(failedStep, allSteps, cause) {
+        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        const stepList = allSteps
+            .map((step) => {
+            const prefix = step === failedStep ? ">>> " : "    ";
+            const status = step.index < failedStep.index
+                ? "[ok]"
+                : step.index === failedStep.index
+                    ? "[FAILED]"
+                    : "[skipped]";
+            return `${prefix}${status} ${step.name}`;
+        })
+            .join("\n");
+        super(`feather-testing-core: Step ${failedStep.index + 1} of ${allSteps.length} failed\n\n` +
+            `Failed at: ${failedStep.name}\n` +
+            `Cause: ${causeMessage}\n\n` +
+            `Chain:\n${stepList}\n`, { cause });
+        this.name = "StepError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Session } from "./session.js";
+export { StepError } from "./errors.js";
+export type { AssertHasOptions, AssertPathOptions, QueuedStep, TestDriver, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Session } from "./session.js";
+export { StepError } from "./errors.js";

package/dist/playwright/driver.d.ts

@@ -0,0 +1,27 @@
+import { type Page, type Locator } from "@playwright/test";
+import type { AssertHasOptions, AssertPathOptions, TestDriver } from "../types.js";
+export declare class PlaywrightDriver implements TestDriver {
+    private page;
+    private scope;
+    private lastFormLocator;
+    constructor(page: Page, scope?: Page | Locator);
+    visit(path: string): Promise<void>;
+    click(text: string): Promise<void>;
+    clickLink(text: string): Promise<void>;
+    clickButton(text: string): Promise<void>;
+    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>;
+    assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
+    refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
+    assertText(text: string): Promise<void>;
+    refuteText(text: string): Promise<void>;
+    assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
+    refutePath(path: string): Promise<void>;
+    within(selector: string): Promise<TestDriver>;
+    debug(): Promise<void>;
+}
+//# sourceMappingURL=driver.d.ts.map

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

@@ -0,0 +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"}

package/dist/playwright/driver.js

@@ -0,0 +1,127 @@
+import { expect } from "@playwright/test";
+export class PlaywrightDriver {
+    page;
+    scope;
+    lastFormLocator = null;
+    constructor(page, scope = page) {
+        this.page = page;
+        this.scope = scope;
+    }
+    async visit(path) {
+        await this.page.goto(path);
+    }
+    async click(text) {
+        await this.scope.getByText(text).click();
+    }
+    async clickLink(text) {
+        await this.scope.getByRole("link", { name: text }).click();
+    }
+    async clickButton(text) {
+        await this.scope.getByRole("button", { name: text }).click();
+    }
+    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,
+        });
+    }
+    async selectOption(label, option) {
+        const select = this.scope.getByLabel(label);
+        await select.selectOption({ label: option });
+        this.lastFormLocator = this.scope.locator("form", { has: select });
+    }
+    async check(label) {
+        const checkbox = this.scope.getByLabel(label);
+        await checkbox.check();
+        this.lastFormLocator = this.scope.locator("form", { has: checkbox });
+    }
+    async uncheck(label) {
+        const checkbox = this.scope.getByLabel(label);
+        await checkbox.uncheck();
+        this.lastFormLocator = this.scope.locator("form", { has: checkbox });
+    }
+    async choose(label) {
+        const radio = this.scope.getByRole("radio", { name: label });
+        await radio.check();
+        this.lastFormLocator = this.scope.locator("form", { has: radio });
+    }
+    async submit() {
+        if (!this.lastFormLocator) {
+            throw new Error("submit() called but no form was previously interacted with. " +
+                "Use fillIn(), selectOption(), check(), uncheck(), or choose() first.");
+        }
+        const submitBtn = this.lastFormLocator.locator('button[type="submit"], input[type="submit"]');
+        if ((await submitBtn.count()) > 0) {
+            await submitBtn.first().click();
+        }
+        else {
+            await this.lastFormLocator
+                .locator("input, textarea, select")
+                .last()
+                .press("Enter");
+        }
+    }
+    async assertHas(selector, opts) {
+        let locator = this.scope.locator(selector);
+        if (opts?.text) {
+            locator = opts.exact
+                ? locator.filter({ hasText: opts.text })
+                : locator.filter({ hasText: new RegExp(opts.text) });
+        }
+        if (opts?.count !== undefined) {
+            await expect(locator).toHaveCount(opts.count, {
+                timeout: opts?.timeout,
+            });
+        }
+        else {
+            await expect(locator.first()).toBeVisible({ timeout: opts?.timeout });
+        }
+    }
+    async refuteHas(selector, opts) {
+        let locator = this.scope.locator(selector);
+        if (opts?.text) {
+            locator = locator.filter({ hasText: opts.text });
+        }
+        await expect(locator).toHaveCount(0, { timeout: opts?.timeout });
+    }
+    async assertText(text) {
+        await expect(this.scope.getByText(text).first()).toBeVisible();
+    }
+    async refuteText(text) {
+        await expect(this.scope.getByText(text)).toHaveCount(0);
+    }
+    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}(\\?.*)?$`));
+        }
+    }
+    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.`);
+        }
+    }
+    async within(selector) {
+        const scopedLocator = this.scope.locator(selector);
+        await expect(scopedLocator).toBeAttached();
+        return new PlaywrightDriver(this.page, scopedLocator);
+    }
+    async debug() {
+        await this.page.screenshot({
+            path: `debug-${Date.now()}.png`,
+            fullPage: true,
+        });
+    }
+}

package/dist/playwright/index.d.ts

@@ -0,0 +1,12 @@
+import { type Page } from "@playwright/test";
+import { Session } from "../session.js";
+export { Session } from "../session.js";
+export { StepError } from "../errors.js";
+export { PlaywrightDriver } from "./driver.js";
+export type { AssertHasOptions, AssertPathOptions, TestDriver, } from "../types.js";
+export declare function createSession(page: Page): Session;
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
+    session: Session;
+}, 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

@@ -0,0 +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"}

package/dist/playwright/index.js

@@ -0,0 +1,15 @@
+import { test as base } from "@playwright/test";
+import { Session } from "../session.js";
+import { PlaywrightDriver } from "./driver.js";
+export { Session } from "../session.js";
+export { StepError } from "../errors.js";
+export { PlaywrightDriver } from "./driver.js";
+export function createSession(page) {
+    return new Session(new PlaywrightDriver(page));
+}
+export const test = base.extend({
+    session: async ({ page }, use) => {
+        await use(createSession(page));
+    },
+});
+export { expect } from "@playwright/test";

package/dist/rtl/driver.d.ts

@@ -0,0 +1,31 @@
+import { type UserEvent } from "@testing-library/user-event";
+import type { AssertHasOptions, TestDriver } from "../types.js";
+/**
+ * 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 {
+    private user;
+    private container;
+    private lastFormElement;
+    constructor(user?: UserEvent, container?: HTMLElement);
+    visit(): Promise<void>;
+    click(text: string): Promise<void>;
+    clickLink(text: string): Promise<void>;
+    clickButton(text: string): Promise<void>;
+    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>;
+    assertHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
+    refuteHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
+    assertText(text: string): Promise<void>;
+    refuteText(text: string): Promise<void>;
+    assertPath(): Promise<void>;
+    refutePath(): Promise<void>;
+    within(selector: string): Promise<TestDriver>;
+    debug(): Promise<void>;
+}
+//# sourceMappingURL=driver.d.ts.map

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

@@ -0,0 +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"}

package/dist/rtl/driver.js

@@ -0,0 +1,115 @@
+import { screen, 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.
+ * Navigation methods (visit, assertPath, refutePath) are not supported.
+ */
+export class RTLDriver {
+    user;
+    container;
+    lastFormElement = null;
+    constructor(user, container) {
+        this.user = user ?? userEvent.setup();
+        this.container = container ? rtlWithin(container) : screen;
+    }
+    async visit() {
+        throw new Error("visit() is not available in the RTL adapter. Render the desired component directly.");
+    }
+    async click(text) {
+        const element = await this.container.findByText(text);
+        await this.user.click(element);
+    }
+    async clickLink(text) {
+        const link = await this.container.findByRole("link", { name: text });
+        await this.user.click(link);
+    }
+    async clickButton(text) {
+        const button = await this.container.findByRole("button", { name: text });
+        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);
+        }
+        await this.user.clear(input);
+        await this.user.type(input, value);
+        this.lastFormElement = input.closest("form");
+    }
+    async selectOption(label, option) {
+        const select = await this.container.findByLabelText(label);
+        await this.user.selectOptions(select, option);
+        this.lastFormElement = select.closest("form");
+    }
+    async check(label) {
+        const checkbox = await this.container.findByLabelText(label);
+        if (!checkbox.checked) {
+            await this.user.click(checkbox);
+        }
+        this.lastFormElement = checkbox.closest("form");
+    }
+    async uncheck(label) {
+        const checkbox = await this.container.findByLabelText(label);
+        if (checkbox.checked) {
+            await this.user.click(checkbox);
+        }
+        this.lastFormElement = checkbox.closest("form");
+    }
+    async choose(label) {
+        const radio = await this.container.findByRole("radio", { name: label });
+        await this.user.click(radio);
+        this.lastFormElement = radio.closest("form");
+    }
+    async submit() {
+        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"]');
+        if (submitBtn) {
+            await this.user.click(submitBtn);
+        }
+        else {
+            this.lastFormElement.requestSubmit();
+        }
+    }
+    async assertHas(_selector, _opts) {
+        throw new Error("assertHas() with CSS selectors is not recommended in RTL. Use assertText() instead.");
+    }
+    async refuteHas(_selector, _opts) {
+        throw new Error("refuteHas() with CSS selectors is not recommended in RTL. Use refuteText() instead.");
+    }
+    async assertText(text) {
+        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.`);
+        }
+    }
+    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 within(selector) {
+        const root = this.container === screen
+            ? document.body
+            : (this.container
+                .container ?? document.body);
+        const element = root.querySelector(selector);
+        if (!element)
+            throw new Error(`within('${selector}'): element not found`);
+        return new RTLDriver(this.user, element);
+    }
+    async debug() {
+        screen.debug();
+    }
+}

package/dist/rtl/index.d.ts

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

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

@@ -0,0 +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"}

package/dist/rtl/index.js

@@ -0,0 +1,8 @@
+import { Session } from "../session.js";
+import { RTLDriver } from "./driver.js";
+export { Session } from "../session.js";
+export { StepError } from "../errors.js";
+export { RTLDriver } from "./driver.js";
+export function createSession() {
+    return new Session(new RTLDriver());
+}

package/dist/session.d.ts

@@ -0,0 +1,29 @@
+import type { AssertHasOptions, AssertPathOptions, TestDriver } from "./types.js";
+export declare class Session implements PromiseLike<void> {
+    private driver;
+    private steps;
+    private stepIndex;
+    constructor(driver: TestDriver);
+    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;
+    visit(path: string): this;
+    click(text: string): this;
+    clickLink(text: string): this;
+    clickButton(text: string): this;
+    fillIn(label: string, value: string): this;
+    selectOption(label: string, option: string): this;
+    check(label: string): this;
+    uncheck(label: string): this;
+    choose(label: string): this;
+    submit(): this;
+    assertText(text: string): this;
+    refuteText(text: 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;
+    debug(): this;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +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"}

package/dist/session.js

@@ -0,0 +1,97 @@
+import { StepError } from "./errors.js";
+export class Session {
+    driver;
+    steps = [];
+    stepIndex = 0;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    then(onfulfilled, onrejected) {
+        return this.executeSteps().then(onfulfilled, onrejected);
+    }
+    async executeSteps() {
+        const steps = [...this.steps];
+        this.steps = [];
+        for (const step of steps) {
+            try {
+                await step.action();
+            }
+            catch (error) {
+                throw new StepError(step, steps, error);
+            }
+        }
+    }
+    enqueue(name, action) {
+        this.steps.push({ name, action, index: this.stepIndex++ });
+        return this;
+    }
+    // --- Navigation ---
+    visit(path) {
+        return this.enqueue(`visit('${path}')`, () => this.driver.visit(path));
+    }
+    // --- Interactions ---
+    click(text) {
+        return this.enqueue(`click('${text}')`, () => this.driver.click(text));
+    }
+    clickLink(text) {
+        return this.enqueue(`clickLink('${text}')`, () => this.driver.clickLink(text));
+    }
+    clickButton(text) {
+        return this.enqueue(`clickButton('${text}')`, () => this.driver.clickButton(text));
+    }
+    fillIn(label, value) {
+        return this.enqueue(`fillIn('${label}', '${value}')`, () => this.driver.fillIn(label, value));
+    }
+    selectOption(label, option) {
+        return this.enqueue(`selectOption('${label}', '${option}')`, () => this.driver.selectOption(label, option));
+    }
+    check(label) {
+        return this.enqueue(`check('${label}')`, () => this.driver.check(label));
+    }
+    uncheck(label) {
+        return this.enqueue(`uncheck('${label}')`, () => this.driver.uncheck(label));
+    }
+    choose(label) {
+        return this.enqueue(`choose('${label}')`, () => this.driver.choose(label));
+    }
+    submit() {
+        return this.enqueue("submit()", () => this.driver.submit());
+    }
+    // --- Assertions ---
+    assertText(text) {
+        return this.enqueue(`assertText('${text}')`, () => this.driver.assertText(text));
+    }
+    refuteText(text) {
+        return this.enqueue(`refuteText('${text}')`, () => this.driver.refuteText(text));
+    }
+    assertHas(selector, opts) {
+        const desc = opts?.text
+            ? `assertHas('${selector}', text: '${opts.text}')`
+            : `assertHas('${selector}')`;
+        return this.enqueue(desc, () => this.driver.assertHas(selector, opts));
+    }
+    refuteHas(selector, opts) {
+        const desc = opts?.text
+            ? `refuteHas('${selector}', text: '${opts.text}')`
+            : `refuteHas('${selector}')`;
+        return this.enqueue(desc, () => this.driver.refuteHas(selector, opts));
+    }
+    assertPath(path, opts) {
+        return this.enqueue(`assertPath('${path}')`, () => this.driver.assertPath(path, opts));
+    }
+    refutePath(path) {
+        return this.enqueue(`refutePath('${path}')`, () => this.driver.refutePath(path));
+    }
+    // --- Scoping ---
+    within(selector, fn) {
+        return this.enqueue(`within('${selector}')`, async () => {
+            const scopedDriver = await this.driver.within(selector);
+            const scopedSession = new Session(scopedDriver);
+            await fn(scopedSession);
+        });
+    }
+    // --- Debug ---
+    debug() {
+        return this.enqueue("debug()", () => this.driver.debug());
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export interface AssertHasOptions {
+    text?: string;
+    count?: number;
+    exact?: boolean;
+    timeout?: number;
+}
+export interface AssertPathOptions {
+    queryParams?: Record<string, string>;
+}
+export interface QueuedStep {
+    name: string;
+    action: () => Promise<void>;
+    index: number;
+}
+export interface TestDriver {
+    visit(path: string): Promise<void>;
+    click(text: string): Promise<void>;
+    clickLink(text: string): Promise<void>;
+    clickButton(text: string): Promise<void>;
+    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>;
+    assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
+    refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
+    assertText(text: string): Promise<void>;
+    refuteText(text: string): Promise<void>;
+    assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
+    refutePath(path: string): Promise<void>;
+    within(selector: string): Promise<TestDriver>;
+    debug(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "feather-testing-core",
+  "version": "0.1.0",
+  "description": "Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library",
+  "license": "MIT",
+  "keywords": [
+    "testing",
+    "playwright",
+    "react-testing-library",
+    "fluent",
+    "dsl",
+    "e2e",
+    "integration"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright/index.js",
+      "default": "./dist/playwright/index.js"
+    },
+    "./rtl": {
+      "types": "./dist/rtl/index.d.ts",
+      "import": "./dist/rtl/index.js",
+      "default": "./dist/rtl/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0",
+    "@testing-library/react": ">=14.0.0",
+    "@testing-library/user-event": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
+    "@testing-library/user-event": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.0",
+    "typescript": "~5.9.3"
+  }
+}