@atomic-testing/playwright 0.87.0 → 0.89.0

package/src/PlaywrightInteractor.ts

@@ -1,10 +1,12 @@
 import {
   BlurOption,
+  BoundingRect,
   byCssSelector,
   ClickOption,
   CssProperty,
   dateUtil,
   defaultWaitForOption,
+  ElementNotFoundError,
   EnterTextOption,
   FocusOption,
   HoverOption,
@@ -19,6 +21,7 @@ import {
   MouseUpOption,
   Optional,
   PartLocator,
+  Point,
   PressKeyOption,
   timingUtil,
   WaitForOption,
@@ -35,15 +38,150 @@ export class PlaywrightInteractor implements Interactor {
    */
   constructor(public readonly 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 async runMutation<T>(locator: PartLocator, action: string, run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (e) {
+      if ((await this.exists(locator)) === false) {
+        throw new ElementNotFoundError(locator, action);
+      }
+      throw e;
+    }
+  }
+
   /**
    * 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
    */
   async selectOptionValue(locator: PartLocator, values: string[]): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    await this.page.locator(cssLocator).selectOption(values);
+    await this.runMutation(locator, 'selectOptionValue', () => this.page.locator(cssLocator).selectOption(values));
+  }
+
+  /**
+   * 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
+   */
+  async setInputFiles(locator: PartLocator, files: string | string[]): Promise<void> {
+    const cssLocator = await locatorUtil.toCssSelector(locator, this);
+    await this.runMutation(locator, 'setInputFiles', () => this.page.locator(cssLocator).setInputFiles(files));
+  }
+
+  /**
+   * 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
+   */
+  async scrollIntoView(locator: PartLocator): Promise<void> {
+    const css = await locatorUtil.toCssSelector(locator, this);
+    await this.runMutation(locator, 'scrollIntoView', () => this.page.locator(css).scrollIntoViewIfNeeded());
+  }
+
+  /**
+   * 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
+   */
+  async scrollBy(locator: PartLocator, delta: Point): Promise<void> {
+    const css = await locatorUtil.toCssSelector(locator, this);
+    await this.runMutation(locator, 'scrollBy', () =>
+      this.page.locator(css).evaluate((el, d) => el.scrollBy(d.x, d.y), { x: delta.x, y: delta.y })
+    );
+  }
+
+  /**
+   * 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
+   */
+  async dragTo(source: PartLocator, target: PartLocator): Promise<void> {
+    const srcCss = await locatorUtil.toCssSelector(source, this);
+    const tgtCss = await locatorUtil.toCssSelector(target, this);
+    try {
+      await this.page.locator(srcCss).dragTo(this.page.locator(tgtCss));
+    } catch (e) {
+      if ((await this.exists(source)) === false) {
+        throw new ElementNotFoundError(source, 'dragTo');
+      }
+      if ((await this.exists(target)) === false) {
+        throw new ElementNotFoundError(target, 'dragTo');
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * 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
+   */
+  async drag(locator: PartLocator, delta: Point): Promise<void> {
+    const rect = await this.getBoundingRect(locator);
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    await this.page.mouse.move(cx, cy);
+    await this.page.mouse.down();
+    await this.page.mouse.move(cx + delta.x, cy + delta.y, { steps: 8 });
+    await this.page.mouse.up();
   }
 
   /**
@@ -104,93 +242,152 @@ export class PlaywrightInteractor implements Interactor {
 
   async enterText(locator: PartLocator, text: string, option?: Optional<Partial<EnterTextOption>>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    if (!option?.append) {
-      await this.page.locator(cssLocator).clear();
-    }
+    await this.runMutation(locator, 'enterText', async () => {
+      if (!option?.append) {
+        await this.page.locator(cssLocator).clear();
+      }
 
-    // If it is a date, time or datetime-local input, validate the date format
-    const type = (await this.getAttribute(locator, 'type')) ?? '';
-    if (dateUtil.isHtmlDateInputType(type)) {
-      const result = dateUtil.validateHtmlDateInput(type, text);
-      if (!result.valid) {
-        throw new Error(
-          `Invalid date format for type: ${type}, expected format: ${result.format}, example: ${result.example}`
-        );
+      // If it is a date, time or datetime-local input, validate the date format
+      const type = (await this.getAttribute(locator, 'type')) ?? '';
+      if (dateUtil.isHtmlDateInputType(type)) {
+        const result = dateUtil.validateHtmlDateInput(type, text);
+        if (!result.valid) {
+          throw new Error(
+            `Invalid date format for type: ${type}, expected format: ${result.format}, example: ${result.example}`
+          );
+        }
       }
-    }
-    await this.page.locator(cssLocator).fill(text);
+      await this.page.locator(cssLocator).fill(text);
+    });
+  }
+
+  async setRangeValue(locator: PartLocator, value: number): Promise<void> {
+    const cssLocator = await locatorUtil.toCssSelector(locator, this);
+    // Playwright's `fill` rejects `<input type="range">` (it is not a fillable
+    // text control), so set the value in-page through the native value setter.
+    // Calling the prototype setter both sanitizes the value to the input's step
+    // (the browser snaps an off-step target to the nearest valid step) and lets
+    // React's value tracker observe the change; the dispatched input/change
+    // events then drive a controlled component (e.g. MUI Slider) to re-render.
+    await this.runMutation(locator, 'setRangeValue', () =>
+      this.page.locator(cssLocator).evaluate((el, nextValue) => {
+        const input = el as HTMLInputElement;
+        const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set;
+        setter?.call(input, nextValue);
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+      }, String(value))
+    );
   }
 
   async click(locator: PartLocator, option?: Partial<ClickOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    await this.page.locator(cssLocator).click({ position: option?.position });
+    await this.runMutation(locator, 'click', () => this.page.locator(cssLocator).click({ position: option?.position }));
+  }
+
+  /**
+   * 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
+   */
+  async contextMenu(locator: PartLocator): Promise<void> {
+    const css = await locatorUtil.toCssSelector(locator, this);
+    await this.runMutation(locator, 'contextMenu', () => this.page.locator(css).click({ button: 'right' }));
   }
 
   async hover(locator: PartLocator, option?: Partial<HoverOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    await this.page.locator(cssLocator).hover({ position: option?.position });
+    await this.runMutation(locator, 'hover', () => this.page.locator(cssLocator).hover({ position: option?.position }));
   }
 
   async mouseMove(locator: PartLocator, option?: Partial<MouseMoveOption>): Promise<void> {
-    await this.hover(locator, {
-      position: option?.position,
+    await this.runMutation(locator, 'mouseMove', async () => {
+      await this.hover(locator, { position: option?.position });
+      await this.page.mouse.move(0, 0);
     });
-    await this.page.mouse.move(0, 0);
   }
 
   async mouseDown(locator: PartLocator, option?: Partial<MouseDownOption>): Promise<void> {
-    await this.hover(locator, {
-      position: option?.position,
+    await this.runMutation(locator, 'mouseDown', async () => {
+      await this.hover(locator, { position: option?.position });
+      await this.page.mouse.down();
     });
-    await this.page.mouse.down();
   }
 
   async mouseUp(locator: PartLocator, option?: Partial<MouseUpOption>): Promise<void> {
-    await this.hover(locator, {
-      position: option?.position,
+    await this.runMutation(locator, 'mouseUp', async () => {
+      await this.hover(locator, { position: option?.position });
+      await this.page.mouse.up();
     });
-    await this.page.mouse.up();
   }
 
   async mouseOver(locator: PartLocator, option?: Partial<HoverOption>): Promise<void> {
-    return this.hover(locator, option);
+    await this.runMutation(locator, 'mouseOver', () => this.hover(locator, option));
   }
 
   async mouseOut(locator: PartLocator, _option?: Partial<MouseOutOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    // First hover over the element to trigger mouseenter/mouseover
-    await this.page.locator(cssLocator).hover();
-    // Then dispatch mouseout event directly for cross-browser reliability
-    await this.page.locator(cssLocator).dispatchEvent('mouseout');
+    await this.runMutation(locator, 'mouseOut', async () => {
+      // First hover over the element to trigger mouseenter/mouseover
+      await this.page.locator(cssLocator).hover();
+      // Then dispatch mouseout event directly for cross-browser reliability
+      await this.page.locator(cssLocator).dispatchEvent('mouseout');
+    });
   }
 
   async mouseEnter(locator: PartLocator, _option?: Partial<MouseEnterOption>): Promise<void> {
-    return this.hover(locator);
+    await this.runMutation(locator, 'mouseEnter', () => this.hover(locator));
   }
 
   async mouseLeave(locator: PartLocator, _option?: Partial<MouseLeaveOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    // First hover over the element to trigger mouseenter/mouseover
-    await this.page.locator(cssLocator).hover();
-    // Dispatch mouseout which triggers both mouseout and mouseleave handlers in React
-    await this.page.locator(cssLocator).dispatchEvent('mouseout');
+    await this.runMutation(locator, 'mouseLeave', async () => {
+      // First hover over the element to trigger mouseenter/mouseover
+      await this.page.locator(cssLocator).hover();
+      // Dispatch mouseout which triggers both mouseout and mouseleave handlers in React
+      await this.page.locator(cssLocator).dispatchEvent('mouseout');
+    });
   }
 
   async focus(locator: PartLocator, _option?: Partial<FocusOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    return this.page.focus(cssLocator);
+    await this.runMutation(locator, 'focus', () => this.page.focus(cssLocator));
   }
 
   async blur(locator: PartLocator, _option?: Partial<BlurOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
-    await this.page.locator(cssLocator).blur();
+    await this.runMutation(locator, 'blur', () => this.page.locator(cssLocator).blur());
   }
 
-  async pressKey(locator: PartLocator, key: string, _option?: Partial<PressKeyOption>): Promise<void> {
+  async pressKey(locator: PartLocator, key: string, option?: Partial<PressKeyOption>): Promise<void> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
+    // Compose Playwright's chord syntax — modifiers joined to the key by `+`, in
+    // Playwright's accepted Control+Alt+Shift+Meta order — so the browser holds
+    // those modifiers across the keypress and the event carries ctrlKey/etc.
+    const modifiers: string[] = [];
+    if (option?.ctrl) {
+      modifiers.push('Control');
+    }
+    if (option?.alt) {
+      modifiers.push('Alt');
+    }
+    if (option?.shift) {
+      modifiers.push('Shift');
+    }
+    if (option?.meta) {
+      modifiers.push('Meta');
+    }
+    const chord = modifiers.length > 0 ? `${modifiers.join('+')}+${key}` : key;
     // locator.press auto-focuses the element, then dispatches a real, trusted
     // KeyboardEvent — the browser equivalent of the DOM focus-first keyDown/keyUp.
-    await this.page.locator(cssLocator).press(key);
+    // Caveat: for Shift + a printable key the browser case-folds `event.key`
+    // (`Shift+a` → `'A'`) whereas the jsdom path keeps `'a'` — only the modifier
+    // flags are delivered identically across engines (see #924).
+    await this.runMutation(locator, 'pressKey', () => this.page.locator(cssLocator).press(chord));
   }
 
   async activate(locator: PartLocator): Promise<void> {
@@ -198,7 +395,7 @@ export class PlaywrightInteractor implements Interactor {
     // Geometry-free activation mirrors the mouseout dispatch precedent above: it
     // bypasses hit-testing to actuate a covered or zero-size input that
     // locator.click() (a real geometry hit-test) cannot reach.
-    await this.page.locator(cssLocator).dispatchEvent('click');
+    await this.runMutation(locator, 'activate', () => this.page.locator(cssLocator).dispatchEvent('click'));
   }
 
   //#region wait conditions
@@ -249,6 +446,26 @@ export class PlaywrightInteractor implements Interactor {
     return text ?? undefined;
   }
 
+  /**
+   * 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
+   */
+  async getBoundingRect(locator: PartLocator): Promise<BoundingRect> {
+    const css = await locatorUtil.toCssSelector(locator, this);
+    const box = await this.page.locator(css).boundingBox();
+    if (box == null) {
+      throw new ElementNotFoundError(locator, 'getBoundingRect');
+    }
+    return { x: box.x, y: box.y, width: box.width, height: box.height };
+  }
+
   async exists(locator: PartLocator): Promise<boolean> {
     const cssLocator = await locatorUtil.toCssSelector(locator, this);
     const count = await this.page.locator(cssLocator).count();

package/src/index.ts

@@ -1,3 +1,2 @@
 export { createTestEngine } from './createTestEngine';
 export { PlaywrightInteractor } from './PlaywrightInteractor';
-export * from './testRunnerAdapter';

package/src/testRunnerAdapter.ts

@@ -1,79 +0,0 @@
-import { ScenePart, TestEngine } from '@atomic-testing/core';
-import {
-  E2eTestInterface,
-  E2eTestRunEnvironmentFixture,
-  TestFrameworkMapper,
-} from '@atomic-testing/internal-test-runner';
-import { expect, Page, test } from '@playwright/test';
-
-import { createTestEngine } from './createTestEngine';
-
-/**
- * Navigate the current Playwright page to the provided URL.
- *
- * @param url - Destination URL to load.
- * @param fixture - Optional test fixture supplying the Playwright page.
- */
-export async function goto(url: string): Promise<void>;
-export async function goto(url: string, fixture: E2eTestRunEnvironmentFixture): Promise<void>;
-export async function goto(url: string, fixture?: E2eTestRunEnvironmentFixture): Promise<void> {
-  const page = fixture!.page as Page;
-  await page.goto(url);
-}
-
-/**
- * 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.
- */
-export function playwrightGetTestEngine<T extends ScenePart>(
-  scenePart: T,
-  fixture: E2eTestRunEnvironmentFixture
-): TestEngine<T> {
-  const page = fixture.page as Page;
-  return createTestEngine(page, scenePart);
-}
-
-/**
- * Playwright adapter for the TestFrameworkMapper interface.
- */
-export const playWrightTestFrameworkMapper: TestFrameworkMapper = {
-  /*
-   * INTENTIONAL @ts-expect-error comments: Playwright's test functions have different type
-   * signatures than the normalized TestFrameworkMapper interface. Playwright uses fixture-based
-   * callbacks with destructuring ({ page, browser }) while our interface uses a union type for
-   * Jest compatibility (done callback or fixture object). The functions are compatible at runtime
-   * but TypeScript cannot verify this due to these fundamental signature differences.
-   */
-
-  assertEqual: (a, b) => expect(a).toEqual(b),
-  assertNotEqual: (a, b) => expect(a).not.toEqual(b),
-  assertTrue: value => expect(value).toBe(true),
-  assertFalse: value => expect(value).toBe(false),
-  assertApproxEqual: (actual, expected, tolerance) =>
-    expect(Math.abs(actual - expected)).toBeLessThanOrEqual(tolerance),
-  // @ts-expect-error - Playwright describe signature differs from TestFrameworkMapper.Describe
-  describe: test.describe,
-
-  beforeEach: test.beforeEach,
-  afterEach: test.afterEach,
-  beforeAll: test.beforeAll,
-  afterAll: test.afterAll,
-
-  // @ts-expect-error - Playwright test signature differs from TestFrameworkMapper.Test
-  test: test,
-
-  // @ts-expect-error - Playwright test signature differs from TestFrameworkMapper.Test
-  it: test,
-};
-
-/**
- * Get a typed interface for running end-to-end tests with Playwright.
- */
-export function getTestRunnerInterface<T extends ScenePart>(): E2eTestInterface<T> {
-  return {
-    getTestEngine: playwrightGetTestEngine,
-    goto,
-  };
-}