@lullabot/playwright-testing 1.2.1 → 1.3.0

package/README.md

@@ -1,8 +1,8 @@
 # `@lullabot/playwright-testing`
 
 Framework-neutral utilities for stable Playwright screenshots, accessibility
-baselines, URL-driven visual comparisons, WebKit autofocus stabilization, and
-GitHub reporting.
+baselines, URL-driven visual comparisons, CKEditor 5 editing, WebKit autofocus
+stabilization, and GitHub reporting.
 
 This package is developed in the
 [`playwright-drupal` monorepo](https://github.com/Lullabot/playwright-drupal),
@@ -25,8 +25,9 @@ version.
 
 - `@lullabot/playwright-testing` exports screenshot stabilization,
   accessibility checks and baselines, visual-diff definitions, interaction and
-  pseudo-state helpers, reusable mocks, and the `suppressWebKitAutofocus()` init
-  script (installed explicitly in WebKit contexts).
+  pseudo-state helpers, `openAllDetails()`, CKEditor 5 editing, reusable mocks,
+  and the `suppressWebKitAutofocus()` init script (installed explicitly in WebKit
+  contexts).
 - `@lullabot/playwright-testing/github` exports the optional GitHub report,
   attachment-upload, and path-remapping APIs.
 - `playwright-testing-a11y-summary` and
@@ -51,6 +52,8 @@ test('home page', async ({ page }, testInfo) => {
 
 - [Accessibility testing][testing-accessibility]
 - [Stable screenshots and visual comparisons][testing-screenshots]
+- [Page readiness and browser state][testing-page-readiness]
+- [CKEditor 5 editing][testing-ckeditor5]
 - [WebKit native autofocus workaround][testing-webkit-autofocus]
 - [GitHub reporting][testing-github-reporting]
 
@@ -67,3 +70,7 @@ package.
 [testing-screenshots]: https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/screenshots-and-visual-comparisons.md
 [testing-github-reporting]: https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/github-reporting.md
 [testing-webkit-autofocus]: https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/webkit-autofocus.md
+
+[testing-page-readiness]: https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/page-readiness.md
+
+[testing-ckeditor5]: https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/ckeditor5.md

package/lib/ckeditor5.d.ts

@@ -0,0 +1,58 @@
+import { FrameLocator, Page } from "@playwright/test";
+/**
+ * Return the select-all modifier key for a given platform.
+ *
+ * Exported so unit tests can cover the platform branch without mocking
+ * `process.platform`. Defaults to the current platform.
+ */
+export declare function selectAllModifier(platform?: NodeJS.Platform): "Meta" | "Control";
+/**
+ * Drive a CKEditor **5** field from a Playwright test.
+ *
+ * This class is specifically for CKEditor 5. It does **not** work with
+ * CKEditor 4.
+ *
+ * CKEditor 5 keeps a virtual-DOM model that it synchronises with the visible
+ * contenteditable element. Setting the DOM directly (e.g. via Playwright's
+ * `locator.fill()`) can be silently dropped because the editor's next
+ * re-render overwrites it; it also bypasses any input handlers CKEditor
+ * plugins register. `fill()` here dispatches real keyboard events through
+ * `page.keyboard`, which CKEditor's event pipeline processes as normal
+ * edits.
+ *
+ * The `selector` targets the widget **wrapper** (e.g.
+ * `#body-editor` or `[data-testid="body-editor"]`),
+ * not the contenteditable itself — the class drills into
+ * `.ck-editor__editable` internally so callers don't have to memorise
+ * CKEditor 5's markup.
+ *
+ * For editors rendered inside an iframe, pass the `FrameLocator` as `root`
+ * while keeping `page` as the owning page so keyboard events still reach the
+ * right window.
+ */
+export declare class Ckeditor5 {
+    page: Page;
+    root: Page | FrameLocator;
+    protected selector: string;
+    /**
+     * @param page
+     *   The page the CKEditor 5 instance lives on. Keyboard events are sent to
+     *   this page.
+     * @param selector
+     *   A selector that resolves to the widget wrapper containing the editor
+     *   (e.g. `#body-editor`). The class finds the
+     *   `.ck-editor__editable` element inside.
+     * @param root
+     *   Optional frame locator if the editor is inside an iframe. Defaults to
+     *   `page`.
+     */
+    constructor(page: Page, selector: string, root?: Page | FrameLocator);
+    /**
+     * Replace the editor's contents with the given text.
+     *
+     * Clears existing content (select-all + Backspace) so the call has
+     * Playwright-style `fill()` semantics: the final value is exactly `text`,
+     * regardless of whether the field was empty.
+     */
+    fill(text: string): Promise<void>;
+}

package/lib/ckeditor5.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ckeditor5 = void 0;
+exports.selectAllModifier = selectAllModifier;
+/**
+ * Return the select-all modifier key for a given platform.
+ *
+ * Exported so unit tests can cover the platform branch without mocking
+ * `process.platform`. Defaults to the current platform.
+ */
+function selectAllModifier(platform = process.platform) {
+    return platform === "darwin" ? "Meta" : "Control";
+}
+/**
+ * Drive a CKEditor **5** field from a Playwright test.
+ *
+ * This class is specifically for CKEditor 5. It does **not** work with
+ * CKEditor 4.
+ *
+ * CKEditor 5 keeps a virtual-DOM model that it synchronises with the visible
+ * contenteditable element. Setting the DOM directly (e.g. via Playwright's
+ * `locator.fill()`) can be silently dropped because the editor's next
+ * re-render overwrites it; it also bypasses any input handlers CKEditor
+ * plugins register. `fill()` here dispatches real keyboard events through
+ * `page.keyboard`, which CKEditor's event pipeline processes as normal
+ * edits.
+ *
+ * The `selector` targets the widget **wrapper** (e.g.
+ * `#body-editor` or `[data-testid="body-editor"]`),
+ * not the contenteditable itself — the class drills into
+ * `.ck-editor__editable` internally so callers don't have to memorise
+ * CKEditor 5's markup.
+ *
+ * For editors rendered inside an iframe, pass the `FrameLocator` as `root`
+ * while keeping `page` as the owning page so keyboard events still reach the
+ * right window.
+ */
+class Ckeditor5 {
+    page;
+    root;
+    selector;
+    /**
+     * @param page
+     *   The page the CKEditor 5 instance lives on. Keyboard events are sent to
+     *   this page.
+     * @param selector
+     *   A selector that resolves to the widget wrapper containing the editor
+     *   (e.g. `#body-editor`). The class finds the
+     *   `.ck-editor__editable` element inside.
+     * @param root
+     *   Optional frame locator if the editor is inside an iframe. Defaults to
+     *   `page`.
+     */
+    constructor(page, selector, root) {
+        this.page = page;
+        this.selector = selector;
+        this.root = root ?? page;
+    }
+    /**
+     * Replace the editor's contents with the given text.
+     *
+     * Clears existing content (select-all + Backspace) so the call has
+     * Playwright-style `fill()` semantics: the final value is exactly `text`,
+     * regardless of whether the field was empty.
+     */
+    async fill(text) {
+        const editable = this.root
+            .locator(this.selector)
+            .locator(".ck-editor__editable");
+        await editable.waitFor({ state: "visible", timeout: 15000 });
+        // Click places the caret inside the editable so the keyboard events
+        // below land in CKEditor rather than the outer document.
+        await editable.click();
+        await this.page.keyboard.press(`${selectAllModifier()}+A`);
+        await this.page.keyboard.press("Backspace");
+        // keyboard.type fires keydown/keypress/input events that CKEditor 5's
+        // event pipeline processes. locator.fill() would set the DOM directly
+        // and can be silently dropped on the next model re-render.
+        await this.page.keyboard.type(text);
+    }
+}
+exports.Ckeditor5 = Ckeditor5;

package/lib/details.d.ts

@@ -0,0 +1,6 @@
+import { Page } from "@playwright/test";
+/**
+ * Expand every collapsed `<details>` element on the page so nested controls
+ * become interactable. Call after navigation and before filling nested fields.
+ */
+export declare function openAllDetails(page: Page): Promise<void>;

package/lib/details.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openAllDetails = openAllDetails;
+/**
+ * Expand every collapsed `<details>` element on the page so nested controls
+ * become interactable. Call after navigation and before filling nested fields.
+ */
+async function openAllDetails(page) {
+    await page.evaluate(() => {
+        document.querySelectorAll("details:not([open])").forEach((d) => {
+            d.open = true;
+        });
+    });
+}

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./details.js";
 export * from "./focus.js";
 export * from "./accessibility-baseline.js";
 export * from "./accessibility-baseline-file.js";
@@ -12,3 +13,4 @@ export * from "./videos.js";
 export * from "./visualdiff.js";
 export * from "./mock/index.js";
 export * from "./webkit-autofocus.js";
+export * from "./ckeditor5.js";

package/lib/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./details.js"), exports);
 __exportStar(require("./focus.js"), exports);
 __exportStar(require("./accessibility-baseline.js"), exports);
 __exportStar(require("./accessibility-baseline-file.js"), exports);
@@ -28,3 +29,4 @@ __exportStar(require("./videos.js"), exports);
 __exportStar(require("./visualdiff.js"), exports);
 __exportStar(require("./mock/index.js"), exports);
 __exportStar(require("./webkit-autofocus.js"), exports);
+__exportStar(require("./ckeditor5.js"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lullabot/playwright-testing",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Framework-neutral Playwright testing utilities",
   "license": "Apache-2.0",
   "repository": {

package/src/ckeditor5.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { selectAllModifier } from "./ckeditor5";
+
+describe("selectAllModifier", () => {
+  it("returns Meta on darwin", () => {
+    expect(selectAllModifier("darwin")).toBe("Meta");
+  });
+
+  it("returns Control on linux", () => {
+    expect(selectAllModifier("linux")).toBe("Control");
+  });
+
+  it("returns Control on win32", () => {
+    expect(selectAllModifier("win32")).toBe("Control");
+  });
+
+  it("returns Control on freebsd / other", () => {
+    expect(selectAllModifier("freebsd")).toBe("Control");
+  });
+});

package/src/ckeditor5.ts

@@ -0,0 +1,84 @@
+import { FrameLocator, Page } from "@playwright/test";
+
+/**
+ * Return the select-all modifier key for a given platform.
+ *
+ * Exported so unit tests can cover the platform branch without mocking
+ * `process.platform`. Defaults to the current platform.
+ */
+export function selectAllModifier(
+  platform: NodeJS.Platform = process.platform,
+): "Meta" | "Control" {
+  return platform === "darwin" ? "Meta" : "Control";
+}
+
+/**
+ * Drive a CKEditor **5** field from a Playwright test.
+ *
+ * This class is specifically for CKEditor 5. It does **not** work with
+ * CKEditor 4.
+ *
+ * CKEditor 5 keeps a virtual-DOM model that it synchronises with the visible
+ * contenteditable element. Setting the DOM directly (e.g. via Playwright's
+ * `locator.fill()`) can be silently dropped because the editor's next
+ * re-render overwrites it; it also bypasses any input handlers CKEditor
+ * plugins register. `fill()` here dispatches real keyboard events through
+ * `page.keyboard`, which CKEditor's event pipeline processes as normal
+ * edits.
+ *
+ * The `selector` targets the widget **wrapper** (e.g.
+ * `#body-editor` or `[data-testid="body-editor"]`),
+ * not the contenteditable itself — the class drills into
+ * `.ck-editor__editable` internally so callers don't have to memorise
+ * CKEditor 5's markup.
+ *
+ * For editors rendered inside an iframe, pass the `FrameLocator` as `root`
+ * while keeping `page` as the owning page so keyboard events still reach the
+ * right window.
+ */
+export class Ckeditor5 {
+  public page: Page;
+  public root: Page | FrameLocator;
+  protected selector: string;
+
+  /**
+   * @param page
+   *   The page the CKEditor 5 instance lives on. Keyboard events are sent to
+   *   this page.
+   * @param selector
+   *   A selector that resolves to the widget wrapper containing the editor
+   *   (e.g. `#body-editor`). The class finds the
+   *   `.ck-editor__editable` element inside.
+   * @param root
+   *   Optional frame locator if the editor is inside an iframe. Defaults to
+   *   `page`.
+   */
+  public constructor(page: Page, selector: string, root?: Page | FrameLocator) {
+    this.page = page;
+    this.selector = selector;
+    this.root = root ?? page;
+  }
+
+  /**
+   * Replace the editor's contents with the given text.
+   *
+   * Clears existing content (select-all + Backspace) so the call has
+   * Playwright-style `fill()` semantics: the final value is exactly `text`,
+   * regardless of whether the field was empty.
+   */
+  public async fill(text: string): Promise<void> {
+    const editable = this.root
+      .locator(this.selector)
+      .locator(".ck-editor__editable");
+    await editable.waitFor({ state: "visible", timeout: 15000 });
+    // Click places the caret inside the editable so the keyboard events
+    // below land in CKEditor rather than the outer document.
+    await editable.click();
+    await this.page.keyboard.press(`${selectAllModifier()}+A`);
+    await this.page.keyboard.press("Backspace");
+    // keyboard.type fires keydown/keypress/input events that CKEditor 5's
+    // event pipeline processes. locator.fill() would set the DOM directly
+    // and can be silently dropped on the next model re-render.
+    await this.page.keyboard.type(text);
+  }
+}

package/src/details.ts

@@ -0,0 +1,13 @@
+import { Page } from "@playwright/test";
+
+/**
+ * Expand every collapsed `<details>` element on the page so nested controls
+ * become interactable. Call after navigation and before filling nested fields.
+ */
+export async function openAllDetails(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    document.querySelectorAll("details:not([open])").forEach((d) => {
+      (d as HTMLDetailsElement).open = true;
+    });
+  });
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./details.js";
 export * from "./focus.js";
 export * from "./accessibility-baseline.js";
 export * from "./accessibility-baseline-file.js";
@@ -12,3 +13,4 @@ export * from "./videos.js";
 export * from "./visualdiff.js";
 export * from "./mock/index.js";
 export * from "./webkit-autofocus.js";
+export * from "./ckeditor5.js";