feather-testing-core 0.3.0 → 0.4.0

package/dist/session.js

@@ -1,4 +1,19 @@
 import { StepError } from "./errors.js";
+/**
+ * Verbs that take a human description exist so a failure names intent rather
+ * than mechanics. An empty description defeats that, so it is rejected where
+ * the mistake is — at the call site, before the chain runs.
+ */
+function requireDescription(verb, value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`feather-testing-core: ${verb}() requires a non-empty description as its ` +
+            "first argument — it is what the chain trace prints when the step fails.");
+    }
+}
+/** How a string-or-regex expectation reads in the chain trace. */
+function describe(expected) {
+    return typeof expected === "string" ? expected : String(expected);
+}
 export class Session {
     driver;
     steps = [];
@@ -62,12 +77,27 @@ export class Session {
     submit() {
         return this.enqueue("submit()", () => this.driver.submit());
     }
+    /** Set a file input, found by its label, to the file at `path`. */
+    attachFile(label, path) {
+        return this.enqueue(`attachFile('${label}', '${path}')`, () => this.driver.attachFile(label, path));
+    }
+    /** @deprecated Older name for {@link Session.attachFile}. */
     upload(label, path) {
-        return this.enqueue(`upload('${label}', '${path}')`, () => this.driver.upload(label, path));
+        return this.enqueue(`upload('${label}', '${path}')`, () => this.driver.upload
+            ? this.driver.upload(label, path)
+            : this.driver.attachFile(label, path));
     }
     dropFile(selector, path) {
         return this.enqueue(`dropFile('${selector}', '${path}')`, () => this.driver.dropFile(selector, path));
     }
+    /** Press a key on the focused element, e.g. 'Enter' or 'Control+A'. */
+    pressKey(key) {
+        return this.enqueue(`pressKey('${key}')`, () => this.driver.pressKey(key));
+    }
+    /** Hover the element with this text. */
+    hover(text) {
+        return this.enqueue(`hover('${text}')`, () => this.driver.hover(text));
+    }
     // --- Assertions ---
     assertText(text) {
         return this.enqueue(`assertText('${text}')`, () => this.driver.assertText(text));
@@ -109,6 +139,32 @@ export class Session {
     refutePath(path) {
         return this.enqueue(`refutePath('${path}')`, () => this.driver.refutePath(path));
     }
+    /**
+     * Assert that running `trigger` makes the browser offer a download whose
+     * suggested filename matches `expected`. The trigger is a callback because
+     * the wait has to be armed before the click that starts the download.
+     *
+     * Browser-only: the RTL adapter throws a BrowserOnlyVerbError.
+     */
+    assertDownload(expected, trigger, opts) {
+        return this.enqueue(`assertDownload('${describe(expected)}')`, () => this.driver.assertDownload(expected, async () => {
+            await trigger(new Session(this.driver));
+        }, opts));
+    }
+    // --- Waiting ---
+    /**
+     * Wait for a condition instead of sleeping. `description` is mandatory: it
+     * is what the chain trace prints, so a timeout reads
+     * `[FAILED] until: the export finishes` rather than naming a mechanism.
+     *
+     * The predicate receives the adapter's context ({ page, scope } for
+     * Playwright, { user, container } for RTL) and may be sync or async; it
+     * is polled until it returns something truthy or the budget is spent.
+     */
+    until(description, predicate, opts) {
+        requireDescription("until", description);
+        return this.enqueue(`until: ${description}`, () => this.driver.until(description, predicate, opts));
+    }
     // --- Escape hatch ---
     /**
      * Queue a named custom step. `fn` receives the adapter's context
@@ -119,6 +175,16 @@ export class Session {
     step(name, fn) {
         return this.enqueue(`step('${name}')`, () => this.driver.step(fn));
     }
+    /**
+     * Drop to the driver itself — Playwright's `page`, RTL's scoped queries —
+     * without leaving the chain. `label` is mandatory and registers as a named
+     * step, so an escape hatch still names intent in the trace instead of
+     * ending it: `[FAILED] raw('drag the card to Done')`.
+     */
+    raw(label, fn) {
+        requireDescription("raw", label);
+        return this.enqueue(`raw('${label}')`, () => this.driver.raw(fn));
+    }
     // --- Scoping ---
     /**
      * `fn` must either return the scoped session — so its queued steps run — or

package/dist/types.d.ts

@@ -7,16 +7,31 @@ export interface AssertHasOptions {
 export interface AssertPathOptions {
     queryParams?: Record<string, string>;
 }
+export interface UntilOptions {
+    /** Overall budget in ms. Defaults to the adapter's own wait timeout. */
+    timeout?: number;
+    /** Gap between polls in ms. Defaults to the adapter's own cadence. */
+    interval?: number;
+}
+export interface DownloadOptions {
+    /** How long to wait for the download to start, in ms. */
+    timeout?: number;
+}
 export interface QueuedStep {
     name: string;
     action: () => Promise<void>;
     index: number;
 }
+/** A condition polled by `until()`; may be sync or async. */
+export type UntilPredicate<TContext> = (context: TContext) => unknown | Promise<unknown>;
 /**
  * TContext is the adapter-specific context handed to custom step() callbacks
  * (e.g. { page, scope } for Playwright, { user, container } for RTL).
+ *
+ * TNative is the adapter's own driving handle, handed to raw() callbacks:
+ * Playwright's `Page`, RTL's scoped query object.
  */
-export interface TestDriver<TContext = unknown> {
+export interface TestDriver<TContext = unknown, TNative = unknown> {
     visit(path: string): Promise<void>;
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
@@ -27,8 +42,12 @@ export interface TestDriver<TContext = unknown> {
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
-    upload(label: string, path: string): Promise<void>;
+    attachFile(label: string, path: string): Promise<void>;
+    /** @deprecated The older name for {@link TestDriver.attachFile}. */
+    upload?(label: string, path: string): Promise<void>;
     dropFile(selector: string, path: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    hover(text: string): Promise<void>;
     assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     assertText(text: string): Promise<void>;
@@ -40,8 +59,21 @@ export interface TestDriver<TContext = unknown> {
     assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
     refutePath(path: string): Promise<void>;
+    /**
+     * Run `trigger` and assert the browser offers a download whose suggested
+     * filename matches `expected`. Browser-only: the RTL adapter throws.
+     */
+    assertDownload(expected: string | RegExp, trigger: () => Promise<void>, opts?: DownloadOptions): Promise<void>;
+    /**
+     * Poll `predicate` until it returns something truthy, or fail once the
+     * timeout is spent. `description` is what the chain trace prints, so it
+     * has to say what is being awaited in plain language.
+     */
+    until(description: string, predicate: UntilPredicate<TContext>, opts?: UntilOptions): Promise<void>;
     step(fn: (context: TContext) => Promise<unknown>): Promise<void>;
-    within(selector: string): Promise<TestDriver<TContext>>;
+    /** Hand the caller the adapter's own driving handle, untyped by the DSL. */
+    raw(fn: (native: TNative) => unknown | Promise<unknown>): Promise<void>;
+    within(selector: string): Promise<TestDriver<TContext, TNative>>;
     debug(): Promise<void>;
     /**
      * Optional hook: wrap a queued step's execution (e.g. in Playwright's

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feather-testing-core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,11 @@
       "types": "./dist/rtl/index.d.ts",
       "import": "./dist/rtl/index.js",
       "default": "./dist/rtl/index.js"
+    },
+    "./eslint-plugin": {
+      "types": "./dist/eslint-plugin/index.d.ts",
+      "import": "./dist/eslint-plugin/index.js",
+      "default": "./dist/eslint-plugin/index.js"
     }
   },
   "files": [
@@ -57,7 +62,8 @@
     "build": "tsc",
     "test": "vitest run",
     "test:pw": "playwright test",
-    "test:all": "vitest run && playwright test"
+    "test:all": "vitest run && playwright test",
+    "lint": "npm run build && eslint ."
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",
@@ -67,6 +73,8 @@
     "@types/node": "^26.1.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/parser": "^8.68.0",
+    "eslint": "^9.39.5",
     "jsdom": "^28.1.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",