@owlmeans/test-ui 0.1.18-rc.47 → 0.1.18-rc.49

package/build/mount.d.ts

@@ -1,42 +1,4 @@
-import type { Page } from 'playwright';
-export interface MountOptions {
-    /**
-     * URL the harness is reachable at. The consuming package is in charge
-     * of producing it — typically a Vite dev server pointed at
-     * `node_modules/@owlmeans/test-ui/harness/` plus a per-package
-     * `mount.tsx` that registers the components under test, OR an
-     * inlined `data:text/html,...` URL for the simplest smoke tests.
-     */
-    url: string;
-    /**
-     * Component name registered in the harness. Appended as `?component=`.
-     * Omit when the harness mounts a single fixed root.
-     */
-    component?: string;
-    /**
-     * JSON-serialisable props passed to the component. Encoded into the
-     * URL as `?props=<json>` for the harness's `mount.tsx` to read.
-     */
-    props?: Record<string, unknown>;
-    /**
-     * What counts as "arrived". Defaults to `domcontentloaded`.
-     *
-     * NOT `load`, which is playwright's own default and is wrong for any page that is a real
-     * application: `load` waits for EVERY subresource, and an analytics beacon, a long-poll or a
-     * third-party pixel that never settles holds it open until the navigation times out — with the
-     * page fully rendered and working the whole time. The failure reads as "the site is down".
-     *
-     * A spec waits for the selector it actually needs; that is the assertion, not the load event.
-     */
-    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
-    /** Navigation timeout in ms. */
-    timeout?: number;
-}
-export interface Mounted {
-    page: Page;
-    /** Closes the page's browser context — the shared browser stays alive. */
-    close: () => Promise<void>;
-}
+import type { Mounted, MountOptions } from './types.js';
 /**
  * Open a fresh browser context, navigate to the harness URL with the
  * `component` and `props` query parameters set, and return the `Page`
@@ -47,7 +9,7 @@ export interface Mounted {
  *     try { expect(await page.locator('h1').textContent()).toBe('Sign in') }
  *     finally { await close() }
  *
- * `closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
+ * `browserHelper.closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
  */
 export declare const mountComponent: (opts: MountOptions) => Promise<Mounted>;
 //# sourceMappingURL=mount.d.ts.map

package/build/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAGtC,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,MAAM,GAAG,aAAa,CAAA;IAClE,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,0EAA0E;IAC1E,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAYD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,SAAgB,YAAY,KAAG,OAAO,CAAC,OAAO,CAYxE,CAAA"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAYvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,SAAgB,YAAY,KAAG,OAAO,CAAC,OAAO,CAYxE,CAAA"}

package/build/mount.js

@@ -1,4 +1,4 @@
-import { launchBrowser } from './browser.js';
+import { browserHelper } from './browser.js';
 const buildUrl = (opts) => {
     const params = new URLSearchParams();
     if (opts.component != null)
@@ -21,10 +21,10 @@ const buildUrl = (opts) => {
  *     try { expect(await page.locator('h1').textContent()).toBe('Sign in') }
  *     finally { await close() }
  *
- * `closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
+ * `browserHelper.closeBrowser()` from `afterAll` tears down the shared browser at the end of the suite.
  */
 export const mountComponent = async (opts) => {
-    const browser = await launchBrowser();
+    const browser = await browserHelper.launchBrowser();
     const context = await browser.newContext();
     const page = await context.newPage();
     await page.goto(buildUrl(opts), {

package/build/mount.js.map

@@ -1 +1 @@
-{"version":3,"file":"mount.js","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AA0C5C,MAAM,QAAQ,GAAG,CAAC,IAAkB,EAAU,EAAE;IAC9C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACnE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC5B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,GAAG,CAAA;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;IAC9C,OAAO,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,EAAE,EAAE,CAAA;AACjC,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,IAAkB,EAAoB,EAAE;IAC3E,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IACpC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QAC9B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,kBAAkB;QAC/C,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC,CAAA;IACF,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA,CAAC,CAAC;KAC7C,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../src/mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAG5C,MAAM,QAAQ,GAAG,CAAC,IAAkB,EAAU,EAAE;IAC9C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IACnE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC5B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,GAAG,CAAA;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;IAC9C,OAAO,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,EAAE,EAAE,CAAA;AACjC,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,IAAkB,EAAoB,EAAE;IAC3E,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,aAAa,EAAE,CAAA;IACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IACpC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;QAC9B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,kBAAkB;QAC/C,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC,CAAA;IACF,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA,CAAC,CAAC;KAC7C,CAAA;AACH,CAAC,CAAA"}

package/build/page/types.d.ts

@@ -0,0 +1,134 @@
+export interface AnswerMarketingConsentOptions {
+    /**
+     * Which choice to save when the step is shown. `'all'` (the default) ticks the "select all"
+     * checkbox (every consent, and the Terms row while it is up — see {@link terms} for what is left
+     * of that) before saving; `'none'` saves with every item left unchecked, which is a valid,
+     * fully-compliant state on its own; `'skip'` clicks "Skip for now" instead of saving anything —
+     * only valid when a Terms box is not on screen (nothing calls it there; see {@link terms}).
+     */
+    accept?: 'none' | 'all' | 'skip';
+    /**
+     * When a Terms row is on screen (`appendMarketingConsent({ terms: 'step' })`), `'accept'` (the
+     * default) ends with it ticked. `'leave'` ends with it unticked, even after a select-all — for a
+     * spec that means to drive the blocked state itself; the confirm click below still fires (with `{ force: true }`, since
+     * the control is never truly `disabled`), and this helper then EXPECTS the box to still be up
+     * afterward rather than treating that as a failure.
+     */
+    terms?: 'accept' | 'leave';
+    timeout?: number;
+}
+/** What {@link PageHelper.acceptConsent} waits for. */
+export interface AcceptConsentOptions {
+    /** How long the dialog may take to appear, and then to go away. Defaults to 5s. */
+    timeout?: number;
+}
+export interface DispatcherLoginOptions {
+    dispatcherPath?: string;
+    /** What counts as "arrived" for the navigation. Defaults to `domcontentloaded` — see `MountOptions.waitUntil`. */
+    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
+    /**
+     * Answer the marketing-consent step if it is shown right after the dispatcher navigates away.
+     * Defaults to `'save'` (select-all and save) — see {@link PageHelper.answerMarketingConsent}. Pass
+     * `'ignore'` to skip the call entirely, e.g. in a spec that answers the step itself.
+     */
+    marketingConsent?: 'save' | 'ignore';
+}
+export interface SupervisorFormLoginOptions {
+    baseUrl: string;
+    /** Target user id / email. */
+    userId: string;
+    /** Supervisor private key (e.g. `ed25519:<base64>` from `.env.dev.secrets`). */
+    pk: string;
+    /** Login path; defaults to the standard supervisor route. */
+    path?: string;
+    /** Predicate/URL fragment that signals a successful landing (default: leaving the login path). */
+    expectPath?: string;
+    timeout?: number;
+    /**
+     * What counts as "arrived" for the initial navigation. Defaults to `domcontentloaded`.
+     *
+     * See the note on `MountOptions.waitUntil`: `load` is playwright's default and is wrong for a
+     * real application, because it waits for every subresource — a tag manager, an analytics beacon
+     * or any pixel that never settles holds it open until the navigation times out, with the login
+     * form rendered and fillable the whole time.
+     */
+    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
+    /**
+     * What to do about a cookie-consent dialog covering the form. Defaults to `accept`, because an
+     * OwlMeans app will not start an authentication flow until consent is answered — see
+     * {@link PageHelper.acceptConsent}. Pass `ignore` only in a spec that answers the dialog itself.
+     */
+    consent?: 'accept' | 'ignore';
+    /** When set, capture the filled login form (`supervisor-login-form.png`) before submit. */
+    screenshotDir?: string;
+    /**
+     * Answer the marketing-consent step if it is shown right after landing. Defaults to `'save'`
+     * (select-all and save) — see {@link PageHelper.answerMarketingConsent}. Pass `'ignore'` to skip the call
+     * entirely, e.g. in a spec that answers the step itself.
+     */
+    marketingConsent?: 'save' | 'ignore';
+}
+/** Driving one page of an OwlMeans app: consent dialogs, the login flows, screenshots. */
+export interface PageHelper {
+    /**
+     * Answer the marketing-consent full-page step (`@owlmeans/web-marketing-consent`) if it is shown
+     * right after login, so a spec driving {@link PageHelper.loginViaSupervisorForm} or
+     * {@link PageHelper.loginViaDispatcher} is never blocked behind it.
+     *
+     * The screen is opt-in per app, and most apps/environments will not have it wired in — that makes
+     * detecting its ABSENCE cheaply the whole point. A plain `waitFor` on `[data-marketing-consent]`
+     * alone would cost the full `timeout` on every login of every app that never renders it (the same
+     * caveat `acceptConsent` documents for the cookie dialog). Instead this races the step's own root
+     * against the generic OwlMeans "the app has already landed" / "still on the login screen" markers
+     * this helper's own login flows already wait on (`#app-prompt`, `[data-login-method]`) — by the
+     * time a login flow calls this, one of those has typically already rendered, so the race resolves
+     * as soon as it does: no fixed sleep, and in the common "step absent" case, no material added
+     * latency over what the login flow already paid to get here.
+     *
+     * @returns whether the step was actually shown and answered (including the error/skip fallback);
+     * `false` when it never appeared within `timeout`, which is the expected result everywhere
+     * the screen is not yet configured or the visitor already has saved consents.
+     * @throws if a Terms box could not be confirmed (a `[data-marketing-consent-terms-error]`, or the
+     * box is still up with nowhere left to go — Skip is never offered there on purpose).
+     */
+    answerMarketingConsent: (opts?: AnswerMarketingConsentOptions) => Promise<boolean>;
+    /**
+     * Inject a pre-generated bearer into an app that uses the standard owlmeans
+     * dispatcher: navigate to `/dispatcher?token=...` so the web app authenticates
+     * and redirects home natively. Note: apps that override the DISPATCHER route
+     * (e.g. to force an external IdP) should use {@link PageHelper.loginViaSupervisorForm}.
+     */
+    loginViaDispatcher: (baseUrl: string, token: string, opts?: DispatcherLoginOptions) => Promise<void>;
+    /**
+     * Save a full-page screenshot to `<dir>/<name>.png`, creating `dir` if needed.
+     * Returns the absolute file path. Use a host-backed folder (e.g. the project's
+     * `tmp/tests/screenshots`) so the file is visible whether the test runs on the
+     * host or inside a dev container.
+     */
+    saveScreenshot: (dir: string, name: string) => Promise<string>;
+    /**
+     * Answer the cookie-consent dialog if one is up, so the page underneath can be driven.
+     *
+     * An OwlMeans app asks for consent BEFORE it will start an authentication flow, and the dialog is
+     * a modal with no dismissal — by design, since a decision is what the gate is waiting for. For a
+     * test that means the login form renders, resolves, reports itself "visible, enabled and stable"
+     * and still cannot be clicked, because the overlay intercepts the pointer. Playwright retries for
+     * the full timeout and then blames the button, which is the most misleading failure in this
+     * helper: nothing is wrong with the form.
+     *
+     * Accepting is the honest default for a login helper — the flow it is about to drive is exactly
+     * what the dialog is gating — but it is best-effort: an app without the widget, or one where the
+     * visitor already decided, simply has no dialog and this returns at once.
+     *
+     * @returns whether a dialog was actually answered.
+     */
+    acceptConsent: (opts?: AcceptConsentOptions) => Promise<boolean>;
+    /**
+     * Drive the PK-based supervisor login FORM end-to-end (the faithful path that
+     * exercises the real supervisor plugin + registration): navigate to the
+     * supervisor login route, fill the user id + private key, submit, and wait for
+     * the app to leave the login screen.
+     */
+    loginViaSupervisorForm: (opts: SupervisorFormLoginOptions) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/page/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/page/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,6BAA6B;IAC5C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;IAChC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kHAAkH;IAClH,SAAS,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,MAAM,GAAG,aAAa,CAAA;IAClE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAA;IACV,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,kBAAkB,GAAG,MAAM,GAAG,aAAa,CAAA;IAClE;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC7B,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;CACrC;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAAsB,EAAE,CAAC,IAAI,CAAC,EAAE,6BAA6B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAClF;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpG;;;;;OAKG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D;;;;;;;;;;;;;;;OAeG;IACH,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAChE;;;;;OAKG;IACH,sBAAsB,EAAE,CAAC,IAAI,EAAE,0BAA0B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5E"}

package/build/page/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/page/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/page/types.ts"],"names":[],"mappings":""}

package/build/page.d.ts

@@ -0,0 +1,4 @@
+import type { Page } from 'playwright';
+import type { PageHelper } from './page/types.js';
+export declare const makePageHelper: (page: Page) => PageHelper;
+//# sourceMappingURL=page.d.ts.map

package/build/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,OAAO,KAAK,EACmE,UAAU,EACxF,MAAM,iBAAiB,CAAA;AAExB,eAAO,MAAM,cAAc,SAAU,IAAI,KAAG,UA+K3C,CAAA"}

package/build/page.js

@@ -0,0 +1,160 @@
+import { mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { DEFAULT_MARKETING_CONSENT_TIMEOUT, DEFAULT_SUPERVISOR_PATH } from './consts.local.js';
+export const makePageHelper = (page) => {
+    const answerMarketingConsent = async (opts) => {
+        const timeout = opts?.timeout ?? DEFAULT_MARKETING_CONSENT_TIMEOUT;
+        const step = page.locator('[data-marketing-consent]');
+        try {
+            await page.locator('[data-marketing-consent], #app-prompt, [data-login-method]')
+                .first().waitFor({ state: 'visible', timeout });
+        }
+        catch {
+            return false;
+        }
+        if (await step.count() === 0)
+            return false;
+        // The step's own status read may still be outstanding (`data-state="loading"`) — wait past it,
+        // OR notice it already auto-continued (nothing was pending) and detached on its own. An older
+        // `web-marketing-consent` that predates `data-state` entirely satisfies the first selector
+        // immediately (a missing attribute is never `"loading"`), so this costs nothing there.
+        await Promise.race([
+            page.waitForSelector('[data-marketing-consent]:not([data-state="loading"])', { timeout }),
+            page.waitForSelector('[data-marketing-consent]', { state: 'detached', timeout }),
+        ]).catch(() => undefined);
+        // Nothing was pending — it already auto-continued while this waited.
+        if (await step.count() === 0)
+            return true;
+        const terms = page.locator('[data-marketing-consent-terms]');
+        const hasTerms = await terms.count() > 0;
+        if (!hasTerms && opts?.accept === 'skip') {
+            await page.locator('[data-marketing-consent-skip]').click();
+            await step.waitFor({ state: 'detached', timeout });
+            return true;
+        }
+        if ((opts?.accept ?? 'all') === 'all') {
+            // The step draws "Select all" only when there is more than one row to select; a lone consent
+            // is ticked itself. Select all speaks for the Terms row too while it is up, which the choice
+            // below then settles either way.
+            const all = page.locator('[data-marketing-consent-all]');
+            if (await all.count() > 0) {
+                await all.click();
+            }
+            else {
+                for (const item of await page.locator('[data-marketing-consent-item]').all()) {
+                    await item.check();
+                }
+            }
+        }
+        // 'none' leaves every item unchecked and clicks nothing else before saving.
+        if (hasTerms) {
+            const wanted = (opts?.terms ?? 'accept') === 'accept';
+            if (wanted && !(await terms.isChecked())) {
+                await terms.check();
+            }
+            else if (!wanted && await terms.isChecked()) {
+                await terms.uncheck();
+            }
+        }
+        // `{ force: true }`: the confirm is never the native `disabled` — only `aria-disabled` while a
+        // Terms box is unticked, or merely styled muted with nothing changed yet — and Playwright's own
+        // actionability check honours `aria-disabled`, which this helper deliberately does not.
+        await page.locator('[data-marketing-consent-save]').click({ force: true });
+        const outcome = await Promise.race([
+            step.waitFor({ state: 'detached', timeout }).then(() => 'saved'),
+            page.locator('[data-marketing-consent-error]').waitFor({ state: 'visible', timeout })
+                .then(() => 'error'),
+            page.locator('[data-marketing-consent-terms-error]').waitFor({ state: 'visible', timeout })
+                .then(() => 'terms-error'),
+        ]).catch(() => 'error');
+        if (outcome === 'terms-error') {
+            throw new Error('[@owlmeans/test-ui] the marketing-consent step could not confirm the Terms');
+        }
+        if (outcome !== 'saved') {
+            const skip = page.locator('[data-marketing-consent-skip]');
+            if (await skip.count() > 0) {
+                console.warn('[@owlmeans/test-ui] marketing consent save did not complete; using the skip link instead');
+                await skip.click();
+                await step.waitFor({ state: 'detached', timeout }).catch(() => undefined);
+            }
+            else if (await terms.count() > 0) {
+                // No Skip is ever offered while the Terms box is up — a failed/blocked confirm here has no
+                // fallback, and silently returning would hide a caller stuck behind a real requirement.
+                throw new Error('[@owlmeans/test-ui] the marketing-consent step is still showing its Terms box');
+            }
+        }
+        // Answered either way: saved, or skipped past a flaky save. Never leaves the caller blocked.
+        return true;
+    };
+    const loginViaDispatcher = async (baseUrl, token, opts) => {
+        const path = opts?.dispatcherPath ?? '/dispatcher';
+        const url = new URL(path, baseUrl);
+        url.searchParams.set('token', token);
+        // `domcontentloaded`, not playwright's `load` default — see the note on `MountOptions.waitUntil`.
+        await page.goto(url.toString(), { waitUntil: opts?.waitUntil ?? 'domcontentloaded' });
+        // Wait until the dispatcher has navigated away (token consumed).
+        await page.waitForURL(u => !u.pathname.startsWith(path), { timeout: 30_000 });
+        if (opts?.marketingConsent !== 'ignore') {
+            await answerMarketingConsent({ accept: 'all', timeout: 30_000 });
+        }
+    };
+    const saveScreenshot = async (dir, name) => {
+        const target = resolve(dir);
+        await mkdir(target, { recursive: true });
+        const file = join(target, `${name}.png`);
+        await page.screenshot({ path: file, fullPage: true });
+        return file;
+    };
+    const acceptConsent = async (opts) => {
+        const dialog = page.locator('[data-consent-dialog]');
+        try {
+            await dialog.waitFor({ state: 'visible', timeout: opts?.timeout ?? 5_000 });
+        }
+        catch {
+            return false;
+        }
+        // Accept-all rather than essential-only: a test asserting a narrower decision should make that
+        // decision itself, and silently choosing the minimum here would hide it from the spec.
+        await page.locator('[data-consent-accept-all]').click();
+        await dialog.waitFor({ state: 'detached', timeout: opts?.timeout ?? 5_000 });
+        return true;
+    };
+    const loginViaSupervisorForm = async (opts) => {
+        const path = opts.path ?? DEFAULT_SUPERVISOR_PATH;
+        const timeout = opts.timeout ?? 60_000;
+        await page.goto(new URL(path, opts.baseUrl).toString(), {
+            waitUntil: opts.waitUntil ?? 'domcontentloaded', timeout
+        });
+        // Wait for the app to MOUNT before deciding whether there is a dialog to answer. `domcontentloaded`
+        // returns while the SPA is still booting, and on a dev server that boot is occasionally tens of
+        // seconds — so a short consent probe reports "no dialog", the dialog then mounts over the form,
+        // and the fill below waits out its own timeout on a field that is present but covered. Either
+        // marker proves the app is up: the dialog, or the form itself when consent was already given.
+        await page.locator('[data-consent-dialog], [data-testid="supervisor-user-id"]')
+            .first().waitFor({ state: 'visible', timeout });
+        if (opts.consent !== 'ignore')
+            await acceptConsent({ timeout });
+        // The form renders only AFTER the dialog is dismissed, so these carry the caller's budget rather
+        // than playwright's 30s default — the whole point of accepting an explicit `timeout` here.
+        await page.getByTestId('supervisor-user-id').fill(opts.userId, { timeout });
+        await page.getByTestId('supervisor-pk').fill(opts.pk, { timeout });
+        if (opts.screenshotDir != null) {
+            await saveScreenshot(opts.screenshotDir, 'supervisor-login-form');
+        }
+        await page.getByTestId('supervisor-submit').click({ timeout });
+        if (opts.expectPath != null) {
+            await page.waitForURL(url => url.toString().includes(opts.expectPath), { timeout });
+        }
+        else {
+            await page.waitForURL(url => !url.pathname.startsWith(path), { timeout });
+        }
+        // Carries the CALLER's own budget rather than the helper's smaller internal default — a slow
+        // cold environment (vite re-optimizing, a stage pod still warming) can easily spend most of a
+        // short fixed timeout just getting here, leaving too little for the two extra POSTs (terms, then
+        // items) a Terms-mode step now makes.
+        if (opts.marketingConsent !== 'ignore')
+            await answerMarketingConsent({ accept: 'all', timeout });
+    };
+    return { answerMarketingConsent, loginViaDispatcher, saveScreenshot, acceptConsent, loginViaSupervisorForm };
+};
+//# sourceMappingURL=page.js.map

package/build/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"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"}

package/build/supervisor/types.d.ts

@@ -0,0 +1,56 @@
+import type { AuthRole } from '@owlmeans/auth';
+export interface PregenerateAuthTokenOptions {
+    /** Target user id / email the token represents. */
+    userId: string;
+    /**
+     * Private key to sign the bearer with, e.g. `ed25519:<base64>` from
+     * `.env.dev.secrets`. MUST be the key the target backend trusts as its own
+     * signing key (it verifies bearers against `cfg.alias`/`cfg.service`).
+     */
+    pk: string;
+    scopes?: string[];
+    role?: AuthRole;
+    entityId?: string;
+    profileId?: string;
+    /** `source` recorded in the Auth payload (usually the backend service alias). */
+    source?: string;
+}
+export interface SupervisorApiAuthOptions {
+    /** Auth-manager API base URL (the backend serving /authentication/* and /authenticate). */
+    apiBaseUrl: string;
+    /** Target user id / email to authenticate (and register on first use). */
+    userId: string;
+    /** Supervisor private key, e.g. `ed25519:<base64>` from `.env.dev.secrets`. */
+    pk: string;
+    /** Paths, overridable for non-default routing. */
+    paths?: {
+        init?: string;
+        authenticate?: string;
+        dispatch?: string;
+    };
+    fetchImpl?: typeof fetch;
+}
+/** Bearers for a backend, minted without a browser. */
+export interface SupervisorAuthHelper {
+    /**
+     * Mint a ready-to-use `ED25519-BASIC-TOKEN ...` bearer offline, reusing
+     * `@owlmeans/test-auth`'s `makeBearer`. This is the "set a token directly"
+     * fast-path for e2e/integration tests: no UI, no live auth round-trip. The
+     * backend accepts it because it is signed by the project's own trusted key.
+     *
+     * For a faithful end-to-end login (real supervisor plugin + registration), drive
+     * {@link PageHelper.loginViaSupervisorForm} instead.
+     */
+    pregenerateAuthToken: (opts: PregenerateAuthTokenOptions) => Promise<string>;
+    /**
+     * Pregenerate a real bearer by driving the live PK-based supervisor flow over the
+     * backend API (no browser): `/authentication/init` -> sign the challenge with the
+     * supervisor key -> `/authentication/authenticate` -> `/authenticate` (dispatcher
+     * exchange). This is the faithful "set a token directly via API" path
+     * (registers the user on first use), independent of any front-end routing.
+     *
+     * Returns the final `ED25519-BASIC-TOKEN ...` bearer the backend accepts.
+     */
+    authenticateViaSupervisorApi: (opts: SupervisorApiAuthOptions) => Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/supervisor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/supervisor/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAG9C,MAAM,WAAW,2BAA2B;IAC1C,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,EAAE,EAAE,MAAM,CAAA;IACV,kDAAkD;IAClD,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,oBAAoB,EAAE,CAAC,IAAI,EAAE,2BAA2B,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5E;;;;;;;;OAQG;IACH,4BAA4B,EAAE,CAAC,IAAI,EAAE,wBAAwB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAClF"}

package/build/supervisor/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/supervisor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/supervisor/types.ts"],"names":[],"mappings":""}

package/build/supervisor.d.ts

@@ -1,138 +1,14 @@
 import type { Page } from 'playwright';
-import type { AuthRole } from '@owlmeans/auth';
-export interface PregenerateAuthTokenOptions {
-    /** Target user id / email the token represents. */
-    userId: string;
-    /**
-     * Private key to sign the bearer with, e.g. `ed25519:<base64>` from
-     * `.env.dev.secrets`. MUST be the key the target backend trusts as its own
-     * signing key (it verifies bearers against `cfg.alias`/`cfg.service`).
-     */
-    pk: string;
-    scopes?: string[];
-    role?: AuthRole;
-    entityId?: string;
-    profileId?: string;
-    /** `source` recorded in the Auth payload (usually the backend service alias). */
-    source?: string;
-}
-/**
- * Mint a ready-to-use `ED25519-BASIC-TOKEN ...` bearer offline, reusing
- * `@owlmeans/test-auth`'s `makeBearer`. This is the "set a token directly"
- * fast-path for e2e/integration tests: no UI, no live auth round-trip. The
- * backend accepts it because it is signed by the project's own trusted key.
- *
- * For a faithful end-to-end login (real supervisor plugin + registration), drive
- * {@link loginViaSupervisorForm} instead.
- */
-export declare const pregenerateAuthToken: (opts: PregenerateAuthTokenOptions) => Promise<string>;
-/**
- * Inject a pre-generated bearer into an app that uses the standard owlmeans
- * dispatcher: navigate to `/dispatcher?token=...` so the web app authenticates
- * and redirects home natively. Note: apps that override the DISPATCHER route
- * (e.g. to force an external IdP) should use {@link loginViaSupervisorForm}.
- */
-export declare const loginViaDispatcher: (page: Page, baseUrl: string, token: string, opts?: {
-    dispatcherPath?: string;
-    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
-    /**
-     * Answer the marketing-consent step if it is shown right after the dispatcher navigates away.
-     * Defaults to `'save'` (select-all and save) — see {@link answerMarketingConsent}. Pass
-     * `'ignore'` to skip the call entirely, e.g. in a spec that answers the step itself.
-     */
-    marketingConsent?: 'save' | 'ignore';
-}) => Promise<void>;
-export interface SupervisorApiAuthOptions {
-    /** Auth-manager API base URL (the backend serving /authentication/* and /authenticate). */
-    apiBaseUrl: string;
-    /** Target user id / email to authenticate (and register on first use). */
-    userId: string;
-    /** Supervisor private key, e.g. `ed25519:<base64>` from `.env.dev.secrets`. */
-    pk: string;
-    /** Paths, overridable for non-default routing. */
-    paths?: {
-        init?: string;
-        authenticate?: string;
-        dispatch?: string;
-    };
-    fetchImpl?: typeof fetch;
-}
-/**
- * Pregenerate a real bearer by driving the live PK-based supervisor flow over the
- * backend API (no browser): `/authentication/init` -> sign the challenge with the
- * supervisor key -> `/authentication/authenticate` -> `/authenticate` (dispatcher
- * exchange). This is the faithful "set a token directly via API" path
- * (registers the user on first use), independent of any front-end routing.
- *
- * Returns the final `ED25519-BASIC-TOKEN ...` bearer the backend accepts.
- */
+import type { AcceptConsentOptions, SupervisorFormLoginOptions } from './page/types.js';
+import type { SupervisorApiAuthOptions, SupervisorAuthHelper } from './supervisor/types.js';
+export declare const createSupervisorAuthHelper: () => SupervisorAuthHelper;
+export declare const supervisorAuthHelper: SupervisorAuthHelper;
+/** @deprecated compat:factory-refactor — use `supervisorAuthHelper.authenticateViaSupervisorApi(…)` */
 export declare const authenticateViaSupervisorApi: (opts: SupervisorApiAuthOptions) => Promise<string>;
-/**
- * Save a full-page screenshot to `<dir>/<name>.png`, creating `dir` if needed.
- * Returns the absolute file path. Use a host-backed folder (e.g. the project's
- * `tmp/tests/screenshots`) so the file is visible whether the test runs on the
- * host or inside a dev container.
- */
+/** @deprecated compat:factory-refactor — use `makePageHelper(page).saveScreenshot(…)` */
 export declare const saveScreenshot: (page: Page, dir: string, name: string) => Promise<string>;
-export interface SupervisorFormLoginOptions {
-    baseUrl: string;
-    /** Target user id / email. */
-    userId: string;
-    /** Supervisor private key (e.g. `ed25519:<base64>` from `.env.dev.secrets`). */
-    pk: string;
-    /** Login path; defaults to the standard supervisor route. */
-    path?: string;
-    /** Predicate/URL fragment that signals a successful landing (default: leaving the login path). */
-    expectPath?: string;
-    timeout?: number;
-    /**
-     * What counts as "arrived" for the initial navigation. Defaults to `domcontentloaded`.
-     *
-     * See the note on `MountOptions.waitUntil`: `load` is playwright's default and is wrong for a
-     * real application, because it waits for every subresource — a tag manager, an analytics beacon
-     * or any pixel that never settles holds it open until the navigation times out, with the login
-     * form rendered and fillable the whole time.
-     */
-    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
-    /**
-     * What to do about a cookie-consent dialog covering the form. Defaults to `accept`, because an
-     * OwlMeans app will not start an authentication flow until consent is answered — see
-     * {@link acceptConsent}. Pass `ignore` only in a spec that answers the dialog itself.
-     */
-    consent?: 'accept' | 'ignore';
-    /** When set, capture the filled login form (`supervisor-login-form.png`) before submit. */
-    screenshotDir?: string;
-    /**
-     * Answer the marketing-consent step if it is shown right after landing. Defaults to `'save'`
-     * (select-all and save) — see {@link answerMarketingConsent}. Pass `'ignore'` to skip the call
-     * entirely, e.g. in a spec that answers the step itself.
-     */
-    marketingConsent?: 'save' | 'ignore';
-}
-/**
- * Answer the cookie-consent dialog if one is up, so the page underneath can be driven.
- *
- * An OwlMeans app asks for consent BEFORE it will start an authentication flow, and the dialog is
- * a modal with no dismissal — by design, since a decision is what the gate is waiting for. For a
- * test that means the login form renders, resolves, reports itself "visible, enabled and stable"
- * and still cannot be clicked, because the overlay intercepts the pointer. Playwright retries for
- * the full timeout and then blames the button, which is the most misleading failure in this file:
- * nothing is wrong with the form.
- *
- * Accepting is the honest default for a login helper — the flow it is about to drive is exactly
- * what the dialog is gating — but it is best-effort: an app without the widget, or one where the
- * visitor already decided, simply has no dialog and this returns at once.
- *
- * @returns whether a dialog was actually answered.
- */
-export declare const acceptConsent: (page: Page, opts?: {
-    timeout?: number;
-}) => Promise<boolean>;
-/**
- * Drive the PK-based supervisor login FORM end-to-end (the faithful path that
- * exercises the real supervisor plugin + registration): navigate to the
- * supervisor login route, fill the user id + private key, submit, and wait for
- * the app to leave the login screen.
- */
+/** @deprecated compat:factory-refactor — use `makePageHelper(page).acceptConsent(…)` */
+export declare const acceptConsent: (page: Page, opts?: AcceptConsentOptions) => Promise<boolean>;
+/** @deprecated compat:factory-refactor — use `makePageHelper(page).loginViaSupervisorForm(…)` */
 export declare const loginViaSupervisorForm: (page: Page, opts: SupervisorFormLoginOptions) => Promise<void>;
 //# sourceMappingURL=supervisor.d.ts.map