@atomic-testing/playwright 0.88.0 → 0.90.0

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import { BlurOption, BoundingRect, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, Point, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
+import { BlurOption, BoundingRect, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, ITestEngineOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, Point, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
 import { Page } from "@playwright/test";
-import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } from "@atomic-testing/internal-test-runner";
 
 //#region src/createTestEngine.d.ts
 /**
@@ -9,9 +8,12 @@ import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } f
  * @param page - Playwright page used for interaction.
  * @param partDefinitions - Scene part definitions describing the scene
  *   structure for the engine.
+ * @param _option - Reserved for entry-point symmetry with the other adapters;
+ *   currently ignored. `rootElement` is not applicable to Playwright, which drives
+ *   a real browser page rather than mounting into a host element.
  * @returns A configured {@link TestEngine} ready for use.
  */
-declare function createTestEngine<T extends ScenePart>(page: Page, partDefinitions: T): TestEngine<T>;
+declare function createTestEngine<T extends ScenePart>(page: Page, partDefinitions: T, _option?: ITestEngineOption): TestEngine<T>;
 //#endregion
 //#region src/PlaywrightInteractor.d.ts
 /**
@@ -23,11 +25,32 @@ declare class PlaywrightInteractor implements Interactor {
    * @param page - Playwright page instance used to drive the browser.
    */
   constructor(page: Page);
+  /**
+   * Run a Playwright mutation and normalize a "locator matched nothing" failure
+   * into {@link ElementNotFoundError}, so a missing element throws the same error
+   * class here as it does in `DOMInteractor`, regardless of environment (the
+   * unified contract ratified in ADR-006).
+   *
+   * Playwright auto-waits for actionability and then throws its own
+   * `TimeoutError`. We translate that to `ElementNotFoundError` ONLY when the
+   * element genuinely does not exist (count 0) and otherwise rethrow the original
+   * error — preserving Playwright's auto-wait for an element that exists but is
+   * briefly not actionable (covered, disabled, animating). The trade-off is that
+   * a truly-missing element waits out the page's action timeout before throwing;
+   * bound it with `page.setDefaultTimeout` when fast failure matters.
+   *
+   * @param locator - Locator the mutation targets
+   * @param action - Method name used in the error message (e.g. `'click'`)
+   * @param run - The Playwright action to execute
+   * @throws {ElementNotFoundError} If the action fails and the element is absent
+   */
+  private runMutation;
   /**
    * Select the given option values on a `<select>` element.
    *
    * @param locator - Locator to the `<select>` element.
    * @param values - Values to select.
+   * @throws {ElementNotFoundError} If the element is not found
    */
   selectOptionValue(locator: PartLocator, values: string[]): Promise<void>;
   /**
@@ -35,23 +58,21 @@ declare class PlaywrightInteractor implements Interactor {
    *
    * Playwright's native `setInputFiles` reads the given paths from disk and
    * populates the input's `FileList`, firing the change event — the only way to
-   * fill a file input, whose value cannot be set programmatically. Following
-   * this layer's convention, no `ElementNotFoundError` is fabricated: a missing
-   * element surfaces through Playwright's own auto-wait timeout.
+   * fill a file input, whose value cannot be set programmatically.
    *
    * @param locator - Locator of the `<input type="file">` element
    * @param files - One or more filesystem paths to upload
+   * @throws {ElementNotFoundError} If the element is not found
    */
   setInputFiles(locator: PartLocator, files: string | string[]): Promise<void>;
   /**
    * Scroll the located element into view, no-op if already visible.
    *
    * Delegates to Playwright's `scrollIntoViewIfNeeded`, which performs a real
-   * layout-aware scroll in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * layout-aware scroll in the browser.
    *
    * @param locator - Locator of the element to scroll into view
+   * @throws {ElementNotFoundError} If the element is not found
    */
   scrollIntoView(locator: PartLocator): Promise<void>;
   /**
@@ -63,24 +84,22 @@ declare class PlaywrightInteractor implements Interactor {
    * whereas evaluating `scrollBy` on the resolved element scrolls exactly that
    * element. This is a deliberate deviation from ADR 0001's per-engine table
    * (which lists `page.mouse.wheel`), taking the alternative the step-5 prompt
-   * permits ("or evaluate el.scrollBy") for cross-browser determinism. As with
-   * {@link scrollIntoView}, no `ElementNotFoundError` is fabricated; a missing
-   * element surfaces through Playwright's own auto-wait timeout.
+   * permits ("or evaluate el.scrollBy") for cross-browser determinism.
    *
    * @param locator - Locator of the scrollable element
    * @param delta - Pixel offset to scroll by
+   * @throws {ElementNotFoundError} If the element is not found
    */
   scrollBy(locator: PartLocator, delta: Point): Promise<void>;
   /**
    * Drag the source element and drop it onto the target element.
    *
    * Delegates to Playwright's native `Locator.dragTo`, which performs a real,
-   * layout-aware drag gesture in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * layout-aware drag gesture in the browser.
    *
    * @param source - Locator of the element to drag
    * @param target - Locator of the drop target
+   * @throws {ElementNotFoundError} If either the source or target is not found
    */
   dragTo(source: PartLocator, target: PartLocator): Promise<void>;
   /**
@@ -91,9 +110,9 @@ declare class PlaywrightInteractor implements Interactor {
    * {@link mouseMove}/{@link mouseDown} — `mouseMove` resets the pointer with
    * `page.mouse.move(0, 0)` after hovering, which would corrupt the drag path
    * (see ADR 0001, option 5). The center comes from {@link getBoundingRect},
-   * which throws `ElementNotFoundError` when the element has no box
-   * (detached/invisible) rather than auto-waiting — so this shares that
-   * "element not found" contract instead of re-deriving the box + guard here.
+   * which throws `ElementNotFoundError` when the element has no box, so this
+   * shares that "element not found" contract instead of re-deriving the box +
+   * guard here.
    *
    * @param locator - Locator of the element to drag
    * @param delta - Pixel offset to drag by
@@ -117,16 +136,16 @@ declare class PlaywrightInteractor implements Interactor {
   getSelectLabels(locator: PartLocator): Promise<Optional<readonly string[]>>;
   getStyleValue(locator: PartLocator, propertyName: CssProperty): Promise<Optional<string>>;
   enterText(locator: PartLocator, text: string, option?: Optional<Partial<EnterTextOption>>): Promise<void>;
+  setRangeValue(locator: PartLocator, value: number): Promise<void>;
   click(locator: PartLocator, option?: Partial<ClickOption>): Promise<void>;
   /**
    * Dispatch a right-click on the located element to open its context menu.
    *
    * Delegates to Playwright's native right-button click, which fires a real
-   * `contextmenu` event in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * `contextmenu` event in the browser.
    *
    * @param locator - Locator of the element to right-click
+   * @throws {ElementNotFoundError} If the element is not found
    */
   contextMenu(locator: PartLocator): Promise<void>;
   hover(locator: PartLocator, option?: Partial<HoverOption>): Promise<void>;
@@ -141,7 +160,6 @@ declare class PlaywrightInteractor implements Interactor {
   blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void>;
   pressKey(locator: PartLocator, key: string, option?: Partial<PressKeyOption>): Promise<void>;
   activate(locator: PartLocator): Promise<void>;
-  wait(ms: number): Promise<void>;
   waitUntilComponentState(locator: PartLocator, option?: Partial<Readonly<WaitForOption>>): Promise<void>;
   waitUntil<T>(option: WaitUntilOption<T>): Promise<T>;
   getAttribute(locator: PartLocator, name: string, isMultiple: true): Promise<readonly string[]>;
@@ -152,9 +170,8 @@ declare class PlaywrightInteractor implements Interactor {
    * Get the located element's bounding rectangle.
    *
    * `boundingBox()` returns `null` for a detached/invisible element rather than
-   * auto-waiting, so this is one of the few Playwright methods that throws
-   * `ElementNotFoundError` — matching the house "element not found" contract
-   * (ADR 0001).
+   * auto-waiting, so this throws `ElementNotFoundError` directly (no auto-wait)
+   * — matching the unified "element not found" contract (ADR-006).
    *
    * @param locator - Locator of the element to measure
    * @returns The element's bounding rectangle in CSS pixels
@@ -165,37 +182,13 @@ declare class PlaywrightInteractor implements Interactor {
   isChecked(locator: PartLocator): Promise<boolean>;
   isDisabled(locator: PartLocator): Promise<boolean>;
   isReadonly(locator: PartLocator): Promise<boolean>;
+  isRequired(locator: PartLocator): Promise<boolean>;
+  isError(locator: PartLocator): Promise<boolean>;
   isVisible(locator: PartLocator): Promise<boolean>;
   hasCssClass(locator: PartLocator, className: string): Promise<boolean>;
   hasAttribute(locator: PartLocator, name: string): Promise<boolean>;
   innerHTML(locator: PartLocator): Promise<string>;
-  clone(): Interactor;
 }
 //#endregion
-//#region src/testRunnerAdapter.d.ts
-/**
- * Navigate the current Playwright page to the provided URL.
- *
- * @param url - Destination URL to load.
- * @param fixture - Optional test fixture supplying the Playwright page.
- */
-declare function goto(url: string): Promise<void>;
-declare function goto(url: string, fixture: E2eTestRunEnvironmentFixture): Promise<void>;
-/**
- * Create a {@link TestEngine} bound to the Playwright page in the given fixture.
- *
- * @param scenePart - Scene definition to drive.
- * @param fixture - Fixture providing the Playwright page.
- */
-declare function playwrightGetTestEngine<T extends ScenePart>(scenePart: T, fixture: E2eTestRunEnvironmentFixture): TestEngine<T>;
-/**
- * Playwright adapter for the TestFrameworkMapper interface.
- */
-declare const playWrightTestFrameworkMapper: TestFrameworkMapper;
-/**
- * Get a typed interface for running end-to-end tests with Playwright.
- */
-declare function getTestRunnerInterface<T extends ScenePart>(): E2eTestInterface<T>;
-//#endregion
-export { PlaywrightInteractor, createTestEngine, getTestRunnerInterface, goto, playWrightTestFrameworkMapper, playwrightGetTestEngine };
+export { PlaywrightInteractor, createTestEngine };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,6 +1,5 @@
-import { BlurOption, BoundingRect, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, Point, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
+import { BlurOption, BoundingRect, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, ITestEngineOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, Point, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
 import { Page } from "@playwright/test";
-import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } from "@atomic-testing/internal-test-runner";
 
 //#region src/createTestEngine.d.ts
 /**
@@ -9,9 +8,12 @@ import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } f
  * @param page - Playwright page used for interaction.
  * @param partDefinitions - Scene part definitions describing the scene
  *   structure for the engine.
+ * @param _option - Reserved for entry-point symmetry with the other adapters;
+ *   currently ignored. `rootElement` is not applicable to Playwright, which drives
+ *   a real browser page rather than mounting into a host element.
  * @returns A configured {@link TestEngine} ready for use.
  */
-declare function createTestEngine<T extends ScenePart>(page: Page, partDefinitions: T): TestEngine<T>;
+declare function createTestEngine<T extends ScenePart>(page: Page, partDefinitions: T, _option?: ITestEngineOption): TestEngine<T>;
 //#endregion
 //#region src/PlaywrightInteractor.d.ts
 /**
@@ -23,11 +25,32 @@ declare class PlaywrightInteractor implements Interactor {
    * @param page - Playwright page instance used to drive the browser.
    */
   constructor(page: Page);
+  /**
+   * Run a Playwright mutation and normalize a "locator matched nothing" failure
+   * into {@link ElementNotFoundError}, so a missing element throws the same error
+   * class here as it does in `DOMInteractor`, regardless of environment (the
+   * unified contract ratified in ADR-006).
+   *
+   * Playwright auto-waits for actionability and then throws its own
+   * `TimeoutError`. We translate that to `ElementNotFoundError` ONLY when the
+   * element genuinely does not exist (count 0) and otherwise rethrow the original
+   * error — preserving Playwright's auto-wait for an element that exists but is
+   * briefly not actionable (covered, disabled, animating). The trade-off is that
+   * a truly-missing element waits out the page's action timeout before throwing;
+   * bound it with `page.setDefaultTimeout` when fast failure matters.
+   *
+   * @param locator - Locator the mutation targets
+   * @param action - Method name used in the error message (e.g. `'click'`)
+   * @param run - The Playwright action to execute
+   * @throws {ElementNotFoundError} If the action fails and the element is absent
+   */
+  private runMutation;
   /**
    * Select the given option values on a `<select>` element.
    *
    * @param locator - Locator to the `<select>` element.
    * @param values - Values to select.
+   * @throws {ElementNotFoundError} If the element is not found
    */
   selectOptionValue(locator: PartLocator, values: string[]): Promise<void>;
   /**
@@ -35,23 +58,21 @@ declare class PlaywrightInteractor implements Interactor {
    *
    * Playwright's native `setInputFiles` reads the given paths from disk and
    * populates the input's `FileList`, firing the change event — the only way to
-   * fill a file input, whose value cannot be set programmatically. Following
-   * this layer's convention, no `ElementNotFoundError` is fabricated: a missing
-   * element surfaces through Playwright's own auto-wait timeout.
+   * fill a file input, whose value cannot be set programmatically.
    *
    * @param locator - Locator of the `<input type="file">` element
    * @param files - One or more filesystem paths to upload
+   * @throws {ElementNotFoundError} If the element is not found
    */
   setInputFiles(locator: PartLocator, files: string | string[]): Promise<void>;
   /**
    * Scroll the located element into view, no-op if already visible.
    *
    * Delegates to Playwright's `scrollIntoViewIfNeeded`, which performs a real
-   * layout-aware scroll in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * layout-aware scroll in the browser.
    *
    * @param locator - Locator of the element to scroll into view
+   * @throws {ElementNotFoundError} If the element is not found
    */
   scrollIntoView(locator: PartLocator): Promise<void>;
   /**
@@ -63,24 +84,22 @@ declare class PlaywrightInteractor implements Interactor {
    * whereas evaluating `scrollBy` on the resolved element scrolls exactly that
    * element. This is a deliberate deviation from ADR 0001's per-engine table
    * (which lists `page.mouse.wheel`), taking the alternative the step-5 prompt
-   * permits ("or evaluate el.scrollBy") for cross-browser determinism. As with
-   * {@link scrollIntoView}, no `ElementNotFoundError` is fabricated; a missing
-   * element surfaces through Playwright's own auto-wait timeout.
+   * permits ("or evaluate el.scrollBy") for cross-browser determinism.
    *
    * @param locator - Locator of the scrollable element
    * @param delta - Pixel offset to scroll by
+   * @throws {ElementNotFoundError} If the element is not found
    */
   scrollBy(locator: PartLocator, delta: Point): Promise<void>;
   /**
    * Drag the source element and drop it onto the target element.
    *
    * Delegates to Playwright's native `Locator.dragTo`, which performs a real,
-   * layout-aware drag gesture in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * layout-aware drag gesture in the browser.
    *
    * @param source - Locator of the element to drag
    * @param target - Locator of the drop target
+   * @throws {ElementNotFoundError} If either the source or target is not found
    */
   dragTo(source: PartLocator, target: PartLocator): Promise<void>;
   /**
@@ -91,9 +110,9 @@ declare class PlaywrightInteractor implements Interactor {
    * {@link mouseMove}/{@link mouseDown} — `mouseMove` resets the pointer with
    * `page.mouse.move(0, 0)` after hovering, which would corrupt the drag path
    * (see ADR 0001, option 5). The center comes from {@link getBoundingRect},
-   * which throws `ElementNotFoundError` when the element has no box
-   * (detached/invisible) rather than auto-waiting — so this shares that
-   * "element not found" contract instead of re-deriving the box + guard here.
+   * which throws `ElementNotFoundError` when the element has no box, so this
+   * shares that "element not found" contract instead of re-deriving the box +
+   * guard here.
    *
    * @param locator - Locator of the element to drag
    * @param delta - Pixel offset to drag by
@@ -117,16 +136,16 @@ declare class PlaywrightInteractor implements Interactor {
   getSelectLabels(locator: PartLocator): Promise<Optional<readonly string[]>>;
   getStyleValue(locator: PartLocator, propertyName: CssProperty): Promise<Optional<string>>;
   enterText(locator: PartLocator, text: string, option?: Optional<Partial<EnterTextOption>>): Promise<void>;
+  setRangeValue(locator: PartLocator, value: number): Promise<void>;
   click(locator: PartLocator, option?: Partial<ClickOption>): Promise<void>;
   /**
    * Dispatch a right-click on the located element to open its context menu.
    *
    * Delegates to Playwright's native right-button click, which fires a real
-   * `contextmenu` event in the browser. Per this layer's convention, no
-   * `ElementNotFoundError` is fabricated: a missing element surfaces through
-   * Playwright's own auto-wait timeout.
+   * `contextmenu` event in the browser.
    *
    * @param locator - Locator of the element to right-click
+   * @throws {ElementNotFoundError} If the element is not found
    */
   contextMenu(locator: PartLocator): Promise<void>;
   hover(locator: PartLocator, option?: Partial<HoverOption>): Promise<void>;
@@ -141,7 +160,6 @@ declare class PlaywrightInteractor implements Interactor {
   blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void>;
   pressKey(locator: PartLocator, key: string, option?: Partial<PressKeyOption>): Promise<void>;
   activate(locator: PartLocator): Promise<void>;
-  wait(ms: number): Promise<void>;
   waitUntilComponentState(locator: PartLocator, option?: Partial<Readonly<WaitForOption>>): Promise<void>;
   waitUntil<T>(option: WaitUntilOption<T>): Promise<T>;
   getAttribute(locator: PartLocator, name: string, isMultiple: true): Promise<readonly string[]>;
@@ -152,9 +170,8 @@ declare class PlaywrightInteractor implements Interactor {
    * Get the located element's bounding rectangle.
    *
    * `boundingBox()` returns `null` for a detached/invisible element rather than
-   * auto-waiting, so this is one of the few Playwright methods that throws
-   * `ElementNotFoundError` — matching the house "element not found" contract
-   * (ADR 0001).
+   * auto-waiting, so this throws `ElementNotFoundError` directly (no auto-wait)
+   * — matching the unified "element not found" contract (ADR-006).
    *
    * @param locator - Locator of the element to measure
    * @returns The element's bounding rectangle in CSS pixels
@@ -165,37 +182,13 @@ declare class PlaywrightInteractor implements Interactor {
   isChecked(locator: PartLocator): Promise<boolean>;
   isDisabled(locator: PartLocator): Promise<boolean>;
   isReadonly(locator: PartLocator): Promise<boolean>;
+  isRequired(locator: PartLocator): Promise<boolean>;
+  isError(locator: PartLocator): Promise<boolean>;
   isVisible(locator: PartLocator): Promise<boolean>;
   hasCssClass(locator: PartLocator, className: string): Promise<boolean>;
   hasAttribute(locator: PartLocator, name: string): Promise<boolean>;
   innerHTML(locator: PartLocator): Promise<string>;
-  clone(): Interactor;
 }
 //#endregion
-//#region src/testRunnerAdapter.d.ts
-/**
- * Navigate the current Playwright page to the provided URL.
- *
- * @param url - Destination URL to load.
- * @param fixture - Optional test fixture supplying the Playwright page.
- */
-declare function goto(url: string): Promise<void>;
-declare function goto(url: string, fixture: E2eTestRunEnvironmentFixture): Promise<void>;
-/**
- * Create a {@link TestEngine} bound to the Playwright page in the given fixture.
- *
- * @param scenePart - Scene definition to drive.
- * @param fixture - Fixture providing the Playwright page.
- */
-declare function playwrightGetTestEngine<T extends ScenePart>(scenePart: T, fixture: E2eTestRunEnvironmentFixture): TestEngine<T>;
-/**
- * Playwright adapter for the TestFrameworkMapper interface.
- */
-declare const playWrightTestFrameworkMapper: TestFrameworkMapper;
-/**
- * Get a typed interface for running end-to-end tests with Playwright.
- */
-declare function getTestRunnerInterface<T extends ScenePart>(): E2eTestInterface<T>;
-//#endregion
-export { PlaywrightInteractor, createTestEngine, getTestRunnerInterface, goto, playWrightTestFrameworkMapper, playwrightGetTestEngine };
+export { PlaywrightInteractor, createTestEngine };
 //# sourceMappingURL=index.d.mts.map