@atomic-testing/playwright 0.87.0 → 0.89.0

package/dist/index.d.cts

@@ -1,6 +1,5 @@
-import { BlurOption, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
+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 { Page } from "@playwright/test";
-import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } from "@atomic-testing/internal-test-runner";
 
 //#region src/createTestEngine.d.ts
 /**
@@ -23,13 +22,100 @@ 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>;
+  /**
+   * Set the selected files on a `<input type="file">` element.
+   *
+   * 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.
+   *
+   * @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.
+   *
+   * @param locator - Locator of the element to scroll into view
+   * @throws {ElementNotFoundError} If the element is not found
+   */
+  scrollIntoView(locator: PartLocator): Promise<void>;
+  /**
+   * Scroll the located element by the given pixel delta.
+   *
+   * The scroll is performed by evaluating `el.scrollBy(dx, dy)` on the element
+   * itself rather than `page.mouse.wheel`. A wheel event scrolls whatever sits
+   * under the pointer and is non-deterministic across chromium/firefox/webkit,
+   * 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.
+   *
+   * @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.
+   *
+   * @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>;
+  /**
+   * Drag the located element by the given pixel delta from its center.
+   *
+   * The gesture is a single uninterrupted `move → down → move → up` sequence
+   * computed from the element's center. It deliberately does NOT reuse
+   * {@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, 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
+   * @throws {ElementNotFoundError} If the element has no bounding box
+   */
+  drag(locator: PartLocator, delta: Point): Promise<void>;
   /**
    * Get the value of an `<input>` element.
    *
@@ -47,7 +133,18 @@ 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.
+   *
+   * @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>;
   mouseMove(locator: PartLocator, option?: Partial<MouseMoveOption>): Promise<void>;
   mouseDown(locator: PartLocator, option?: Partial<MouseDownOption>): Promise<void>;
@@ -58,7 +155,7 @@ declare class PlaywrightInteractor implements Interactor {
   mouseLeave(locator: PartLocator, _option?: Partial<MouseLeaveOption>): Promise<void>;
   focus(locator: PartLocator, _option?: Partial<FocusOption>): Promise<void>;
   blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void>;
-  pressKey(locator: PartLocator, key: string, _option?: Partial<PressKeyOption>): 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>;
@@ -67,6 +164,18 @@ declare class PlaywrightInteractor implements Interactor {
   getAttribute(locator: PartLocator, name: string, isMultiple: false): Promise<Optional<string>>;
   getAttribute(locator: PartLocator, name: string): Promise<Optional<string>>;
   getText(locator: PartLocator): Promise<Optional<string>>;
+  /**
+   * Get the located element's bounding rectangle.
+   *
+   * `boundingBox()` returns `null` for a detached/invisible element rather than
+   * 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
+   * @throws {ElementNotFoundError} If the element has no bounding box
+   */
+  getBoundingRect(locator: PartLocator): Promise<BoundingRect>;
   exists(locator: PartLocator): Promise<boolean>;
   isChecked(locator: PartLocator): Promise<boolean>;
   isDisabled(locator: PartLocator): Promise<boolean>;
@@ -78,30 +187,5 @@ declare class PlaywrightInteractor implements Interactor {
   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, ClickOption, CssProperty, EnterTextOption, FocusOption, HoverOption, Interactor, MouseDownOption, MouseEnterOption, MouseLeaveOption, MouseMoveOption, MouseOutOption, MouseUpOption, Optional, PartLocator, PressKeyOption, ScenePart, TestEngine, WaitForOption, WaitUntilOption } from "@atomic-testing/core";
+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 { Page } from "@playwright/test";
-import { E2eTestInterface, E2eTestRunEnvironmentFixture, TestFrameworkMapper } from "@atomic-testing/internal-test-runner";
 
 //#region src/createTestEngine.d.ts
 /**
@@ -23,13 +22,100 @@ 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>;
+  /**
+   * Set the selected files on a `<input type="file">` element.
+   *
+   * 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.
+   *
+   * @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.
+   *
+   * @param locator - Locator of the element to scroll into view
+   * @throws {ElementNotFoundError} If the element is not found
+   */
+  scrollIntoView(locator: PartLocator): Promise<void>;
+  /**
+   * Scroll the located element by the given pixel delta.
+   *
+   * The scroll is performed by evaluating `el.scrollBy(dx, dy)` on the element
+   * itself rather than `page.mouse.wheel`. A wheel event scrolls whatever sits
+   * under the pointer and is non-deterministic across chromium/firefox/webkit,
+   * 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.
+   *
+   * @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.
+   *
+   * @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>;
+  /**
+   * Drag the located element by the given pixel delta from its center.
+   *
+   * The gesture is a single uninterrupted `move → down → move → up` sequence
+   * computed from the element's center. It deliberately does NOT reuse
+   * {@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, 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
+   * @throws {ElementNotFoundError} If the element has no bounding box
+   */
+  drag(locator: PartLocator, delta: Point): Promise<void>;
   /**
    * Get the value of an `<input>` element.
    *
@@ -47,7 +133,18 @@ 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.
+   *
+   * @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>;
   mouseMove(locator: PartLocator, option?: Partial<MouseMoveOption>): Promise<void>;
   mouseDown(locator: PartLocator, option?: Partial<MouseDownOption>): Promise<void>;
@@ -58,7 +155,7 @@ declare class PlaywrightInteractor implements Interactor {
   mouseLeave(locator: PartLocator, _option?: Partial<MouseLeaveOption>): Promise<void>;
   focus(locator: PartLocator, _option?: Partial<FocusOption>): Promise<void>;
   blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void>;
-  pressKey(locator: PartLocator, key: string, _option?: Partial<PressKeyOption>): 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>;
@@ -67,6 +164,18 @@ declare class PlaywrightInteractor implements Interactor {
   getAttribute(locator: PartLocator, name: string, isMultiple: false): Promise<Optional<string>>;
   getAttribute(locator: PartLocator, name: string): Promise<Optional<string>>;
   getText(locator: PartLocator): Promise<Optional<string>>;
+  /**
+   * Get the located element's bounding rectangle.
+   *
+   * `boundingBox()` returns `null` for a detached/invisible element rather than
+   * 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
+   * @throws {ElementNotFoundError} If the element has no bounding box
+   */
+  getBoundingRect(locator: PartLocator): Promise<BoundingRect>;
   exists(locator: PartLocator): Promise<boolean>;
   isChecked(locator: PartLocator): Promise<boolean>;
   isDisabled(locator: PartLocator): Promise<boolean>;
@@ -78,30 +187,5 @@ declare class PlaywrightInteractor implements Interactor {
   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