@zitadel/testing 0.0.0 → 0.1.0-alpha.19

package/dist/playwright.d.mts

@@ -1,8 +1,151 @@
-import { a as Identity, d as SeedUserInput, f as SeedUsersTemplate, i as ConnectedZitadel, l as MintedSession, n as applyAppEnvTemplate, o as InstanceHandle, p as SeededUser, r as nextAppEnv, t as AppEnvTemplate, u as SeedSessionInput } from "./app-env-D3W0GYhA.mjs";
+import { a as Identity, d as SeedUserInput, f as SeedUsersTemplate, i as ConnectedZitadel, l as MintedSession, n as applyAppEnvTemplate, o as InstanceHandle, p as SeededUser, r as nextAppEnv, t as AppEnvTemplate, u as SeedSessionInput } from "./app-env-Btmfcflb.mjs";
 import { SetupPreset, SetupUseCase } from "@zitadel/config/defaults";
 import * as _$_playwright_test0 from "@playwright/test";
-import { Page, PlaywrightTestConfig, expect } from "@playwright/test";
+import { Locator, Page, PlaywrightTestConfig, expect } from "@playwright/test";
 
+//#region src/passkey.d.ts
+/**
+ * A virtual WebAuthn authenticator attached to one page. Ceremonies started
+ * from that page (passkey registration, passkey login) complete automatically
+ * — no OS authenticator dialog, no touch.
+ */
+interface VirtualPasskey {
+  /** CDP id of the virtual authenticator, for advanced raw-protocol use. */
+  authenticatorId: string;
+  /** Number of credentials the authenticator currently stores. */
+  credentialCount(): Promise<number>;
+  /** Remove the authenticator and detach the CDP session. */
+  dispose(): Promise<void>;
+}
+/**
+ * Attach a virtual passkey authenticator to the page via the Chrome DevTools
+ * Protocol. The options mirror a platform authenticator with discoverable
+ * credentials and automatic user presence — the profile the consumer journey
+ * has run in CI since passkey coverage became mandatory there.
+ *
+ * Chromium only: the CDP WebAuthn domain does not exist in WebKit or Firefox.
+ * The authenticator is bound to this page — drive registration and the later
+ * login from the same page, or the credential is gone. Serve the app under
+ * test on an origin WebAuthn accepts as a relying-party ID: HTTPS on a real
+ * domain, or `http://localhost` for local runs — raw IP origins such as
+ * `http://127.0.0.1` are invalid RP IDs.
+ */
+declare function enableVirtualPasskey(page: Page): Promise<VirtualPasskey>;
+//#endregion
+//#region src/flows.d.ts
+/**
+ * Helpers that drive the `<zitadel-login>` widget through complete auth
+ * ceremonies, built on the widget's documented automation hooks
+ * (`zitadel-field-*` / `zitadel-input-*` on fields, `zitadel-action-*` on
+ * actions — see packages/components/README.md). Field names use the
+ * normalised hook token: the flow engine names credential fields
+ * `x-auth-methods#password`, but the hook (and this API) says `password`.
+ *
+ * The ceremony helpers assume the default flow vocabulary — steps that
+ * declare `submit` / `passkey` / `passkey_register` actions and `email` /
+ * password fields, as `default-login.json` does. They branch only on
+ * widget-observable state (which fields and actions the flow renders),
+ * because customer flow configurations legitimately vary; they never
+ * assert app state. Callers navigate to the widget first and assert their
+ * own signed-in surface afterwards. Flows with renamed actions or custom
+ * steps drive the widget directly via `flowAction` / `flowField`.
+ */
+interface FlowActionOptions {
+  /**
+   * Accessible-name fallback for templates that do not emit the documented
+   * `data-testid` hooks: adds role-based button/link candidates.
+   */
+  name?: RegExp;
+}
+interface FlowFieldOptions {
+  /** Label fallback for templates that do not emit the documented hooks. */
+  label?: RegExp;
+}
+/**
+ * One optional registration field, filled only when the flow renders it.
+ * The value's type picks the control: a boolean drives a checkbox
+ * (`zl-checkbox`), a string first tries a select (`zl-select`) and falls
+ * back to filling a text-like input.
+ */
+interface ProfileEntry {
+  /** Normalised field hook token, e.g. `givenName`. */
+  field: string;
+  value: string | boolean;
+  /** Label fallback for text-like inputs on templates without hooks. */
+  label?: RegExp;
+}
+interface LoginCredentials {
+  email: string;
+  password: string;
+}
+interface RegistrationDetails {
+  email: string;
+  /** Extra fields some flows require at registration, filled if rendered. */
+  profile?: ProfileEntry[];
+}
+interface PasswordRegistrationDetails extends RegistrationDetails {
+  password: string;
+}
+/**
+ * Locator for a flow action control by its declared action name. Matches
+ * every hook shape the default template emits — host testid, native
+ * shadow button/link testids, and the raw `action`/`data-action`
+ * attributes (the recover link carries only `data-action`).
+ */
+declare function flowAction(page: Page, action: string, options?: FlowActionOptions): Locator;
+/**
+ * Locator for a flow field's input by its normalised hook token
+ * (`email`, `password`, a user-schema property name).
+ */
+declare function flowField(page: Page, field: string, options?: FlowFieldOptions): Locator;
+/** Click a flow action (auto-waits like any locator click). */
+declare function clickFlowAction(page: Page, action: string, options?: FlowActionOptions): Promise<void>;
+/** Fill a flow field (auto-waits like any locator fill). */
+declare function fillFlowField(page: Page, field: string, value: string, options?: FlowFieldOptions): Promise<void>;
+/**
+ * Sign in with email and password from the flow's entry step. Handles both
+ * the default split shape (identifier → password) and flows that render
+ * the password field on the entry step.
+ */
+declare function loginWithPassword(page: Page, {
+  email,
+  password
+}: LoginCredentials): Promise<void>;
+/**
+ * Sign in with a passkey. With `email`, fills the identifier and takes the
+ * step's passkey action; without, taps the entry step's passkey action
+ * directly (discoverable-credential one-tap, e.g. the passkey-first
+ * preset). Pair with `enableVirtualPasskey` / the `passkey` fixture in
+ * headless runs — the ceremony completes automatically once the widget
+ * issues the WebAuthn challenge.
+ */
+declare function loginWithPasskey(page: Page, options?: {
+  email?: string;
+}): Promise<void>;
+/**
+ * Register a new user with a password: enter the (unknown) identifier,
+ * advance into the registration step, continue on the password path, and
+ * submit the password. Ends when the final submit is clicked — assert your
+ * app's signed-in surface afterwards. Flows that route through steps the
+ * default flow does not (e.g. a passkey upsell) need caller-side handling
+ * after this returns.
+ */
+declare function registerWithPassword(page: Page, {
+  email,
+  password,
+  profile
+}: PasswordRegistrationDetails): Promise<void>;
+/**
+ * Register a new user with a passkey: enter the (unknown) identifier,
+ * advance into the registration step, and take its `passkey_register`
+ * action. Requires an authenticator (see `loginWithPasskey`). The default
+ * flow completes registration from the ceremony directly.
+ */
+declare function registerWithPasskey(page: Page, {
+  email,
+  profile
+}: RegistrationDetails): Promise<void>;
+//#endregion
 //#region src/orchestration.d.ts
 interface SupervisorConfig {
   /** Fixed port: the config process must know the health URL up front. */
@@ -51,8 +194,20 @@ interface WithZitadelOptions {
     keep?: boolean; /** webServer readiness timeout for the boot; cold boot dominates it. */
     bootTimeoutMs?: number;
   };
-  /** The app dev server to run against the instance. */
-  app: {
+  /**
+   * The app dev server to run against the instance.
+   *
+   * Omit it when the **instance itself serves the app** — the Zitadel binary
+   * embeds the console and hosted login shells at `/ui/console/` and
+   * `/ui/login/`, so there is no second server to boot and no env to hand it.
+   * Only the supervisor entry is generated, and `appOrigin` must then be the
+   * instance's own local origin — `http://localhost:<port>` (or another
+   * loopback alias); nothing else is served in this mode. This is the only
+   * configuration that exercises the production path — under a dev server,
+   * the app's proxy rewrites API requests that the binary would serve
+   * directly.
+   */
+  app?: {
     /** Spawn argv (no shell), e.g. ["corepack", "pnpm", "--filter", "my-app", "dev"]. */command: string[]; /** Working directory for the app command. */
     cwd: string; /** Path on `appOrigin` Playwright polls for readiness, e.g. "/login". */
     readyPath: string;
@@ -81,13 +236,19 @@ interface WithZitadelOptions {
  * });
  * ```
  *
+ * Omit `app` when the instance serves the app itself (the binary's embedded
+ * `/ui/console/` and `/ui/login/` surfaces): only the boot entry is
+ * generated, and `appOrigin` must be the instance's own origin.
+ *
  * Also points ZITADEL_TESTING_HANDSHAKE at the handshake file so the
  * `@zitadel/testing/playwright` fixtures resolve the instance — Playwright
  * workers re-evaluate the config, which re-applies this for every process
  * that needs it. The returned value is plain data; append your own entries
  * to `webServer` if the suite needs additional servers.
  */
-declare function withZitadel(options: WithZitadelOptions, /** Test seam: alternative executable resolution. */resolveEntry?: (name: "supervisor" | "app-runner") => string): {
+declare function withZitadel(options: WithZitadelOptions, /** Test seam: alternative executable resolution. */
+
+resolveEntry?: (name: "supervisor" | "app-runner") => string): {
   webServer: WebServerEntry[];
 };
 //#endregion
@@ -113,6 +274,12 @@ interface ZitadelTestFixtures {
    * `use.baseURL` (every withZitadel consumer sets it).
    */
   authenticatedPage: AuthenticatedPage;
+  /**
+   * Virtual passkey authenticator attached to the default `page`, disposed on
+   * teardown. On-demand: tests that don't request it pay nothing. Chromium
+   * only — see `enableVirtualPasskey` for the constraints.
+   */
+  passkey: VirtualPasskey;
 }
 interface ZitadelWorkerFixtures {
   /** Connection to the suite's instance, resolved once per worker. */
@@ -120,5 +287,5 @@ interface ZitadelWorkerFixtures {
 }
 declare const test: _$_playwright_test0.TestType<_$_playwright_test0.PlaywrightTestArgs & _$_playwright_test0.PlaywrightTestOptions & ZitadelTestFixtures, _$_playwright_test0.PlaywrightWorkerArgs & _$_playwright_test0.PlaywrightWorkerOptions & ZitadelWorkerFixtures>;
 //#endregion
-export { type AppEnvTemplate, AuthenticatedPage, type ConnectedZitadel, type Identity, type InstanceHandle, type MintedSession, type SeedSessionInput, type SeedUserInput, type SeedUsersTemplate, type SeededUser, type WithZitadelOptions, ZitadelTestFixtures, ZitadelWorkerFixtures, applyAppEnvTemplate, expect, nextAppEnv, test, withZitadel };
+export { type AppEnvTemplate, AuthenticatedPage, type ConnectedZitadel, type FlowActionOptions, type FlowFieldOptions, type Identity, type InstanceHandle, type LoginCredentials, type MintedSession, type PasswordRegistrationDetails, type ProfileEntry, type RegistrationDetails, type SeedSessionInput, type SeedUserInput, type SeedUsersTemplate, type SeededUser, type VirtualPasskey, type WithZitadelOptions, ZitadelTestFixtures, ZitadelWorkerFixtures, applyAppEnvTemplate, clickFlowAction, enableVirtualPasskey, expect, fillFlowField, flowAction, flowField, loginWithPasskey, loginWithPassword, nextAppEnv, registerWithPasskey, registerWithPassword, test, withZitadel };
 //# sourceMappingURL=playwright.d.mts.map

package/dist/playwright.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.d.mts","names":[],"sources":["../src/orchestration.ts","../src/playwright-config.ts","../src/playwright.ts"],"mappings":";;;;;;UAeiB,gBAAA;EAMf;EAJA,IAAA;EACA,UAAA;EACA,YAAA;EAMA;EAJA,gBAAA;EACA,GAAA;EACA,IAAA;EACA,WAAA;EACA,MAAA,GAAS,WAAA;EACT,OAAA,GAAU,YAAA;EACV,SAAA;AAAA;;;KCZG,cAAA,GAAiB,OAAA,CACpB,WAAA,CAAY,oBAAA;AAAA,UAIG,kBAAA;;ADLjB;;;;ECWE,SAAA;EDRA;;;;;ECcA,IAAA;EDPA;;;;;ECaA,SAAA;EDXS;ECaT,OAAA;8CAEE,YAAA,WA3BC;IA6BD,gBAAA;IACA,WAAA;IACA,MAAA,GAAS,gBAAA;IACT,OAAA,GAAU,gBAAA,aAhCQ;IAkClB,GAAA,WAlCyB;IAoCzB,IAAA,YAnCF;IAqCE,aAAA;EAAA;EArC8B;EAwChC,GAAA;IApCiC,qFAsC/B,OAAA,YAZS;IAcT,GAAA,UASK;IAPL,SAAA;IAOmB;;;;;;IAAnB,GAAA,EAAK,cAAA;IACL,cAAA,WAxBA;IA0BA,kBAAA;EAAA;EAzBU;EA4BZ,aAAA;AAAA;;;;;;;;;;;;;AAqBF;;;;;;iBAAgB,WAAA,CACd,OAAA,EAAS,kBAAA,sDAET,YAAA,IAAe,IAAA;EACZ,SAAA,EAAW,cAAA;AAAA;;;UCtFC,iBAAA;;EAEf,IAAA,EAAM,IAAA;EACN,IAAA,EAAM,UAAA;EACN,OAAA,EAAS,aAAA;AAAA;AAAA,UAGM,mBAAA;EFKO;EEHtB,IAAA;IACE,IAAA,CAAK,KAAA,GAAQ,aAAA,GAAgB,OAAA,CAAQ,UAAA;IACrC,KAAA,CAAM,KAAA,UAAe,QAAA,GAAW,iBAAA,GAAoB,OAAA,CAAQ,UAAA,KFJ9D;IEME,QAAA,IAAY,QAAA,EFJd;IEME,OAAA,CAAQ,KAAA,GAAQ,gBAAA,GAAmB,OAAA,CAAQ,aAAA;EAAA;EFJpC;;;;;;EEYT,iBAAA,EAAmB,iBAAA;AAAA;AAAA,UAGJ,qBAAA;EDzBZ;EC2BH,OAAA,EAAS,gBAAA;AAAA;AAAA,cAGE,IAAA,EAAI,mBAAA,CAAA,QAAA,CA0Cf,mBAAA,CA1Ce,kBAAA,GAAA,mBAAA,CAAA,qBAAA,GAAA,mBAAA,EAAA,mBAAA,CAAA,oBAAA,GAAA,mBAAA,CAAA,uBAAA,GAAA,qBAAA"}
+{"version":3,"file":"playwright.d.mts","names":[],"sources":["../src/passkey.ts","../src/flows.ts","../src/orchestration.ts","../src/playwright-config.ts","../src/playwright.ts"],"mappings":"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"}

package/dist/playwright.mjs

@@ -1,10 +1,236 @@
-import { a as nextAppEnv, i as applyAppEnvTemplate, t as readHandshakeSync } from "./handshake-BPtWruO8.mjs";
-import { t as connectZitadel } from "./src-DkG0V4A6.mjs";
+import { a as nextAppEnv, i as applyAppEnvTemplate, n as waitForHandshake } from "./handshake-ClzWvG8z.mjs";
+import { t as connectZitadel } from "./src-9dFjTIAw.mjs";
 import { n as HANDSHAKE_ENV, r as SUPERVISOR_CONFIG_ENV, t as APP_RUNNER_CONFIG_ENV } from "./orchestration-C640_1Lg.mjs";
 import { extname, isAbsolute, join } from "node:path";
 import { existsSync } from "node:fs";
 import { expect, test as test$1 } from "@playwright/test";
 import { fileURLToPath } from "node:url";
+//#region src/passkey.ts
+/**
+* Attach a virtual passkey authenticator to the page via the Chrome DevTools
+* Protocol. The options mirror a platform authenticator with discoverable
+* credentials and automatic user presence — the profile the consumer journey
+* has run in CI since passkey coverage became mandatory there.
+*
+* Chromium only: the CDP WebAuthn domain does not exist in WebKit or Firefox.
+* The authenticator is bound to this page — drive registration and the later
+* login from the same page, or the credential is gone. Serve the app under
+* test on an origin WebAuthn accepts as a relying-party ID: HTTPS on a real
+* domain, or `http://localhost` for local runs — raw IP origins such as
+* `http://127.0.0.1` are invalid RP IDs.
+*/
+async function enableVirtualPasskey(page) {
+	let client;
+	try {
+		client = await page.context().newCDPSession(page);
+	} catch (error) {
+		throw new Error("enableVirtualPasskey: could not open a CDP session — passkey testing needs Chromium's virtual authenticator, so run passkey specs in a Chromium project.", { cause: error });
+	}
+	let authenticatorId;
+	try {
+		await client.send("WebAuthn.enable");
+		({authenticatorId} = await client.send("WebAuthn.addVirtualAuthenticator", { options: {
+			protocol: "ctap2",
+			transport: "internal",
+			hasResidentKey: true,
+			hasUserVerification: true,
+			isUserVerified: true,
+			automaticPresenceSimulation: true
+		} }));
+	} catch (error) {
+		await client.detach().catch(() => void 0);
+		throw error;
+	}
+	return {
+		authenticatorId,
+		async credentialCount() {
+			const { credentials } = await client.send("WebAuthn.getCredentials", { authenticatorId });
+			return credentials.length;
+		},
+		async dispose() {
+			try {
+				await client.send("WebAuthn.removeVirtualAuthenticator", { authenticatorId });
+			} catch {} finally {
+				await client.detach().catch(() => void 0);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/flows.ts
+/**
+* A union locator resolves in DOM order across the whole page, so every
+* candidate built from a broad selector — accessible names, labels, the
+* generic `data-action` attribute — is scoped to the `<zitadel-login>`
+* host; otherwise a same-named control in the app's own chrome (header
+* nav, footer forms) could win the union. The host element exists no
+* matter what the tenant's template renders, so these fallbacks keep
+* working for custom templates that emit no automation hooks — the case
+* they exist for. The `zitadel-*` testid hooks and the `zl-button` atom
+* are namespaced and stay page-global.
+*/
+function widgetRoot(page) {
+	return page.locator("zitadel-login");
+}
+/**
+* Escape a value for use inside a double-quoted CSS attribute selector,
+* per the CSSOM "serialize a string" rules: NUL becomes U+FFFD, control
+* characters become hex code-point escapes, quote and backslash are
+* backslash-escaped. C1 controls (U+0080–U+009F) are escaped too — CSSOM
+* itself leaves them literal, but the escaped form is equivalent and
+* survives stricter-than-spec selector parsers. Anything the flow schema
+* accepts as an action name yields a parseable selector.
+*/
+function cssAttributeValue(value) {
+	let out = "";
+	for (const ch of value) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (code === 0) out += "�";
+		else if (code <= 31 || code >= 127 && code <= 159) out += `\\${code.toString(16)} `;
+		else if (ch === "\"" || ch === "\\") out += `\\${ch}`;
+		else out += ch;
+	}
+	return out;
+}
+/**
+* Locator for a flow action control by its declared action name. Matches
+* every hook shape the default template emits — host testid, native
+* shadow button/link testids, and the raw `action`/`data-action`
+* attributes (the recover link carries only `data-action`).
+*/
+function flowAction(page, action, options = {}) {
+	const attributeSafe = cssAttributeValue(action);
+	let candidates = page.getByTestId(`zitadel-action-${action}`).or(page.getByTestId(`zitadel-action-${action}-button`)).or(page.getByTestId(`zitadel-action-${action}-link`)).or(page.locator(`zl-button[action="${attributeSafe}"]`)).or(widgetRoot(page).locator(`[data-action="${attributeSafe}"]`));
+	if (options.name) candidates = candidates.or(widgetRoot(page).getByRole("button", { name: options.name })).or(widgetRoot(page).getByRole("link", { name: options.name }));
+	return candidates.first();
+}
+/**
+* Locator for a flow field's input by its normalised hook token
+* (`email`, `password`, a user-schema property name).
+*/
+function flowField(page, field, options = {}) {
+	let candidates = page.getByTestId(`zitadel-input-${field}`).or(page.getByTestId(`zitadel-field-${field}`).locator("input"));
+	if (options.label) candidates = candidates.or(widgetRoot(page).getByLabel(options.label));
+	return candidates.first();
+}
+/** Click a flow action (auto-waits like any locator click). */
+async function clickFlowAction(page, action, options) {
+	await flowAction(page, action, options).click();
+}
+/** Fill a flow field (auto-waits like any locator fill). */
+async function fillFlowField(page, field, value, options) {
+	await flowField(page, field, options).fill(value);
+}
+/**
+* Sign in with email and password from the flow's entry step. Handles both
+* the default split shape (identifier → password) and flows that render
+* the password field on the entry step.
+*/
+async function loginWithPassword(page, { email, password }) {
+	await emailField(page).fill(email);
+	const password_ = passwordField(page);
+	if (!await password_.isVisible().catch(() => false)) await flowAction(page, "submit").click();
+	await password_.fill(password);
+	await flowAction(page, "submit").click();
+}
+/**
+* Sign in with a passkey. With `email`, fills the identifier and takes the
+* step's passkey action; without, taps the entry step's passkey action
+* directly (discoverable-credential one-tap, e.g. the passkey-first
+* preset). Pair with `enableVirtualPasskey` / the `passkey` fixture in
+* headless runs — the ceremony completes automatically once the widget
+* issues the WebAuthn challenge.
+*/
+async function loginWithPasskey(page, options = {}) {
+	if (options.email !== void 0) await emailField(page).fill(options.email);
+	await flowAction(page, "passkey").click();
+}
+/**
+* Register a new user with a password: enter the (unknown) identifier,
+* advance into the registration step, continue on the password path, and
+* submit the password. Ends when the final submit is clicked — assert your
+* app's signed-in surface afterwards. Flows that route through steps the
+* default flow does not (e.g. a passkey upsell) need caller-side handling
+* after this returns.
+*/
+async function registerWithPassword(page, { email, password, profile }) {
+	await advanceToRegistration(page, email, profile);
+	const password_ = passwordField(page);
+	if (!await password_.isVisible().catch(() => false)) await flowAction(page, "submit").click();
+	await password_.fill(password);
+	await flowAction(page, "submit").click();
+}
+/**
+* Register a new user with a passkey: enter the (unknown) identifier,
+* advance into the registration step, and take its `passkey_register`
+* action. Requires an authenticator (see `loginWithPasskey`). The default
+* flow completes registration from the ceremony directly.
+*/
+async function registerWithPasskey(page, { email, profile }) {
+	await advanceToRegistration(page, email, profile);
+	await flowAction(page, "passkey_register").click();
+}
+function emailField(page) {
+	return flowField(page, "email", { label: /email/i });
+}
+function passwordField(page) {
+	return flowField(page, "password", { label: /password/i });
+}
+/**
+* From the entry step: submit the unknown identifier (the default flow's
+* `user_not_found` transition routes to registration), or take an explicit
+* `register` navigate action when the entry step is a combined
+* email+password step — there, submitting would attempt a password sign-in
+* instead. Then wait for the registration step and fill what it renders.
+*/
+async function advanceToRegistration(page, email, profile) {
+	await emailField(page).fill(email);
+	if (await passwordField(page).isVisible().catch(() => false)) await flowAction(page, "register").click();
+	else await flowAction(page, "submit").click();
+	await expectRegistrationStep(page);
+	await fillIfVisible(emailField(page), email);
+	for (const entry of profile ?? []) await fillProfileEntry(page, entry);
+}
+/**
+* Fill one registration field with the verb its control needs: booleans
+* check the `zl-checkbox` native input, strings prefer the `zl-select`
+* native select (option matched by value, falling back to label) and
+* otherwise fill a text-like input. The select/checkbox natives carry the
+* name-first testids the atoms document (`zitadel-select-*`,
+* `zitadel-checkbox-*`); templates without those hooks drive such fields
+* via their own locators.
+*/
+async function fillProfileEntry(page, entry) {
+	if (typeof entry.value === "boolean") {
+		const checkbox = page.getByTestId(`zitadel-checkbox-${entry.field}`).first();
+		if (await checkbox.isVisible().catch(() => false)) await checkbox.setChecked(entry.value);
+		return;
+	}
+	const select = page.getByTestId(`zitadel-select-${entry.field}`).first();
+	if (await select.isVisible().catch(() => false)) {
+		await select.selectOption(entry.value);
+		return;
+	}
+	await fillIfVisible(flowField(page, entry.field, { label: entry.label }), entry.value);
+}
+/**
+* Barrier between the entry submit and probing the registration step's
+* fields: without it, optional-field probes race the re-render and read
+* the outgoing step. The default flow's registration step declares
+* `passkey_register` — a structural, locale-independent signal; the
+* heading regex covers password-only flows on the default English
+* template.
+*/
+async function expectRegistrationStep(page) {
+	await flowAction(page, "passkey_register").or(widgetRoot(page).getByRole("heading", { name: /create|register|sign up|no-account/i })).first().waitFor({
+		state: "visible",
+		timeout: 3e4
+	});
+}
+async function fillIfVisible(field, value) {
+	if (await field.isVisible().catch(() => false)) await field.fill(value);
+}
+//#endregion
 //#region src/playwright-config.ts
 /**
 * Generate the Playwright `webServer` entries that boot an ephemeral seeded
@@ -18,6 +244,10 @@ import { fileURLToPath } from "node:url";
 * });
 * ```
 *
+* Omit `app` when the instance serves the app itself (the binary's embedded
+* `/ui/console/` and `/ui/login/` surfaces): only the boot entry is
+* generated, and `appOrigin` must be the instance's own origin.
+*
 * Also points ZITADEL_TESTING_HANDSHAKE at the handshake file so the
 * `@zitadel/testing/playwright` fixtures resolve the instance — Playwright
 * workers re-evaluate the config, which re-applies this for every process
@@ -30,9 +260,18 @@ function withZitadel(options, resolveEntry = entryPoint) {
 	if (!Number.isInteger(port) || port <= 0) throw new Error(`withZitadel: port must be a positive integer, got ${port}`);
 	const origin = URL.canParse(appOrigin) ? new URL(appOrigin) : void 0;
 	if (!origin || origin.protocol !== "http:" && origin.protocol !== "https:" || origin.pathname !== "/" || origin.search !== "" || origin.hash !== "") throw new Error(`withZitadel: appOrigin must be an origin like "http://localhost:3002", got "${appOrigin}"`);
-	if (!app.readyPath.startsWith("/")) throw new Error(`withZitadel: app.readyPath must start with "/", got "${app.readyPath}"`);
-	if (app.command.length === 0) throw new Error("withZitadel: app.command must not be empty");
-	if (!isAbsolute(app.cwd)) throw new Error(`withZitadel: app.cwd must be absolute, got "${app.cwd}"`);
+	if (app === void 0) {
+		const loopbackHosts = new Set([
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		]);
+		if (origin.protocol !== "http:" || !loopbackHosts.has(origin.hostname) || (origin.port || "80") !== String(port)) throw new Error(`withZitadel: with no \`app\`, the instance itself serves the app, so appOrigin must be its local origin (http://localhost:${port}); got "${appOrigin}".`);
+	} else {
+		if (!app.readyPath.startsWith("/")) throw new Error(`withZitadel: app.readyPath must start with "/", got "${app.readyPath}"`);
+		if (app.command.length === 0) throw new Error("withZitadel: app.command must not be empty");
+		if (!isAbsolute(app.cwd)) throw new Error(`withZitadel: app.cwd must be absolute, got "${app.cwd}"`);
+	}
 	for (const [label, value] of [
 		["zitadel.serverBinary", options.zitadel?.serverBinary],
 		["zitadel.dir", options.zitadel?.dir],
@@ -51,13 +290,7 @@ function withZitadel(options, resolveEntry = entryPoint) {
 		preset: options.zitadel?.preset,
 		useCase: options.zitadel?.useCase
 	};
-	const appRunnerConfig = {
-		command: app.command,
-		cwd: app.cwd,
-		env: app.env,
-		handshakeTimeoutMs: app.readyTimeoutMs ?? 18e4
-	};
-	return { webServer: [{
+	const supervisorEntry = {
 		command: `node ${JSON.stringify(resolveEntry("supervisor"))}`,
 		url: `http://localhost:${port}/healthz`,
 		reuseExistingServer: false,
@@ -73,7 +306,15 @@ function withZitadel(options, resolveEntry = entryPoint) {
 			signal: "SIGTERM",
 			timeout: 3e4
 		}
-	}, {
+	};
+	if (app === void 0) return { webServer: [supervisorEntry] };
+	const appRunnerConfig = {
+		command: app.command,
+		cwd: app.cwd,
+		env: app.env,
+		handshakeTimeoutMs: app.readyTimeoutMs ?? 18e4
+	};
+	return { webServer: [supervisorEntry, {
 		command: `node ${JSON.stringify(resolveEntry("app-runner"))}`,
 		url: new URL(app.readyPath, appOrigin).toString(),
 		reuseExistingServer: false,
@@ -110,8 +351,11 @@ const test = test$1.extend({
 	zitadel: [async ({}, use) => {
 		const handshakePath = process.env.ZITADEL_TESTING_HANDSHAKE;
 		if (!handshakePath) throw new Error("ZITADEL_TESTING_HANDSHAKE is not set. Point it at the handshake file written by the script that boots the instance (see @zitadel/testing docs).");
-		await use(connectZitadel(readHandshakeSync(handshakePath)));
-	}, { scope: "worker" }],
+		await use(connectZitadel(await waitForHandshake(handshakePath)));
+	}, {
+		scope: "worker",
+		auto: true
+	}],
 	seed: async ({ zitadel, baseURL }, use) => {
 		await use({
 			user: (input) => zitadel.seedUser(input),
@@ -123,6 +367,11 @@ const test = test$1.extend({
 			})
 		});
 	},
+	passkey: async ({ page }, use) => {
+		const passkey = await enableVirtualPasskey(page);
+		await use(passkey);
+		await passkey.dispose();
+	},
 	authenticatedPage: async ({ browser, zitadel, baseURL }, use) => {
 		if (!baseURL) throw new Error("authenticatedPage requires `use.baseURL` so the session cookie can be scoped to the app under test.");
 		const session = await zitadel.seedSession({ origin: baseURL });
@@ -141,6 +390,6 @@ const test = test$1.extend({
 	}
 });
 //#endregion
-export { applyAppEnvTemplate, expect, nextAppEnv, test, withZitadel };
+export { applyAppEnvTemplate, clickFlowAction, enableVirtualPasskey, expect, fillFlowField, flowAction, flowField, loginWithPasskey, loginWithPassword, nextAppEnv, registerWithPasskey, registerWithPassword, test, withZitadel };
 
 //# sourceMappingURL=playwright.mjs.map