feather-testing-core 0.3.0 → 0.4.0

package/dist/eslint-plugin/rules/warn-serial-mode.js

@@ -0,0 +1,59 @@
+function memberPath(node) {
+    if (node.type === "Identifier")
+        return node.name;
+    if (node.type === "MemberExpression" &&
+        !node.computed &&
+        node.property.type === "Identifier") {
+        const prefix = memberPath(node.object);
+        return prefix === null ? null : `${prefix}.${node.property.name}`;
+    }
+    return null;
+}
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Flag serial mode, which makes each test depend on the ones before it",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            serial: "Serial mode couples these tests: one failure cascades into the rest, " +
+                "so the report stops naming the real cause and a flake becomes a wall " +
+                "of red. Make them independent — share setup, not state — or keep " +
+                "serial with an eslint-disable-next-line comment saying why it is " +
+                "required.",
+        },
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const path = memberPath(node.callee);
+                if (path === null)
+                    return;
+                const segments = path.split(".");
+                const isSerialRunner = segments.includes("serial") &&
+                    ["test", "it", "describe", "suite"].includes(segments[0] ?? "");
+                if (isSerialRunner) {
+                    context.report({ node, messageId: "serial" });
+                    return;
+                }
+                // test.describe.configure({ mode: "serial" })
+                if (!path.endsWith(".configure"))
+                    return;
+                const [options] = node.arguments;
+                if (!options || options.type !== "ObjectExpression")
+                    return;
+                const declaresSerial = options.properties.some((property) => property.type === "Property" &&
+                    !property.computed &&
+                    property.key.type === "Identifier" &&
+                    property.key.name === "mode" &&
+                    property.value.type === "Literal" &&
+                    property.value.value === "serial");
+                if (declaresSerial)
+                    context.report({ node, messageId: "serial" });
+            },
+        };
+    },
+};
+export default rule;

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

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

package/dist/playwright/driver.d.ts

@@ -1,12 +1,12 @@
 import { type Page, type Locator } from "@playwright/test";
-import type { AssertHasOptions, AssertPathOptions, TestDriver } from "../types.js";
+import type { AssertHasOptions, AssertPathOptions, DownloadOptions, TestDriver, UntilOptions, UntilPredicate } from "../types.js";
 /** 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> {
+export declare class PlaywrightDriver implements TestDriver<PlaywrightStepContext, Page> {
     private page;
     private scope;
     private lastFormLocator;
@@ -24,7 +24,11 @@ export declare class PlaywrightDriver implements TestDriver<PlaywrightStepContex
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
+    attachFile(label: string, path: string): Promise<void>;
+    /** @deprecated Older name for {@link PlaywrightDriver.attachFile}. */
     upload(label: string, path: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    hover(text: string): Promise<void>;
     dropFile(selector: string, path: string): Promise<void>;
     assertHas(selector: string, opts?: AssertHasOptions): Promise<void>;
     refuteHas(selector: string, opts?: AssertHasOptions): Promise<void>;
@@ -37,8 +41,17 @@ export declare class PlaywrightDriver implements TestDriver<PlaywrightStepContex
     assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(path: string, opts?: AssertPathOptions): Promise<void>;
     refutePath(path: string): Promise<void>;
+    assertDownload(expected: string | RegExp, trigger: () => Promise<void>, opts?: DownloadOptions): Promise<void>;
+    until(description: string, predicate: UntilPredicate<PlaywrightStepContext>, opts?: UntilOptions): Promise<void>;
     step(fn: (context: PlaywrightStepContext) => Promise<unknown>): Promise<void>;
-    within(selector: string): Promise<TestDriver<PlaywrightStepContext>>;
+    /**
+     * raw() hands over the page itself, not the within() scope: it exists for
+     * the cases the DSL does not model, where re-scoping is the caller's job.
+     */
+    raw(fn: (page: Page) => unknown | Promise<unknown>): Promise<void>;
+    /** The adapter context handed to step(), until(), and friends. */
+    protected context(): PlaywrightStepContext;
+    within(selector: string): Promise<TestDriver<PlaywrightStepContext, Page>>;
     debug(): Promise<void>;
     wrapStep(name: string, fn: () => Promise<void>): Promise<void>;
 }

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

@@ -1 +1 @@
-{"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;AAkBD,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,8EAA8E;IAC9E,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,yBAAyB;IAS3B,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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/playwright/driver.ts"],"names":[],"mappings":"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"}

package/dist/playwright/driver.js

@@ -99,11 +99,21 @@ export class PlaywrightDriver {
                 .press("Enter");
         }
     }
-    async upload(label, path) {
+    async attachFile(label, path) {
         const input = this.labelled(label);
         await input.setInputFiles(path);
         this.lastFormLocator = this.scope.locator("form", { has: input });
     }
+    /** @deprecated Older name for {@link PlaywrightDriver.attachFile}. */
+    async upload(label, path) {
+        await this.attachFile(label, path);
+    }
+    async pressKey(key) {
+        await this.page.keyboard.press(key);
+    }
+    async hover(text) {
+        await this.scope.getByText(text, EXACT).hover();
+    }
     async dropFile(selector, path) {
         const content = await readFile(path);
         const name = basename(path);
@@ -183,8 +193,45 @@ export class PlaywrightDriver {
         })
             .not.toBe(path);
     }
+    async assertDownload(expected, trigger, opts) {
+        // The wait has to be armed before the click that starts the download,
+        // which is why the trigger arrives as a callback rather than as an
+        // earlier step in the chain.
+        const [download] = await Promise.all([
+            this.page.waitForEvent("download", { timeout: opts?.timeout }),
+            trigger(),
+        ]);
+        const filename = download.suggestedFilename();
+        const matched = typeof expected === "string"
+            ? filename === expected
+            : expected.test(filename);
+        if (!matched) {
+            throw new Error(`assertDownload(${typeof expected === "string" ? `'${expected}'` : String(expected)}): ` +
+                `the browser offered a download named '${filename}' instead.`);
+        }
+    }
+    async until(description, predicate, opts) {
+        await expect
+            .poll(async () => Boolean(await predicate(this.context())), {
+            message: `until: ${description}`,
+            timeout: opts?.timeout,
+            intervals: opts?.interval === undefined ? undefined : [opts.interval],
+        })
+            .toBe(true);
+    }
     async step(fn) {
-        await fn({ page: this.page, scope: this.scope });
+        await fn(this.context());
+    }
+    /**
+     * raw() hands over the page itself, not the within() scope: it exists for
+     * the cases the DSL does not model, where re-scoping is the caller's job.
+     */
+    async raw(fn) {
+        await fn(this.page);
+    }
+    /** The adapter context handed to step(), until(), and friends. */
+    context() {
+        return { page: this.page, scope: this.scope };
     }
     async within(selector) {
         const scopedLocator = this.scope.locator(selector);

package/dist/playwright/index.d.ts

@@ -2,12 +2,12 @@ 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 { StepError, BrowserOnlyVerbError } from "../errors.js";
 export { PlaywrightDriver, type PlaywrightStepContext } from "./driver.js";
-export type { AssertHasOptions, AssertPathOptions, TestDriver, } from "../types.js";
-export declare function createSession(page: Page): Session<PlaywrightStepContext>;
+export type { AssertHasOptions, AssertPathOptions, DownloadOptions, TestDriver, UntilOptions, UntilPredicate, } from "../types.js";
+export declare function createSession(page: Page): Session<PlaywrightStepContext, Page>;
 export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
-    session: Session<PlaywrightStepContext>;
+    session: Session<PlaywrightStepContext, Page>;
 }, 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;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"}
+{"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,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAEtC;AAED,eAAO,MAAM,IAAI;aACN,OAAO,CAAC,qBAAqB,EAAE,IAAI,CAAC;sGAK7C,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/playwright/index.js

@@ -2,7 +2,7 @@ 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 { StepError, BrowserOnlyVerbError } from "../errors.js";
 export { PlaywrightDriver } from "./driver.js";
 export function createSession(page) {
     return new Session(new PlaywrightDriver(page));

package/dist/rtl/driver.d.ts

@@ -1,6 +1,8 @@
 import { screen, within as rtlWithin } from "@testing-library/react";
 import { type UserEvent } from "@testing-library/user-event";
-import type { AssertHasOptions, TestDriver } from "../types.js";
+import type { AssertHasOptions, DownloadOptions, TestDriver, UntilOptions, UntilPredicate } from "../types.js";
+/** The scoped query object raw() callbacks receive in the RTL adapter. */
+export type RTLQueries = ReturnType<typeof rtlWithin>;
 /** Context handed to custom step() callbacks in the RTL adapter. */
 export interface RTLStepContext {
     user: UserEvent;
@@ -19,7 +21,7 @@ export interface RTLStepContext {
  * driver to markup whose labels are wrapper siblings rather than `htmlFor`
  * targets.
  */
-export declare class RTLDriver implements TestDriver<RTLStepContext> {
+export declare class RTLDriver implements TestDriver<RTLStepContext, RTLQueries> {
     protected user: UserEvent;
     /** The element every query and selector in this driver resolves against. */
     protected root: HTMLElement;
@@ -39,7 +41,7 @@ export declare class RTLDriver implements TestDriver<RTLStepContext> {
      */
     protected findField(label: string): Promise<HTMLElement>;
     /** Subclasses override this so within() yields a driver of their own type. */
-    protected scoped(element: HTMLElement): TestDriver<RTLStepContext>;
+    protected scoped(element: HTMLElement): TestDriver<RTLStepContext, RTLQueries>;
     visit(): Promise<void>;
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
@@ -50,7 +52,16 @@ export declare class RTLDriver implements TestDriver<RTLStepContext> {
     uncheck(label: string): Promise<void>;
     choose(label: string): Promise<void>;
     submit(): Promise<void>;
+    attachFile(label: string, path: string): Promise<void>;
+    /** @deprecated Older name for {@link RTLDriver.attachFile}. */
     upload(label: string, path: string): Promise<void>;
+    /**
+     * Keys are named the Playwright way ('Enter', 'Control+A') and translated
+     * to user-event's keyboard syntax, so one spec reads the same on both
+     * adapters.
+     */
+    pressKey(key: string): Promise<void>;
+    hover(text: string): Promise<void>;
     dropFile(selector: string, path: string): Promise<void>;
     assertHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
     refuteHas(_selector: string, _opts?: AssertHasOptions): Promise<void>;
@@ -63,8 +74,21 @@ export declare class RTLDriver implements TestDriver<RTLStepContext> {
     assertOptions(label: string, optionLabels: string[]): Promise<void>;
     assertPath(): Promise<void>;
     refutePath(): Promise<void>;
+    assertDownload(_expected: string | RegExp, _trigger: () => Promise<void>, _opts?: DownloadOptions): Promise<void>;
+    until(description: string, predicate: UntilPredicate<RTLStepContext>, opts?: UntilOptions): Promise<void>;
     step(fn: (context: RTLStepContext) => Promise<unknown>): Promise<void>;
-    within(selector: string): Promise<TestDriver<RTLStepContext>>;
+    /** raw() hands over the scoped query object — `within(root)`, i.e. screen
+     * when the driver is unscoped. */
+    raw(fn: (queries: RTLQueries) => unknown | Promise<unknown>): Promise<void>;
+    /** The adapter context handed to step(), until(), and friends. */
+    protected context(): RTLStepContext;
+    within(selector: string): Promise<TestDriver<RTLStepContext, RTLQueries>>;
     debug(): Promise<void>;
 }
+/**
+ * 'Enter' -> '{Enter}', 'a' -> 'a', 'Control+A' -> '{Control>}A{/Control}'.
+ * Printable characters are typed literally with user-event's own `{` and `[`
+ * escapes applied, so a key name never turns into a descriptor by accident.
+ */
+export declare function toKeyboardSyntax(key: string): string;
 //# 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":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/rtl/driver.ts"],"names":[],"mappings":"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"}

package/dist/rtl/driver.js

@@ -1,5 +1,6 @@
 import { fireEvent, screen, waitFor, within as rtlWithin, } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import { BrowserOnlyVerbError } from "../errors.js";
 /**
  * RTL adapter implementing the subset of TestDriver that applies in JSDOM.
  * Navigation methods (visit, assertPath, refutePath) are not supported.
@@ -116,7 +117,7 @@ export class RTLDriver {
             this.lastFormElement.requestSubmit();
         }
     }
-    async upload(label, path) {
+    async attachFile(label, path) {
         const input = await this.findField(label);
         // JSDOM has no filesystem access; synthesize a File from the basename.
         const name = path.split(/[\\/]/).pop() ?? path;
@@ -124,6 +125,22 @@ export class RTLDriver {
         await this.user.upload(input, file);
         this.lastFormElement = input.closest("form");
     }
+    /** @deprecated Older name for {@link RTLDriver.attachFile}. */
+    async upload(label, path) {
+        await this.attachFile(label, path);
+    }
+    /**
+     * Keys are named the Playwright way ('Enter', 'Control+A') and translated
+     * to user-event's keyboard syntax, so one spec reads the same on both
+     * adapters.
+     */
+    async pressKey(key) {
+        await this.user.keyboard(toKeyboardSyntax(key));
+    }
+    async hover(text) {
+        const element = await this.container.findByText(text, undefined, this.waitOpts());
+        await this.user.hover(element);
+    }
     async dropFile(selector, path) {
         const target = this.rootElement().querySelector(selector);
         if (!target) {
@@ -207,8 +224,32 @@ export class RTLDriver {
     async refutePath() {
         throw new Error("refutePath() is not available in the RTL adapter (no real URL in JSDOM).");
     }
+    async assertDownload(_expected, _trigger, _opts) {
+        throw new BrowserOnlyVerbError("assertDownload()", "Assert the request the download would make, or move this case to a " +
+            "Playwright spec where a real browser can accept the file.");
+    }
+    async until(description, predicate, opts) {
+        await waitFor(async () => {
+            if (!(await predicate(this.context()))) {
+                throw new Error(`until: ${description} — condition was still not met.`);
+            }
+        }, {
+            ...this.waitOpts(),
+            ...(opts?.timeout === undefined ? {} : { timeout: opts.timeout }),
+            ...(opts?.interval === undefined ? {} : { interval: opts.interval }),
+        });
+    }
     async step(fn) {
-        await fn({ user: this.user, container: this.container });
+        await fn(this.context());
+    }
+    /** raw() hands over the scoped query object — `within(root)`, i.e. screen
+     * when the driver is unscoped. */
+    async raw(fn) {
+        await fn(this.container);
+    }
+    /** The adapter context handed to step(), until(), and friends. */
+    context() {
+        return { user: this.user, container: this.container };
     }
     async within(selector) {
         const element = this.rootElement().querySelector(selector);
@@ -220,3 +261,38 @@ export class RTLDriver {
         screen.debug(this.rootElement());
     }
 }
+/** Playwright key names -> user-event keyboard syntax. */
+const KEY_ALIASES = {
+    Ctrl: "Control",
+    Cmd: "Meta",
+    Command: "Meta",
+    Space: " ",
+};
+const MODIFIERS = new Set(["Control", "Shift", "Alt", "Meta"]);
+/**
+ * 'Enter' -> '{Enter}', 'a' -> 'a', 'Control+A' -> '{Control>}A{/Control}'.
+ * Printable characters are typed literally with user-event's own `{` and `[`
+ * escapes applied, so a key name never turns into a descriptor by accident.
+ */
+export function toKeyboardSyntax(key) {
+    const parts = key.split("+").map((p) => KEY_ALIASES[p] ?? p);
+    const target = parts.pop();
+    if (target === undefined || target === "") {
+        throw new Error(`pressKey('${key}'): no key to press.`);
+    }
+    const held = parts.filter((p) => MODIFIERS.has(p));
+    if (held.length !== parts.length) {
+        throw new Error(`pressKey('${key}'): '${parts.find((p) => !MODIFIERS.has(p))}' is not a ` +
+            "modifier. Use Control, Shift, Alt, or Meta.");
+    }
+    const pressed = target.length === 1
+        ? target.replace(/[{[]/g, (c) => c + c)
+        : `{${target}}`;
+    return (held.map((m) => `{${m}>}`).join("") +
+        pressed +
+        held
+            .slice()
+            .reverse()
+            .map((m) => `{/${m}}`)
+            .join(""));
+}

package/dist/rtl/index.d.ts

@@ -1,7 +1,8 @@
 import { Session } from "../session.js";
-import { type RTLStepContext } from "./driver.js";
+import { type RTLQueries, type RTLStepContext } from "./driver.js";
 export { Session } from "../session.js";
-export { StepError } from "../errors.js";
-export { RTLDriver, type RTLStepContext } from "./driver.js";
-export declare function createSession(): Session<RTLStepContext>;
+export { StepError, BrowserOnlyVerbError } from "../errors.js";
+export { RTLDriver, type RTLQueries, type RTLStepContext, } from "./driver.js";
+export type { AssertHasOptions, DownloadOptions, TestDriver, UntilOptions, UntilPredicate, } from "../types.js";
+export declare function createSession(): Session<RTLStepContext, RTLQueries>;
 //# 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;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"}
+{"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,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,KAAK,UAAU,EACf,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,wBAAgB,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,UAAU,CAAC,CAEnE"}

package/dist/rtl/index.js

@@ -1,8 +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 { StepError, BrowserOnlyVerbError } from "../errors.js";
+export { RTLDriver, } from "./driver.js";
 export function createSession() {
     return new Session(new RTLDriver());
 }

package/dist/session.d.ts

@@ -1,10 +1,10 @@
-import type { AssertHasOptions, AssertPathOptions, TestDriver } from "./types.js";
-export declare class Session<TContext = unknown> implements PromiseLike<void> {
+import type { AssertHasOptions, AssertPathOptions, DownloadOptions, TestDriver, UntilOptions, UntilPredicate } from "./types.js";
+export declare class Session<TContext = unknown, TNative = unknown> implements PromiseLike<void> {
     private driver;
     private steps;
     private executedSteps;
     private stepIndex;
-    constructor(driver: TestDriver<TContext>);
+    constructor(driver: TestDriver<TContext, TNative>);
     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;
@@ -18,8 +18,15 @@ export declare class Session<TContext = unknown> implements PromiseLike<void> {
     uncheck(label: string): this;
     choose(label: string): this;
     submit(): this;
+    /** Set a file input, found by its label, to the file at `path`. */
+    attachFile(label: string, path: string): this;
+    /** @deprecated Older name for {@link Session.attachFile}. */
     upload(label: string, path: string): this;
     dropFile(selector: string, path: string): this;
+    /** Press a key on the focused element, e.g. 'Enter' or 'Control+A'. */
+    pressKey(key: string): this;
+    /** Hover the element with this text. */
+    hover(text: string): this;
     assertText(text: string): this;
     refuteText(text: string): this;
     assertValue(label: string, value: string): this;
@@ -31,6 +38,24 @@ export declare class Session<TContext = unknown> implements PromiseLike<void> {
     refuteHas(selector: string, opts?: AssertHasOptions): this;
     assertPath(path: string, opts?: AssertPathOptions): this;
     refutePath(path: string): this;
+    /**
+     * 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: string | RegExp, trigger: (scoped: Session<TContext, TNative>) => Session<TContext, TNative> | PromiseLike<unknown>, opts?: DownloadOptions): this;
+    /**
+     * 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: string, predicate: UntilPredicate<TContext>, opts?: UntilOptions): this;
     /**
      * Queue a named custom step. `fn` receives the adapter's context
      * ({ page, scope } for Playwright, { user, container } for RTL), so a
@@ -38,12 +63,19 @@ export declare class Session<TContext = unknown> implements PromiseLike<void> {
      * StepError output like any built-in step.
      */
     step(name: string, fn: (context: TContext) => Promise<unknown>): this;
+    /**
+     * 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: string, fn: (native: TNative) => unknown | Promise<unknown>): this;
     /**
      * `fn` must either return the scoped session — so its queued steps run — or
      * a promise it already awaited. Returning anything else would silently drop
      * the scoped chain, which is why the callback's return type is not `unknown`.
      */
-    within(selector: string, fn: (scoped: Session<TContext>) => Session<TContext> | PromiseLike<unknown>): this;
+    within(selector: string, fn: (scoped: Session<TContext, TNative>) => Session<TContext, TNative> | PromiseLike<unknown>): 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":"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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}