@lullabot/playwright-testing 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# `@lullabot/playwright-testing`
+
+Framework-neutral utilities for stable Playwright screenshots, accessibility
+baselines, URL-driven visual comparisons, and GitHub reporting.
+
+This package is developed in the
+[`playwright-drupal` monorepo](https://github.com/Lullabot/playwright-drupal),
+but it has no Drupal runtime assumptions. Drupal projects can instead install
+[`@lullabot/playwright-drupal`](https://www.npmjs.com/package/@lullabot/playwright-drupal),
+which applies Drupal-specific defaults and preserves the original API.
+
+## Install
+
+```console
+npm install --save-dev @lullabot/playwright-testing @playwright/test
+```
+
+`@axe-core/playwright` and `@playwright/test` are runtime dependencies of this
+package. Your project should still declare its own compatible
+`@playwright/test` dependency so the test runner and imported types use the same
+version.
+
+## Package entry points
+
+- `@lullabot/playwright-testing` exports screenshot stabilization,
+  accessibility checks and baselines, visual-diff definitions, interaction and
+  pseudo-state helpers, and reusable mocks.
+- `@lullabot/playwright-testing/github` exports the optional GitHub report,
+  attachment-upload, and path-remapping APIs.
+- `playwright-testing-a11y-summary` and
+  `playwright-testing-failure-summary` expose the reporting commands.
+
+The package does not replace Playwright's `test` fixture. Import `test`,
+`expect`, and `testInfo` from `@playwright/test`, then pass the page and test
+metadata to the helpers:
+
+```typescript
+import { expect, test } from '@playwright/test';
+import { takeAccessibleScreenshot } from '@lullabot/playwright-testing';
+
+test('home page', async ({ page }, testInfo) => {
+  await page.goto('/');
+  await takeAccessibleScreenshot(page, testInfo, { fullPage: true });
+  await expect(page).toHaveTitle(/Example/);
+});
+```
+
+## Guides
+
+- [Accessibility testing](https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/accessibility.md)
+- [Stable screenshots and visual comparisons](https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/screenshots-and-visual-comparisons.md)
+- [GitHub reporting](https://github.com/Lullabot/playwright-drupal/blob/main/packages/playwright-testing/docs/github-reporting.md)
+
+## Drupal compatibility
+
+Existing `@lullabot/playwright-drupal` imports remain supported. That package
+depends on this one, re-exports the generic APIs, and wraps screenshot and
+visual-diff calls with its Drupal preset. New framework-neutral code can import
+this package directly; Drupal tests that depend on database isolation, Drush,
+login helpers, or the `a11y` fixture should continue importing the Drupal
+package.

package/bin/github-a11y-summary

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { main } = require('../lib/github/a11y-summary.js')
+
+main()

package/bin/github-failure-summary

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { main } = require('../lib/github/failure-summary.js')
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/lib/accessibility-baseline-file.d.ts

@@ -0,0 +1,47 @@
+import type { TestInfo } from '@playwright/test';
+import type { AccessibilityBaselineEntry } from './accessibility-baseline.js';
+export type ScanKind = 'wcag' | 'best-practice';
+export interface OnDiskBaselineFile {
+    note: string;
+    violations: AccessibilityBaselineEntry[];
+}
+/**
+ * Increment and return the 1-indexed invocation number for this scan kind
+ * within the current test. Every call to `checkAccessibility()` runs up to
+ * two scans (WCAG + best-practice); each scan gets its own counter so that
+ * a test calling `checkAccessibility()` twice produces distinct baseline
+ * file names (`…-1.a11y-baseline.json`, `…-2.a11y-baseline.json`) even when
+ * both scans share a single `checkAccessibility()` call.
+ *
+ * Counter state is keyed by the TestInfo object (held in a WeakMap so it
+ * is discarded with the test). Use `resetAccessibilityScanCounts()` to
+ * clear state explicitly — for example, between tests in a unit-test
+ * suite that reuses a mocked TestInfo.
+ */
+export declare function nextAccessibilityScanCount(testInfo: Pick<TestInfo, 'testId'> | object, scan: ScanKind): number;
+export declare function resetAccessibilityScanCounts(testInfo: object): void;
+/**
+ * Build the on-disk baseline file path for a single scan call.
+ *
+ * Playwright exposes `testInfo.snapshotPath(...name)` as the public way to
+ * resolve a file under the test's snapshots directory (honoring any
+ * user-configured `snapshotPathTemplate`). We pass a filename that mixes
+ * the slugified test title + call counter + a scan-specific suffix, so two
+ * different tests in the same spec file don't collide and each scan has
+ * its own file.
+ *
+ * There is no reusable Playwright API that bakes the test title into an
+ * explicit-name snapshot path — that logic is private to `toMatchSnapshot()`
+ * for its auto-counter naming — so we build the stem ourselves.
+ */
+export declare function baselineFilePath(testInfo: Pick<TestInfo, 'snapshotPath' | 'titlePath' | 'title'>, scan: ScanKind, callCount: number): string;
+/**
+ * Return true if a Playwright snapshot file already exists on disk for
+ * this test — i.e. the test has been previously committed under snapshot
+ * mode. Used to preserve snapshot-mode behaviour for existing tests while
+ * defaulting new (snapshotless) tests into on-disk baseline mode.
+ */
+export declare function snapshotExists(testInfo: Pick<TestInfo, 'snapshotPath' | 'titlePath' | 'title'>): Promise<boolean>;
+export declare function readBaselineFile(filePath: string): Promise<OnDiskBaselineFile | null>;
+export declare function writeBaselineFile(filePath: string, data: OnDiskBaselineFile): Promise<void>;
+export declare function buildSeed(violations: AccessibilityBaselineEntry[]): OnDiskBaselineFile;

package/lib/accessibility-baseline-file.js

@@ -0,0 +1,205 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextAccessibilityScanCount = nextAccessibilityScanCount;
+exports.resetAccessibilityScanCounts = resetAccessibilityScanCounts;
+exports.baselineFilePath = baselineFilePath;
+exports.snapshotExists = snapshotExists;
+exports.readBaselineFile = readBaselineFile;
+exports.writeBaselineFile = writeBaselineFile;
+exports.buildSeed = buildSeed;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const scanInvocationCounters = new WeakMap();
+/**
+ * Increment and return the 1-indexed invocation number for this scan kind
+ * within the current test. Every call to `checkAccessibility()` runs up to
+ * two scans (WCAG + best-practice); each scan gets its own counter so that
+ * a test calling `checkAccessibility()` twice produces distinct baseline
+ * file names (`…-1.a11y-baseline.json`, `…-2.a11y-baseline.json`) even when
+ * both scans share a single `checkAccessibility()` call.
+ *
+ * Counter state is keyed by the TestInfo object (held in a WeakMap so it
+ * is discarded with the test). Use `resetAccessibilityScanCounts()` to
+ * clear state explicitly — for example, between tests in a unit-test
+ * suite that reuses a mocked TestInfo.
+ */
+function nextAccessibilityScanCount(testInfo, scan) {
+    const key = testInfo;
+    let counts = scanInvocationCounters.get(key);
+    if (!counts) {
+        counts = new Map();
+        scanInvocationCounters.set(key, counts);
+    }
+    const n = (counts.get(scan) ?? 0) + 1;
+    counts.set(scan, n);
+    return n;
+}
+function resetAccessibilityScanCounts(testInfo) {
+    scanInvocationCounters.delete(testInfo);
+}
+/**
+ * Slugify a test's fully qualified title the same way we use it as the
+ * stem of both on-disk baseline filenames and (for existence checks) the
+ * prefix of Playwright's auto-generated snapshot filenames.
+ *
+ * Implemented as a single-pass character scan to avoid regex-based
+ * polynomial backtracking on library-supplied input (CodeQL
+ * js/polynomial-redos).
+ */
+function slugifyTitle(testInfo) {
+    const segments = testInfo.titlePath?.slice(1) ?? [];
+    const raw = segments.length > 0 ? segments.join(' ') : testInfo.title;
+    let out = '';
+    let lastWasHyphen = true; // suppresses leading hyphen
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        const isLowerAlpha = code >= 97 && code <= 122; // a-z
+        const isUpperAlpha = code >= 65 && code <= 90; // A-Z
+        const isDigit = code >= 48 && code <= 57; // 0-9
+        if (isLowerAlpha || isDigit) {
+            out += raw[i];
+            lastWasHyphen = false;
+        }
+        else if (isUpperAlpha) {
+            out += String.fromCharCode(code + 32);
+            lastWasHyphen = false;
+        }
+        else if (!lastWasHyphen) {
+            out += '-';
+            lastWasHyphen = true;
+        }
+    }
+    // Trim trailing hyphen.
+    if (out.endsWith('-'))
+        out = out.slice(0, -1);
+    return out;
+}
+/**
+ * Reproduce the stem Playwright uses for auto-named snapshot files: the
+ * title path (minus the spec file) joined with spaces, with every run of
+ * control/punctuation characters collapsed to a single hyphen. Unlike
+ * `slugifyTitle()` this preserves case and does not trim hyphens, so it
+ * matches committed snapshot filenames exactly. Mirrors Playwright's
+ * `sanitizeForFilePath()`. Very long titles, which Playwright truncates
+ * and hashes, are not handled.
+ */
+function playwrightSnapshotStem(testInfo) {
+    const segments = testInfo.titlePath?.slice(1) ?? [];
+    const raw = segments.length > 0 ? segments.join(' ') : testInfo.title;
+    let out = '';
+    let lastWasReplaced = false;
+    for (let i = 0; i < raw.length; i++) {
+        const code = raw.charCodeAt(i);
+        const replaced = code <= 0x2c ||
+            (code >= 0x2e && code <= 0x2f) ||
+            (code >= 0x3a && code <= 0x40) ||
+            (code >= 0x5b && code <= 0x60) ||
+            (code >= 0x7b && code <= 0x7f);
+        if (replaced) {
+            if (!lastWasReplaced)
+                out += '-';
+            lastWasReplaced = true;
+        }
+        else {
+            out += raw[i];
+            lastWasReplaced = false;
+        }
+    }
+    return out;
+}
+/**
+ * Build the on-disk baseline file path for a single scan call.
+ *
+ * Playwright exposes `testInfo.snapshotPath(...name)` as the public way to
+ * resolve a file under the test's snapshots directory (honoring any
+ * user-configured `snapshotPathTemplate`). We pass a filename that mixes
+ * the slugified test title + call counter + a scan-specific suffix, so two
+ * different tests in the same spec file don't collide and each scan has
+ * its own file.
+ *
+ * There is no reusable Playwright API that bakes the test title into an
+ * explicit-name snapshot path — that logic is private to `toMatchSnapshot()`
+ * for its auto-counter naming — so we build the stem ourselves.
+ */
+function baselineFilePath(testInfo, scan, callCount) {
+    const slug = slugifyTitle(testInfo);
+    const suffix = scan === 'wcag' ? 'a11y-baseline' : 'a11y-baseline-best-practice';
+    return testInfo.snapshotPath(`${slug}-${callCount}.${suffix}.json`);
+}
+/**
+ * Return true if a Playwright snapshot file already exists on disk for
+ * this test — i.e. the test has been previously committed under snapshot
+ * mode. Used to preserve snapshot-mode behaviour for existing tests while
+ * defaulting new (snapshotless) tests into on-disk baseline mode.
+ */
+async function snapshotExists(testInfo) {
+    const dir = path_1.default.dirname(testInfo.snapshotPath('a11y-baseline-probe'));
+    let entries;
+    try {
+        entries = await fs_1.promises.readdir(dir);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    // Playwright names snapshots `<stem>-<counter>[-<project>-<platform>].txt`.
+    // Require the counter so a title that merely extends this one (e.g.
+    // "Video" vs "Video Promo") is not mistaken for this test's snapshot.
+    const prefix = `${playwrightSnapshotStem(testInfo)}-`;
+    return entries.some(name => {
+        if (!name.startsWith(prefix) || !name.endsWith('.txt'))
+            return false;
+        let i = prefix.length;
+        while (i < name.length && name.charCodeAt(i) >= 48 && name.charCodeAt(i) <= 57)
+            i++;
+        return i > prefix.length && (name[i] === '-' || name[i] === '.');
+    });
+}
+async function readBaselineFile(filePath) {
+    let raw;
+    try {
+        raw = await fs_1.promises.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.violations)) {
+            throw new Error('expected an object with a "violations" array');
+        }
+        return {
+            note: typeof parsed.note === 'string' ? parsed.note : '',
+            violations: parsed.violations,
+        };
+    }
+    catch (err) {
+        throw new Error(`Malformed baseline file at ${filePath}: ${err.message}`);
+    }
+}
+async function writeBaselineFile(filePath, data) {
+    await fs_1.promises.mkdir(path_1.default.dirname(filePath), { recursive: true });
+    try {
+        await fs_1.promises.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', { flag: 'wx' });
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST')
+            return;
+        throw err;
+    }
+}
+function buildSeed(violations) {
+    if (violations.length === 0) {
+        return { note: 'No accessibility violations found', violations: [] };
+    }
+    return {
+        note: 'TODO: fill in reason and willBeFixedIn for each entry before committing.',
+        violations,
+    };
+}

package/lib/accessibility-baseline.d.ts

@@ -0,0 +1,19 @@
+export interface AccessibilityBaselineEntry {
+    /** axe rule ID (e.g. 'color-contrast') */
+    rule: string;
+    /** CSS selectors for the elements with this violation */
+    targets: string[];
+    /** Why this violation is accepted */
+    reason: string;
+    /** Link to tracking ticket */
+    willBeFixedIn: string;
+}
+export type AccessibilityBaseline = AccessibilityBaselineEntry[];
+export declare function defineAccessibilityBaseline(entries: AccessibilityBaseline): AccessibilityBaseline;
+/**
+ * Validate waiver metadata and reject ambiguous duplicate entries.
+ *
+ * Seed files deliberately contain TODO placeholders, so callers validate only
+ * committed/in-code baselines, not a seed during the local creation run.
+ */
+export declare function validateAccessibilityBaseline(entries: AccessibilityBaseline): void;

package/lib/accessibility-baseline.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAccessibilityBaseline = defineAccessibilityBaseline;
+exports.validateAccessibilityBaseline = validateAccessibilityBaseline;
+function defineAccessibilityBaseline(entries) {
+    validateAccessibilityBaseline(entries);
+    return entries;
+}
+/**
+ * Validate waiver metadata and reject ambiguous duplicate entries.
+ *
+ * Seed files deliberately contain TODO placeholders, so callers validate only
+ * committed/in-code baselines, not a seed during the local creation run.
+ */
+function validateAccessibilityBaseline(entries) {
+    const seen = new Set();
+    entries.forEach((entry, index) => {
+        if (!entry.rule.trim()) {
+            throw new Error(`Accessibility baseline entry ${index + 1} requires a rule.`);
+        }
+        if (entry.targets.length === 0 || entry.targets.some(target => !target.trim())) {
+            throw new Error(`Accessibility baseline entry ${index + 1} requires at least one non-empty target.`);
+        }
+        if (!entry.reason.trim() || entry.reason.trim().toUpperCase() === 'TODO') {
+            throw new Error(`Accessibility baseline entry ${index + 1} requires a reason.`);
+        }
+        if (!entry.willBeFixedIn.trim() || entry.willBeFixedIn.trim().toUpperCase() === 'TODO') {
+            throw new Error(`Accessibility baseline entry ${index + 1} requires a willBeFixedIn tracking reference.`);
+        }
+        for (const target of new Set(entry.targets)) {
+            const key = JSON.stringify([entry.rule, target]);
+            if (seen.has(key)) {
+                throw new Error(`Accessibility baseline contains a duplicate waiver for ${entry.rule} on ${target}.`);
+            }
+            seen.add(key);
+        }
+    });
+}

package/lib/accessible-screenshot.d.ts

@@ -0,0 +1,181 @@
+import { type Locator, type Page, type TestInfo } from "@playwright/test";
+import { type WaitForImagesOptions } from "./images.js";
+import { type WaitForVideosOptions } from "./videos.js";
+import { type ScreenshotInteractionState } from './interaction-states.js';
+import { type AccessibilityBaseline } from './accessibility-baseline.js';
+export type { InteractionState, ScreenshotInteractionState } from './interaction-states.js';
+export interface ScreenshotStabilizationOptions {
+    images?: WaitForImagesOptions;
+    videos?: WaitForVideosOptions;
+}
+export interface ScreenshotOptions {
+    /**
+     * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different
+     * treatment depending on their duration:
+     * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event.
+     * - infinite animations are canceled to initial state, and then played over after the screenshot.
+     *
+     * Defaults to `"disabled"` that disables animations.
+     */
+    animations?: "disabled" | "allow";
+    /**
+     * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be
+     * changed.  Defaults to `"hide"`.
+     */
+    caret?: "hide" | "initial";
+    /**
+     * When `true` (the default), blurs the active element before capturing so a
+     * stray focus ring left over from earlier test interactions does not appear in
+     * only some runs (an invisible-to-a-human diff that still trips the pixel
+     * budget). Set to `false` when the screenshot intentionally captures a focused
+     * state.
+     */
+    blur?: boolean;
+    /**
+     * When `true` (the default), moves the pointer onto a temporary transparent
+     * shield before capturing so stale pointer activity does not leave an
+     * unrelated element in its hover state. Set to `false` when the screenshot
+     * intentionally captures a hovered state.
+     */
+    clearHover?: boolean;
+    /**
+     * Real hover and focus states to apply after the page has settled. These are
+     * supported in Chromium, Firefox, and WebKit and remain active through both
+     * the screenshot and accessibility scan. At most one locator may receive
+     * each state, matching what a real pointer and keyboard can do.
+     */
+    interactionStates?: ScreenshotInteractionState[];
+    /** Configuration for image and video settling. */
+    stabilization?: ScreenshotStabilizationOptions;
+    /**
+     * An object specifying the page area to capture, in CSS pixels.
+     */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to
+     * `false`.
+     */
+    fullPage?: boolean;
+    /**
+     * Derive a page screenshot clip from this locator after readiness waits and
+     * scrolling. Round x, y, width and height to integer CSS pixels without
+     * modifying rendering. Mutually exclusive with clip and a locator target.
+     * Use fullPage for targets larger than the viewport.
+     */
+    clipLocator?: Locator;
+    /**
+     * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink
+     * box `#FF00FF` (customized by `maskColor`) that completely covers its bounding box.
+     */
+    mask?: Array<Locator>;
+    /**
+     * Specify the color of the overlay box for masked elements, in
+     * [CSS color format](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default color is pink `#FF00FF`.
+     */
+    maskColor?: string;
+    /**
+     * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is
+     * configurable with `TestConfig.expect`. Unset by default.
+     */
+    maxDiffPixelRatio?: number;
+    /**
+     * An acceptable amount of pixels that could be different. Default is configurable with `TestConfig.expect`. Unset by
+     * default.
+     */
+    maxDiffPixels?: number;
+    /**
+     * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
+     * Defaults to `false`.
+     */
+    omitBackground?: boolean;
+    /**
+     * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this
+     * will keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so
+     * screenshots of high-dpi devices will be twice as large or even larger.
+     *
+     * Defaults to `"css"`.
+     */
+    scale?: "css" | "device";
+    /**
+     * A stylesheet, or list of stylesheets, to apply while taking the screenshot.
+     * The styles pierce Shadow DOM and apply to inner frames.
+     */
+    stylePath?: string | string[];
+    /**
+     * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
+     * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+     * `TestConfig.expect`. Defaults to `0.2`.
+     */
+    threshold?: number;
+    /**
+     * Time to retry the assertion for in milliseconds. Defaults to `timeout` in `TestConfig.expect`.
+     */
+    timeout?: number;
+    /**
+     * Accessibility options passed through to checkAccessibility().
+     */
+    accessibility?: AccessibilityOptions;
+}
+export interface AccessibilityOptions {
+    /** axe tags for WCAG scan. Default: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] */
+    wcagTags?: string[];
+    /** Additional CSS selectors to exclude from both scans. */
+    exclude?: string[];
+    /** CSS selectors to exclude only from the best-practice scan. */
+    bestPracticeExclude?: string[];
+    /** CSS selectors to exclude only from the WCAG scan. */
+    wcagExclude?: string[];
+    /**
+     * Best-practice scan mode.
+     * - 'soft': uses expect.soft() (default, current behaviour)
+     * - 'hard': uses expect() — test fails immediately on violations
+     * - 'off': skips best-practice scan entirely
+     */
+    bestPracticeMode?: 'soft' | 'hard' | 'off';
+    /** Additional axe rules to enable/disable. */
+    rules?: Record<string, {
+        enabled: boolean;
+    }>;
+    /** Baseline of known violations. When provided, violations matching the baseline are suppressed and toMatchSnapshot() is skipped. */
+    baseline?: AccessibilityBaseline;
+    /**
+     * When true, captures a full-page screenshot with violating elements
+     * highlighted (red outline) and attaches it to the test report.
+     * Default: true.
+     */
+    screenshotViolations?: boolean;
+}
+/**
+ * Run accessibility checks on the current page using axe-core.
+ *
+ * Runs a best-practice scan (unless bestPracticeMode is 'off') and a WCAG scan,
+ * attaching JSON results and asserting on violations via snapshots.
+ *
+ * @param page The Page fixture from the test.
+ * @param testInfo The testInfo object from the test.
+ * @param options Accessibility options to customise the scan.
+ */
+export declare function checkAccessibility(page: Page, testInfo: TestInfo, options?: AccessibilityOptions): Promise<void>;
+/**
+ * Take a visual comparison, and also ensure there's no accessibility issues.
+ *
+ * @param page The Page fixture from the test.
+ * @param testInfo The testInfo object from the test.
+ * @param options Screenshot options from toHaveScreenshot().
+ * @param scrollLocator A locator to ensure is visible before taking the screenshot.
+ * @param locator A specific locator to take the screenshot of. aXe still checks the whole page.
+ */
+export declare function takeAccessibleScreenshot(page: Page, testInfo: TestInfo, options?: ScreenshotOptions, scrollLocator?: Locator, locator?: Locator | Page): Promise<void>;
+/**
+ * Normalize a single CSS selector target for stable comparison.
+ *
+ * Replaces unique numeric HTML IDs and aria-labelledby suffixes with
+ * a stable placeholder so that snapshots and baseline matching are
+ * deterministic across runs.
+ */
+export declare function normalizeTarget(target: string | string[]): string | string[];