feather-testing-core 0.2.0 → 0.3.0

package/README.md

@@ -172,6 +172,20 @@ Every method returns `this` for chaining. A single `await` at the start of the c
 | `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 |
 
+#### Interactions address controls **exactly**
+
+Every interaction above names the control it wants, and that name is matched in full: `clickButton("Check")` clicks the button named *Check*, never the sidebar chip named *"Checklist Run — checklist"*. Whitespace is still normalized, so multi-line markup and padded labels keep working.
+
+This matters because Playwright's bare-string matchers are case-insensitive *substring* matchers. Left as-is, a verb aimed at one control silently widens to any other control whose name merely contains the same text — and the run dies on a strict-mode violation that only appears when both are on screen at once, which turns a naming collision into an ordering-dependent flake. RTL matches whole strings by default, so with this both adapters answer the same question.
+
+Assertions are the deliberate exception: `assertText` / `refuteText` / `assertHas` ask *"does this text appear"*, so they stay substring matches. An exact `refuteText("Check")` would pass while *Checklist Run* is plainly on the page.
+
+To act on a control whose name is genuinely a prefix of another's, scope the lookup rather than loosening it:
+
+```ts
+await session.within("main", (s) => s.clickButton("Check"));
+```
+
 #### 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:
@@ -392,6 +406,36 @@ The RTL adapter runs in JSDOM, which has no real browser. These methods are not
 - `assertPath()` / `refutePath()` — no URL in JSDOM
 - `assertHas()` / `refuteHas()` — RTL discourages CSS selectors; use `assertText()` instead
 
+### Extending the RTL adapter
+
+`RTLDriver` is meant to be subclassed when an app's markup needs a different lookup, so that a host harness binds *this* DSL rather than reimplementing it. Everything worth specializing is `protected`:
+
+| Member | Why you'd override it |
+|--------|----------------------|
+| `findField(label)` | The single label-addressed lookup. Every labelled verb — `fillIn`, `selectOption`, `check`, `uncheck`, `upload`, `assertValue`, `assertChecked`, `assertSelected`, `assertOptions` — goes through it, so one override retargets them all |
+| `scoped(element)` | Factory used by `within()`, so a scoped session keeps your driver's behaviour |
+| `user`, `root`, `container`, `lastFormElement`, `timeout` | Shared state the built-in verbs read and write |
+
+```ts
+class WrapperLabelDriver extends RTLDriver {
+  // Labels with no htmlFor, control is a sibling inside a wrapper div
+  protected override async findField(label: string): Promise<HTMLElement> {
+    for (const l of this.rootElement().querySelectorAll("label")) {
+      if (l.textContent?.trim() !== label) continue;
+      const control = l.parentElement?.querySelector("input, textarea, select");
+      if (control) return control as HTMLElement;
+    }
+    throw new Error(`no field labelled '${label}'`);
+  }
+
+  protected override scoped(element: HTMLElement) {
+    return new WrapperLabelDriver(this.user, element, this.timeout);
+  }
+}
+```
+
+The third constructor argument is a per-lookup timeout in ms; omit it to keep RTL's own default.
+
 ## Exports
 
 ```ts

package/dist/playwright/driver.d.ts

@@ -15,6 +15,8 @@ export declare class PlaywrightDriver implements TestDriver<PlaywrightStepContex
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;
     clickButton(text: string): Promise<void>;
+    /** The single label-addressed lookup: every labelled verb goes through it. */
+    private labelled;
     private fieldByLabelOrPlaceholder;
     fillIn(label: string, value: string): Promise<void>;
     selectOption(label: string, option: string): 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":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/playwright/driver.ts"],"names":[],"mappings":"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"}

package/dist/playwright/driver.js

@@ -1,6 +1,21 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { expect, test } from "@playwright/test";
+/**
+ * Playwright matches a bare string name/label/text as a case-insensitive
+ * SUBSTRING. That makes every text-addressed verb ambient: `clickButton('Check')`
+ * also matches an unrelated "Checklist Run — checklist" control that happens to
+ * be on the page, and the run dies on a strict-mode violation whose appearance
+ * depends on what else rendered. When a spec names a control it means *that*
+ * control, so every addressing matcher here passes `exact: true`. Playwright
+ * still normalizes whitespace under exact matching, so multi-line markup and
+ * padded labels keep working.
+ *
+ * Assertions (assertText/refuteText/assertHas) deliberately stay substring:
+ * they ask "does this text appear", and an exact `refuteText` would pass while
+ * the text is plainly on the page inside a longer string.
+ */
+const EXACT = { exact: true };
 export class PlaywrightDriver {
     page;
     scope;
@@ -13,23 +28,25 @@ export class PlaywrightDriver {
         await this.page.goto(path);
     }
     async click(text) {
-        await this.scope.getByText(text).click();
+        await this.scope.getByText(text, EXACT).click();
     }
     async clickLink(text) {
-        await this.scope.getByRole("link", { name: text }).click();
+        await this.scope.getByRole("link", { name: text, ...EXACT }).click();
     }
     async clickButton(text) {
-        await this.scope.getByRole("button", { name: text }).click();
+        await this.scope.getByRole("button", { name: text, ...EXACT }).click();
+    }
+    /** The single label-addressed lookup: every labelled verb goes through it. */
+    labelled(label) {
+        return this.scope.getByLabel(label, EXACT);
     }
     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
+        // placeholder branch. Both branches match exactly — 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 }));
+        return this.labelled(label).or(this.scope.getByPlaceholder(label, EXACT));
     }
     async fillIn(label, value) {
         const field = this.fieldByLabelOrPlaceholder(label);
@@ -37,22 +54,22 @@ export class PlaywrightDriver {
         this.lastFormLocator = this.scope.locator("form", { has: field });
     }
     async selectOption(label, option) {
-        const select = this.scope.getByLabel(label);
+        const select = this.labelled(label);
         await select.selectOption({ label: option });
         this.lastFormLocator = this.scope.locator("form", { has: select });
     }
     async check(label) {
-        const checkbox = this.scope.getByLabel(label);
+        const checkbox = this.labelled(label);
         await checkbox.check();
         this.lastFormLocator = this.scope.locator("form", { has: checkbox });
     }
     async uncheck(label) {
-        const checkbox = this.scope.getByLabel(label);
+        const checkbox = this.labelled(label);
         await checkbox.uncheck();
         this.lastFormLocator = this.scope.locator("form", { has: checkbox });
     }
     async choose(label) {
-        const radio = this.scope.getByRole("radio", { name: label });
+        const radio = this.scope.getByRole("radio", { name: label, ...EXACT });
         await radio.check();
         this.lastFormLocator = this.scope.locator("form", { has: radio });
     }
@@ -83,7 +100,7 @@ export class PlaywrightDriver {
         }
     }
     async upload(label, path) {
-        const input = this.scope.getByLabel(label);
+        const input = this.labelled(label);
         await input.setInputFiles(path);
         this.lastFormLocator = this.scope.locator("form", { has: input });
     }
@@ -133,17 +150,17 @@ export class PlaywrightDriver {
         await expect(this.fieldByLabelOrPlaceholder(label)).toHaveValue(value);
     }
     async assertChecked(label) {
-        await expect(this.scope.getByLabel(label)).toBeChecked();
+        await expect(this.labelled(label)).toBeChecked();
     }
     async refuteChecked(label) {
-        await expect(this.scope.getByLabel(label)).not.toBeChecked();
+        await expect(this.labelled(label)).not.toBeChecked();
     }
     async assertSelected(label, optionLabel) {
-        const select = this.scope.getByLabel(label);
+        const select = this.labelled(label);
         await expect(select.locator("option:checked")).toHaveText(optionLabel);
     }
     async assertOptions(label, optionLabels) {
-        const select = this.scope.getByLabel(label);
+        const select = this.labelled(label);
         await expect(select.locator("option")).toHaveText(optionLabels);
     }
     async assertPath(path, opts) {

package/dist/rtl/driver.d.ts

@@ -10,14 +10,36 @@ export interface RTLStepContext {
 /**
  * RTL adapter implementing the subset of TestDriver that applies in JSDOM.
  * Navigation methods (visit, assertPath, refutePath) are not supported.
+ *
+ * Everything a host adapter is likely to specialize is `protected`: the
+ * label-to-control lookup (`findField`), the scoped-driver factory
+ * (`scoped`), and the `user` / `root` / `lastFormElement` state the verbs
+ * share. Subclass it rather than reimplementing the DSL when an app's markup
+ * needs a different lookup — that is how feather-testing-postgres binds this
+ * driver to markup whose labels are wrapper siblings rather than `htmlFor`
+ * targets.
  */
 export declare class RTLDriver implements TestDriver<RTLStepContext> {
-    private user;
-    private container;
-    private lastFormElement;
-    constructor(user?: UserEvent, container?: HTMLElement);
-    private rootElement;
-    private findFieldByLabelOrPlaceholder;
+    protected user: UserEvent;
+    /** The element every query and selector in this driver resolves against. */
+    protected root: HTMLElement;
+    protected container: ReturnType<typeof rtlWithin>;
+    protected lastFormElement: HTMLFormElement | null;
+    /** Per-lookup timeout in ms; undefined leaves RTL's own default in place. */
+    protected timeout: number | undefined;
+    constructor(user?: UserEvent, container?: HTMLElement, timeout?: number);
+    protected rootElement(): HTMLElement;
+    /** Options forwarded to every async query and waitFor call. */
+    protected waitOpts(): {
+        timeout?: number;
+    };
+    /**
+     * The single label-addressed lookup: every labelled verb goes through it,
+     * so overriding this one method retargets them all.
+     */
+    protected findField(label: string): Promise<HTMLElement>;
+    /** Subclasses override this so within() yields a driver of their own type. */
+    protected scoped(element: HTMLElement): TestDriver<RTLStepContext>;
     visit(): Promise<void>;
     click(text: string): Promise<void>;
     clickLink(text: string): Promise<void>;

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

@@ -3,52 +3,76 @@ 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.
+ *
+ * Everything a host adapter is likely to specialize is `protected`: the
+ * label-to-control lookup (`findField`), the scoped-driver factory
+ * (`scoped`), and the `user` / `root` / `lastFormElement` state the verbs
+ * share. Subclass it rather than reimplementing the DSL when an app's markup
+ * needs a different lookup — that is how feather-testing-postgres binds this
+ * driver to markup whose labels are wrapper siblings rather than `htmlFor`
+ * targets.
  */
 export class RTLDriver {
     user;
+    /** The element every query and selector in this driver resolves against. */
+    root;
     container;
     lastFormElement = null;
-    constructor(user, container) {
+    /** Per-lookup timeout in ms; undefined leaves RTL's own default in place. */
+    timeout;
+    constructor(user, container, timeout) {
         this.user = user ?? userEvent.setup();
-        this.container = container ? rtlWithin(container) : screen;
+        this.root = container ?? document.body;
+        this.container = rtlWithin(this.root);
+        this.timeout = timeout;
     }
     rootElement() {
-        return this.container === screen
-            ? document.body
-            : (this.container
-                .container ?? document.body);
+        return this.root;
     }
-    async findFieldByLabelOrPlaceholder(label) {
+    /** Options forwarded to every async query and waitFor call. */
+    waitOpts() {
+        return this.timeout === undefined ? {} : { timeout: this.timeout };
+    }
+    /**
+     * The single label-addressed lookup: every labelled verb goes through it,
+     * so overriding this one method retargets them all.
+     */
+    async findField(label) {
         try {
-            return await this.container.findByLabelText(label);
+            return await this.container.findByLabelText(label, undefined, this.waitOpts());
         }
         catch {
-            return await this.container.findByPlaceholderText(label);
+            return await this.container.findByPlaceholderText(label, undefined, this.waitOpts());
         }
     }
+    /** Subclasses override this so within() yields a driver of their own type. */
+    scoped(element) {
+        return new RTLDriver(this.user, element, this.timeout);
+    }
     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);
+        const element = await this.container.findByText(text, undefined, this.waitOpts());
         await this.user.click(element);
     }
     async clickLink(text) {
-        const link = await this.container.findByRole("link", { name: text });
+        const link = await this.container.findByRole("link", { name: text }, this.waitOpts());
         await this.user.click(link);
     }
     async clickButton(text) {
-        const button = await this.container.findByRole("button", { name: text });
+        const button = await this.container.findByRole("button", { name: text }, this.waitOpts());
         await this.user.click(button);
     }
     async fillIn(label, value) {
-        const input = await this.findFieldByLabelOrPlaceholder(label);
+        const input = await this.findField(label);
         await this.user.clear(input);
-        await this.user.type(input, value);
+        if (value)
+            await this.user.type(input, value);
         this.lastFormElement = input.closest("form");
     }
     async selectOption(label, option) {
-        const select = await this.container.findByLabelText(label);
+        const select = await this.findField(label);
         const optionEl = Array.from(select.querySelectorAll("option")).find((o) => o.textContent?.trim() === option);
         if (!optionEl) {
             throw new Error(`selectOption('${label}', '${option}'): no <option> with text '${option}' found.`);
@@ -57,21 +81,21 @@ export class RTLDriver {
         this.lastFormElement = select.closest("form");
     }
     async check(label) {
-        const checkbox = await this.container.findByLabelText(label);
+        const checkbox = await this.findField(label);
         if (!checkbox.checked) {
             await this.user.click(checkbox);
         }
         this.lastFormElement = checkbox.closest("form");
     }
     async uncheck(label) {
-        const checkbox = await this.container.findByLabelText(label);
+        const checkbox = await this.findField(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 });
+        const radio = await this.container.findByRole("radio", { name: label }, this.waitOpts());
         await this.user.click(radio);
         this.lastFormElement = radio.closest("form");
     }
@@ -93,7 +117,7 @@ export class RTLDriver {
         }
     }
     async upload(label, path) {
-        const input = await this.container.findByLabelText(label);
+        const input = await this.findField(label);
         // JSDOM has no filesystem access; synthesize a File from the basename.
         const name = path.split(/[\\/]/).pop() ?? path;
         const file = new File([""], name);
@@ -122,7 +146,7 @@ export class RTLDriver {
         throw new Error("refuteHas() with CSS selectors is not recommended in RTL. Use refuteText() instead.");
     }
     async assertText(text) {
-        await this.container.findByText(text);
+        await this.container.findByText(text, undefined, this.waitOpts());
     }
     async refuteText(text) {
         await waitFor(() => {
@@ -130,44 +154,44 @@ export class RTLDriver {
             if (el) {
                 throw new Error(`Expected NOT to find text '${text}', but it was present.`);
             }
-        });
+        }, this.waitOpts());
     }
     async assertValue(label, value) {
-        const field = await this.findFieldByLabelOrPlaceholder(label);
+        const field = await this.findField(label);
         await waitFor(() => {
             const actual = field.value;
             if (actual !== value) {
                 throw new Error(`assertValue('${label}', '${value}'): expected value '${value}', but found '${actual}'.`);
             }
-        });
+        }, this.waitOpts());
     }
     async assertChecked(label) {
-        const checkbox = await this.container.findByLabelText(label);
+        const checkbox = await this.findField(label);
         await waitFor(() => {
             if (!checkbox.checked) {
                 throw new Error(`assertChecked('${label}'): expected checkbox to be checked, but it was not.`);
             }
-        });
+        }, this.waitOpts());
     }
     async refuteChecked(label) {
-        const checkbox = await this.container.findByLabelText(label);
+        const checkbox = await this.findField(label);
         await waitFor(() => {
             if (checkbox.checked) {
                 throw new Error(`refuteChecked('${label}'): expected checkbox NOT to be checked, but it was.`);
             }
-        });
+        }, this.waitOpts());
     }
     async assertSelected(label, optionLabel) {
-        const select = (await this.container.findByLabelText(label));
+        const select = (await this.findField(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)"}'.`);
             }
-        });
+        }, this.waitOpts());
     }
     async assertOptions(label, optionLabels) {
-        const select = (await this.container.findByLabelText(label));
+        const select = (await this.findField(label));
         await waitFor(() => {
             const actual = Array.from(select.querySelectorAll("option")).map((o) => o.textContent?.trim() ?? "");
             const matches = actual.length === optionLabels.length &&
@@ -175,7 +199,7 @@ export class RTLDriver {
             if (!matches) {
                 throw new Error(`assertOptions('${label}'): expected options [${optionLabels.join(", ")}], but found [${actual.join(", ")}].`);
             }
-        });
+        }, this.waitOpts());
     }
     async assertPath() {
         throw new Error("assertPath() is not available in the RTL adapter (no real URL in JSDOM).");
@@ -190,9 +214,9 @@ export class RTLDriver {
         const element = this.rootElement().querySelector(selector);
         if (!element)
             throw new Error(`within('${selector}'): element not found`);
-        return new RTLDriver(this.user, element);
+        return this.scoped(element);
     }
     async debug() {
-        screen.debug();
+        screen.debug(this.rootElement());
     }
 }

package/dist/session.d.ts

@@ -38,7 +38,12 @@ 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;
-    within(selector: string, fn: (scoped: Session<TContext>) => Session<TContext>): 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;
     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,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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -120,6 +120,11 @@ export class Session {
         return this.enqueue(`step('${name}')`, () => this.driver.step(fn));
     }
     // --- Scoping ---
+    /**
+     * `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, fn) {
         return this.enqueue(`within('${selector}')`, async () => {
             const scopedDriver = await this.driver.within(selector);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feather-testing-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Phoenix Test-inspired fluent testing DSL for Playwright and React Testing Library",
   "license": "MIT",
   "repository": {