@zitadel/testing 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZITADEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# @zitadel/testing
+
+Test-kit for **seeded ephemeral local Zitadel instances**: boot the real server
+(binary runtime + embedded Postgres, no Docker) from test code, create a
+project with the default login flow, and mint password users that can complete
+the real login journey immediately.
+
+> **Status: alpha.** Published to npm on the shared release train — the kit
+> carries the same version as `@zitadel/cli` and the SDKs, the train publishes
+> under the `alpha` dist-tag (install with `@alpha`), and APIs can still move
+> between alphas. macOS/Linux (see [Known limitations](#known-limitations)).
+
+## Why
+
+The repo previously had two extremes: the demo e2e suites run against
+`@zitadel/api-mock` (fast, but fake — no user store, no real crypto), and
+`cli-journey-e2e` runs the real packaged product but creates users by clicking
+through the registration UI, serialized per suite. This kit fills the middle:
+**real server, programmatic seeding, parallel-safe per-test users.**
+
+## Quick start (Playwright)
+
+```sh
+npm i -D @zitadel/testing@alpha @playwright/test
+```
+
+The kit drives the `zitadel` CLI, which resolves the published
+`@zitadel/server` platform binary on its own — no binary paths, no env vars.
+
+One instance per suite, seeded per test. `withZitadel()` generates the
+`webServer` entries that boot the instance and run your app against it — no
+wrapper scripts:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+import { nextAppEnv, withZitadel } from "@zitadel/testing/playwright";
+
+export default defineConfig({
+  testDir: "./e2e",
+  ...withZitadel({
+    configDir: import.meta.dirname,
+    port: 8092, // fixed, so the readiness URL is known up front
+    appOrigin: "http://localhost:3002", // your app's origin (proxy origin check)
+    app: {
+      command: ["pnpm", "dev"], // your app's dev server
+      cwd: import.meta.dirname,
+      readyPath: "/login",
+      env: nextAppEnv, // or your own AppEnvTemplate
+    },
+  }),
+});
+```
+
+```ts
+// my-login.spec.ts
+import { expect, test } from "@zitadel/testing/playwright";
+
+test("user signs in with password", async ({ page, seed }) => {
+  const user = await seed.user(); // unique email + password, loginable now
+  await page.goto("/login");
+  await page.getByLabel(/email/i).fill(user.email);
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+  await page.getByLabel(/password/i).fill(user.password);
+  await page.getByRole("button", { name: "Sign in", exact: true }).click();
+  await expect(page).toHaveURL(/\/admin/);
+});
+```
+
+`app.env` is an `AppEnvTemplate`: a serializable mapping from your app's env
+var names to `InstanceHandle` fields. `nextAppEnv` covers `@zitadel/sdk-next`
+apps; the console maps the same fields to `VITE_*`/`CONSOLE_*` names instead.
+The fixtures find the instance through `ZITADEL_TESTING_HANDSHAKE`, which
+`withZitadel()` points at its handshake file.
+
+### Start tests authenticated
+
+Most app tests don't want to re-test login. `authenticatedPage` seeds a user,
+drives the real login flow headlessly (the same Flow API the login UI renders),
+and injects the resulting session cookie into a dedicated browser context:
+
+```ts
+test("member sees the dashboard", async ({ authenticatedPage }) => {
+  const { page, user } = authenticatedPage;
+  await page.goto("/dashboard"); // already signed in as `user`
+});
+```
+
+Underneath sits `seed.session()`, whose `sessionToken` also drives session
+APIs without any browser — backend tests call the instance directly with the
+cookie header (`cookie: __nextgen_session=<sessionToken>`, the SDK
+middleware's own headless pattern). Scope: password flows (the shipped
+`password-first` presets). A flow step demanding anything beyond the user's
+email and password — a challenge, another factor — fails with the step name;
+log in through the UI for those. `seed.identity()` complements registration
+specs: an unused email+password that creates nothing, so the flow under test
+must create the user.
+
+The two in-repo consumers are `apps/demo-next-e2e/playwright.real.config.mts`
+and `apps/console-e2e/playwright.real.config.mts` — run them with
+`moon run demo-next-e2e:e2e-real` / `moon run console-e2e:e2e-real`.
+
+### Composable pieces
+
+`withZitadel()` is sugar over exported building blocks: a supervisor entry
+that calls `startLocalZitadel()` + `writeHandshake()`, and an app-runner entry
+that `waitForHandshake()`s and spawns the dev server with
+`applyAppEnvTemplate(...)` applied. Suites with unusual topologies (or
+non-Playwright runners) compose those functions directly —
+`apps/console/scripts/dev-real.mts` does, seeding a dev environment rather
+than a test suite.
+
+## API
+
+```ts
+import {
+  startLocalZitadel, // boot + bootstrap an ephemeral instance
+  connectZitadel,    // attach to an existing instance via its handle
+  writeHandshake, readHandshakeSync, waitForHandshake,
+} from "@zitadel/testing";
+
+const z = await startLocalZitadel({
+  port,          // default: free port
+  dir,           // default: temp dir, removed on stop (caller dirs are kept)
+  appOrigins,    // registered as the project's previewOrigins
+  useCase,       // "minimal" (default) | "consumer" | "business"
+  preset,        // "password-first" (default)
+  serverBinary,  // ZITADEL_SERVER_BINARY override (in-repo: dist/server/nextgen)
+  keep,          // keep the temp dir for debugging
+});
+
+z.handle;   // serializable: { baseUrl, projectId, projectSecret, schemaId, previewSecret? }
+z.api;      // authenticated @zitadel/api client (bearer = projectSecret)
+z.appEnv;   // { ZITADEL_URL, NEXT_PUBLIC_ZITADEL_PROJECT_ID, ZITADEL_PROJECT_SECRET }
+await z.seedUser({ email?, password?, attributes? }); // → { id, email, password }
+await z.seedUsers(8, { email?, password?, attributes? }); // per-index templates
+z.identity(); // unused { email, password } — creates nothing
+await z.seedSession({ user? }); // → { user, sessionToken, expiresAt, cookie }
+await z.stop(); // stop server, reap embedded Postgres, remove owned temp dir
+```
+
+`connectZitadel(handle)` returns the same surface minus lifecycle — this is
+what the Playwright fixtures use, and what a future remote-instance mode would
+build on.
+
+From `@zitadel/testing/playwright`: the `test`/`expect` fixtures (`seed.user()`
+per test, `zitadel` per worker), plus `withZitadel(options)` returning
+`{ webServer }` for the config, and `nextAppEnv`/`applyAppEnvTemplate` for the
+env-template mechanism described above.
+
+## How it works
+
+- **Lifecycle** shells out to `zitadel start/stop --json` (the CLI owns port
+  preflight, the health wait, process-group stop, and embedded-Postgres
+  reaping). Swapping this for direct library calls later will not change the
+  public API.
+- **Bootstrap** is the server-side half of `zitadel setup`, no files:
+  `POST /projects` (unauthenticated; returns the `projectSecret` used as
+  bearer for everything else) → `POST /schemas` (server assigns the schema id)
+  → `POST /flow_definitions` (default login flow pinned to that schema id).
+  Templates come from `@zitadel/config/defaults`.
+- **Seeding** is `POST /users` (the body carries `$schema: <schema id>`) +
+  `PUT /users/{id}/password` with `isChangeRequired: false`.
+
+## Parallelism model
+
+**One instance per suite, one fresh user per test.** Emails are unique per
+project, so per-test `seed.user()` calls are isolation enough for login-flow
+tests, and tests run fully parallel against the shared instance
+(demonstrated by `demo-next-e2e:e2e-real`, 2 workers).
+
+Measured on an arm64 macBook (dev build, July 2026):
+
+| Operation | Time |
+| --- | --- |
+| Cold boot (fresh data dir: initdb + migrations + health) | ~20–27s |
+| Warm restart (existing data dir) | ~15s |
+| Stop incl. embedded-Postgres reap | ~12s |
+| Bootstrap (project + schema + flow) | ~100ms |
+| Seed one user (create + password) | ~50ms |
+| Full `e2e-real` suite (boot + Next dev + 2 browser tests) | ~25s |
+
+**Instance-per-worker is not worth it for browser e2e**: the app dev server
+boots once with one project's env, and every extra worker would pay the full
+cold boot. It becomes interesting for API-level (no-browser) suites that
+mutate project-wide state; revisit with warm-dir reuse if that need appears.
+
+## Debugging
+
+- `startLocalZitadel({ keep: true })` keeps the temp dir; the server log is at
+  `<dir>/.zitadel/local/server.log`. Boot failures always keep the dir and
+  print its path.
+- A crashed run can orphan a server: `zitadel stop --all` sweeps every
+  CLI-managed runtime on the machine.
+
+## Developing in this repo
+
+Customer installs get the published server binary through `@zitadel/server`'s
+platform packages; the in-repo workspace carries no such binary, so the repo's
+own suites run `moon run server:build` and point the kit at the result via
+`ZITADEL_SERVER_BINARY` (the `withZitadel` option `zitadel.serverBinary` /
+`serverBinaryHint` exists for this). The in-repo moon tasks set
+`NEXTGEN_SERVER_LOGIN_ENABLED=false` / `NEXTGEN_SERVER_CONSOLE_ENABLED=false`
+— the suites drive the app-embedded login, not the server-hosted `/ui/*`.
+Customer installs need none of this.
+
+## Known limitations
+
+- `@zitadel/api`'s client stores auth in module-global state; avoid
+  interleaving calls to *different* instances within one process. Separate
+  processes (Playwright workers) are unaffected.
+- macOS/Linux only for now. Not because of the port preflight (it degrades
+  gracefully where `lsof` is missing) — the untested surface on Windows is the
+  process-group stop and embedded-Postgres lifecycle. Revisit once the local
+  runtime's SQLite default removes the Postgres component.
+
+## Roadmap
+
+This package is deliberately the **local runtime core** — "Testcontainers for
+Zitadel" when the app under test and Playwright share one machine. The layers
+on top, in intended order:
+
+1. **Registration fixtures.** Landed: `zitadel.identity()` plus the
+   demo-next-e2e registration spec driving the real registration UI and
+   verifying the created user through the API. `cli-journey-e2e` keeps the
+   packaged-product registration coverage.
+2. **Email/OTP capture.** `zitadel.email.waitForCode(address)` for
+   verification flows. Blocked on a server-side story (dev SMTP sink or
+   API-exposed codes); password-only flows don't hit this.
+3. **Vitest surface.** Landed from this item: `withZitadel(config)`
+   orchestration, `AppEnvTemplate`/`nextAppEnv`, and the session-mint seed-op
+   (`seed.session()` driving the real flow headlessly, `authenticatedPage` on
+   top). Remaining: a dedicated `@zitadel/testing/vitest` entry once a second
+   backend consumer exists — `sessionToken` already serves backend tests
+   directly.
+4. **Remote mode: ephemeral project on a persistent instance.** For app
+   deployments that cannot reach a local process (preview environments).
+   `bootstrapProject({ baseUrl })` + `connectZitadel(handle)` already compose
+   into this today; formalizing it means cleanup semantics and docs.
+5. **Vercel Sandbox runtime.** A publicly reachable ephemeral instance per
+   preview deployment (e.g. `@zitadel/testing/vercel`), returning the same
+   `InstanceHandle` so fixtures don't change. Gated on a spike: embedded
+   Postgres on the Sandbox image, forwarded proto/host handling, secure
+   cookies + issuer + handoff verification through `sandbox.domain()`,
+   registering the preview URL as an allowed origin post-deploy
+   (`PATCH /projects`), and cleanup that survives failed runs.
+6. **Publishing.** Landed: the consumer journey installs the kit the way a
+   customer would in CI, and the kit ships on the release train (release
+   manifest + changeset `fixed` group), versioned in lockstep with
+   `@zitadel/cli`. Remaining: the Windows decision (deferred until the SQLite
+   local default removes the embedded-Postgres lifecycle) and the stability
+   commitment when the train leaves alpha.
+
+Parked until server support exists: passkey seeding (pre-registered WebAuthn
+credentials). Independent refactor: extract `apps/cli/src/lib/local-server`
+into a shared package and swap the lifecycle shell-out for imports.

package/dist/app-env-D3W0GYhA.d.mts

@@ -0,0 +1,122 @@
+import { ZitadelClient } from "@zitadel/api/client";
+
+//#region src/types.d.ts
+/**
+ * Serializable description of a bootstrapped instance + project. This is the
+ * contract that crosses process boundaries (boot script -> Playwright workers).
+ */
+interface InstanceHandle {
+  baseUrl: string;
+  projectId: string;
+  projectSecret: string;
+  /**
+   * First registered app origin. Flow submissions enforce the project's
+   * origin allowlist, so headless drivers (seedSession) send it as the
+   * Origin header the way a browser request through the app would.
+   */
+  appOrigin?: string;
+  /**
+   * Server-assigned id of the seeded user schema. User documents must
+   * reference it via their `$schema` field, so seeding needs it alongside the
+   * project credential.
+   */
+  schemaId: string;
+  previewSecret?: string;
+}
+interface SeedUserInput {
+  email?: string;
+  password?: string;
+  /** Extra schema-defined user properties merged into the create body. */
+  attributes?: Record<string, unknown>;
+}
+interface SeededUser {
+  id: string;
+  email: string;
+  password: string;
+}
+/** An unused identity: seeded nowhere, ready for registration-flow specs. */
+interface Identity {
+  email: string;
+  password: string;
+}
+/** Injectable mirror of the server's session cookie (session.go). */
+interface SessionCookie {
+  name: string;
+  value: string;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "Lax";
+  path: string;
+}
+interface MintedSession {
+  user: SeededUser;
+  /** Bearer for session management APIs (e.g. `GET /sessions/me`). */
+  sessionToken: string;
+  expiresAt: string;
+  cookie: SessionCookie;
+}
+interface SeedSessionInput extends SeedUserInput {
+  /** Mint for an existing user instead of seeding a fresh one. */
+  user?: SeededUser;
+  /** Specific flow definition; the project default when omitted. */
+  flowDefinitionName?: string;
+  /**
+   * Origin header for the flow calls (must be on the project's allowlist).
+   * Defaults to the handle's registered app origin; the Playwright fixtures
+   * pass the suite's baseURL.
+   */
+  origin?: string;
+}
+interface SeedUsersTemplate {
+  email?: (index: number) => string;
+  password?: (index: number) => string;
+  attributes?: (index: number) => Record<string, unknown>;
+}
+interface ConnectedZitadel {
+  handle: InstanceHandle;
+  /** Authenticated platform API client (bearer = project secret). */
+  api: ZitadelClient;
+  /** Env vars an SDK-based app needs to talk to this instance/project. */
+  appEnv: Record<string, string>;
+  seedUser(input?: SeedUserInput): Promise<SeededUser>;
+  /** Batch-seed users; the template makes fixture data deterministic. */
+  seedUsers(count: number, template?: SeedUsersTemplate): Promise<SeededUser[]>;
+  /** A unique unused email+password — nothing is created on the instance. */
+  identity(): Identity;
+  /**
+   * Seed (or take) a user and drive the real login flow headlessly to a
+   * session: tests inject `cookie` to start authenticated, backend tests use
+   * `sessionToken` directly. Password flows only.
+   */
+  seedSession(input?: SeedSessionInput): Promise<MintedSession>;
+}
+interface LocalZitadelRuntime {
+  port: number;
+  pid: number;
+  /** State directory holding `.zitadel/local/` (data dir, logs, runtime.json). */
+  dir: string;
+  logPath: string;
+}
+interface LocalZitadel extends ConnectedZitadel, AsyncDisposable {
+  runtime: LocalZitadelRuntime;
+  stop(): Promise<void>;
+}
+//#endregion
+//#region src/app-env.d.ts
+/**
+ * Declarative mapping from an app's env var names to InstanceHandle fields.
+ * A template (not a function) so it can cross process boundaries: the
+ * Playwright config serializes it into the app-runner's environment, where it
+ * is applied to the handle read from the handshake file.
+ */
+type AppEnvTemplate = Record<string, keyof InstanceHandle>;
+/**
+ * The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own
+ * template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`
+ * names, for example.
+ */
+declare const nextAppEnv: AppEnvTemplate;
+declare function applyAppEnvTemplate(template: AppEnvTemplate, handle: InstanceHandle): Record<string, string>;
+//#endregion
+export { Identity as a, LocalZitadelRuntime as c, SeedUserInput as d, SeedUsersTemplate as f, ConnectedZitadel as i, MintedSession as l, SessionCookie as m, applyAppEnvTemplate as n, InstanceHandle as o, SeededUser as p, nextAppEnv as r, LocalZitadel as s, AppEnvTemplate as t, SeedSessionInput as u };
+//# sourceMappingURL=app-env-D3W0GYhA.d.mts.map

package/dist/app-env-D3W0GYhA.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-env-D3W0GYhA.d.mts","names":[],"sources":["../src/types.ts","../src/app-env.ts"],"mappings":";;;;;AAMA;;UAAiB,cAAA;EACf,OAAA;EACA,SAAA;EACA,aAAA;EAAA;;;;;EAMA,SAAA;EAUe;;;;;EAJf,QAAA;EACA,aAAA;AAAA;AAAA,UAGe,aAAA;EACf,KAAA;EACA,QAAA;EAKyB;EAHzB,UAAA,GAAa,MAAA;AAAA;AAAA,UAGE,UAAA;EACf,EAAA;EACA,KAAA;EACA,QAAA;AAAA;AAIF;AAAA,UAAiB,QAAA;EACf,KAAA;EACA,QAAA;AAAA;AAIF;AAAA,UAAiB,aAAA;EACf,IAAA;EACA,KAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA,EAAM,UAAA;EAJF;EAMJ,YAAA;EACA,SAAA;EACA,MAAA,EAAQ,aAAA;AAAA;AAAA,UAGO,gBAAA,SAAyB,aAAA;EAPlC;EASN,IAAA,GAAO,UAAA;EANP;EAQA,kBAAA;EAPQ;;;AAGV;;EAUE,MAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,IAAS,KAAA;EACT,QAAA,IAAY,KAAA;EACZ,UAAA,IAAc,KAAA,aAAkB,MAAA;AAAA;AAAA,UAGjB,gBAAA;EACf,MAAA,EAAQ,cAAA;EAPO;EASf,GAAA,EAAK,aAAA;;EAEL,MAAA,EAAQ,MAAA;EACR,QAAA,CAAS,KAAA,GAAQ,aAAA,GAAgB,OAAA,CAAQ,UAAA;EAXhC;EAaT,SAAA,CAAU,KAAA,UAAe,QAAA,GAAW,iBAAA,GAAoB,OAAA,CAAQ,UAAA;EAZpD;EAcZ,QAAA,IAAY,QAAA;EAbE;;;;AAGhB;EAgBE,WAAA,CAAY,KAAA,GAAQ,gBAAA,GAAmB,OAAA,CAAQ,aAAA;AAAA;AAAA,UAGhC,mBAAA;EACf,IAAA;EACA,GAAA;EAfiB;EAiBjB,GAAA;EACA,OAAA;AAAA;AAAA,UAGe,YAAA,SAAqB,gBAAA,EAAkB,eAAA;EACtD,OAAA,EAAS,mBAAA;EACT,IAAA,IAAQ,OAAA;AAAA;;;;;AAxGV;;;;KCEY,cAAA,GAAiB,MAAA,eAAqB,cAAA;;;;;;cAOrC,UAAA,EAAY,cAAA;AAAA,iBAMT,mBAAA,CACd,QAAA,EAAU,cAAA,EACV,MAAA,EAAQ,cAAA,GACP,MAAA"}

package/dist/app-runner.cjs

@@ -0,0 +1,36 @@
+const require_handshake = require("./handshake-CggSIoxF.cjs");
+const require_orchestration = require("./orchestration-D7QBgQ0l.cjs");
+let node_child_process = require("node:child_process");
+//#region src/app-runner.ts
+/**
+* Playwright webServer entry generated by `withZitadel()`: waits for the
+* supervisor's handshake, then runs the app's dev server with the instance
+* env applied. Signals forward to the child so Playwright teardown stops the
+* app cleanly. Configuration arrives as JSON in ZITADEL_TESTING_APP_RUNNER.
+*/
+const LOG = "[zitadel-testing-app]";
+async function main() {
+	const config = require_orchestration.parseAppRunnerConfig(process.env[require_orchestration.APP_RUNNER_CONFIG_ENV]);
+	const handle = await require_handshake.waitForHandshake(require_orchestration.requireHandshakePath(process.env), config.handshakeTimeoutMs ?? 18e4);
+	console.log(`${LOG} starting ${config.command.join(" ")} against ${handle.baseUrl}`);
+	const [bin, ...args] = config.command;
+	const child = (0, node_child_process.spawn)(bin, args, {
+		cwd: config.cwd,
+		stdio: "inherit",
+		env: {
+			...process.env,
+			...require_handshake.applyAppEnvTemplate(config.env ?? {}, handle)
+		}
+	});
+	child.on("exit", (code) => {
+		process.exit(code ?? 1);
+	});
+	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => child.kill(signal));
+}
+main().catch((error) => {
+	console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
+//#endregion
+
+//# sourceMappingURL=app-runner.cjs.map

package/dist/app-runner.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-runner.cjs","names":["parseAppRunnerConfig","APP_RUNNER_CONFIG_ENV","waitForHandshake","requireHandshakePath","applyAppEnvTemplate"],"sources":["../src/app-runner.ts"],"sourcesContent":["/**\n * Playwright webServer entry generated by `withZitadel()`: waits for the\n * supervisor's handshake, then runs the app's dev server with the instance\n * env applied. Signals forward to the child so Playwright teardown stops the\n * app cleanly. Configuration arrives as JSON in ZITADEL_TESTING_APP_RUNNER.\n */\nimport { spawn } from \"node:child_process\";\n\nimport { applyAppEnvTemplate } from \"./app-env\";\nimport { waitForHandshake } from \"./handshake\";\nimport { APP_RUNNER_CONFIG_ENV, parseAppRunnerConfig, requireHandshakePath } from \"./orchestration\";\n\nconst LOG = \"[zitadel-testing-app]\";\n\nasync function main(): Promise<void> {\n  const config = parseAppRunnerConfig(process.env[APP_RUNNER_CONFIG_ENV]);\n  const handshakePath = requireHandshakePath(process.env);\n\n  const handle = await waitForHandshake(handshakePath, config.handshakeTimeoutMs ?? 180_000);\n  console.log(`${LOG} starting ${config.command.join(\" \")} against ${handle.baseUrl}`);\n\n  const [bin, ...args] = config.command;\n  const child = spawn(bin as string, args, {\n    cwd: config.cwd,\n    stdio: \"inherit\",\n    env: {\n      ...process.env,\n      ...applyAppEnvTemplate(config.env ?? {}, handle),\n    },\n  });\n  child.on(\"exit\", (code) => {\n    process.exit(code ?? 1);\n  });\n  for (const signal of [\"SIGTERM\", \"SIGINT\"] as const) {\n    process.on(signal, () => child.kill(signal));\n  }\n}\n\nmain().catch((error: unknown) => {\n  console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n});\n"],"mappings":";;;;;;;;;;AAYA,MAAM,MAAM;AAEZ,eAAe,OAAsB;CACnC,MAAM,SAASA,sBAAAA,qBAAqB,QAAQ,IAAIC,sBAAAA,uBAAuB;CAGvE,MAAM,SAAS,MAAMC,kBAAAA,iBAFCC,sBAAAA,qBAAqB,QAAQ,IAEA,EAAE,OAAO,sBAAsB,KAAQ;AAC1F,SAAQ,IAAI,GAAG,IAAI,YAAY,OAAO,QAAQ,KAAK,IAAI,CAAC,WAAW,OAAO,UAAU;CAEpF,MAAM,CAAC,KAAK,GAAG,QAAQ,OAAO;CAC9B,MAAM,SAAA,GAAA,mBAAA,OAAc,KAAe,MAAM;EACvC,KAAK,OAAO;EACZ,OAAO;EACP,KAAK;GACH,GAAG,QAAQ;GACX,GAAGC,kBAAAA,oBAAoB,OAAO,OAAO,EAAE,EAAE,OAAO;GACjD;EACF,CAAC;AACF,OAAM,GAAG,SAAS,SAAS;AACzB,UAAQ,KAAK,QAAQ,EAAE;GACvB;AACF,MAAK,MAAM,UAAU,CAAC,WAAW,SAAS,CACxC,SAAQ,GAAG,cAAc,MAAM,KAAK,OAAO,CAAC;;AAIhD,MAAM,CAAC,OAAO,UAAmB;AAC/B,SAAQ,MAAM,GAAG,IAAI,GAAG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GAAG;AACjF,SAAQ,KAAK,EAAE;EACf"}

package/dist/app-runner.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/app-runner.mjs

@@ -0,0 +1,37 @@
+import { i as applyAppEnvTemplate, n as waitForHandshake } from "./handshake-BPtWruO8.mjs";
+import { i as parseAppRunnerConfig, o as requireHandshakePath, t as APP_RUNNER_CONFIG_ENV } from "./orchestration-C640_1Lg.mjs";
+import { spawn } from "node:child_process";
+//#region src/app-runner.ts
+/**
+* Playwright webServer entry generated by `withZitadel()`: waits for the
+* supervisor's handshake, then runs the app's dev server with the instance
+* env applied. Signals forward to the child so Playwright teardown stops the
+* app cleanly. Configuration arrives as JSON in ZITADEL_TESTING_APP_RUNNER.
+*/
+const LOG = "[zitadel-testing-app]";
+async function main() {
+	const config = parseAppRunnerConfig(process.env[APP_RUNNER_CONFIG_ENV]);
+	const handle = await waitForHandshake(requireHandshakePath(process.env), config.handshakeTimeoutMs ?? 18e4);
+	console.log(`${LOG} starting ${config.command.join(" ")} against ${handle.baseUrl}`);
+	const [bin, ...args] = config.command;
+	const child = spawn(bin, args, {
+		cwd: config.cwd,
+		stdio: "inherit",
+		env: {
+			...process.env,
+			...applyAppEnvTemplate(config.env ?? {}, handle)
+		}
+	});
+	child.on("exit", (code) => {
+		process.exit(code ?? 1);
+	});
+	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => child.kill(signal));
+}
+main().catch((error) => {
+	console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=app-runner.mjs.map

package/dist/app-runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-runner.mjs","names":[],"sources":["../src/app-runner.ts"],"sourcesContent":["/**\n * Playwright webServer entry generated by `withZitadel()`: waits for the\n * supervisor's handshake, then runs the app's dev server with the instance\n * env applied. Signals forward to the child so Playwright teardown stops the\n * app cleanly. Configuration arrives as JSON in ZITADEL_TESTING_APP_RUNNER.\n */\nimport { spawn } from \"node:child_process\";\n\nimport { applyAppEnvTemplate } from \"./app-env\";\nimport { waitForHandshake } from \"./handshake\";\nimport { APP_RUNNER_CONFIG_ENV, parseAppRunnerConfig, requireHandshakePath } from \"./orchestration\";\n\nconst LOG = \"[zitadel-testing-app]\";\n\nasync function main(): Promise<void> {\n  const config = parseAppRunnerConfig(process.env[APP_RUNNER_CONFIG_ENV]);\n  const handshakePath = requireHandshakePath(process.env);\n\n  const handle = await waitForHandshake(handshakePath, config.handshakeTimeoutMs ?? 180_000);\n  console.log(`${LOG} starting ${config.command.join(\" \")} against ${handle.baseUrl}`);\n\n  const [bin, ...args] = config.command;\n  const child = spawn(bin as string, args, {\n    cwd: config.cwd,\n    stdio: \"inherit\",\n    env: {\n      ...process.env,\n      ...applyAppEnvTemplate(config.env ?? {}, handle),\n    },\n  });\n  child.on(\"exit\", (code) => {\n    process.exit(code ?? 1);\n  });\n  for (const signal of [\"SIGTERM\", \"SIGINT\"] as const) {\n    process.on(signal, () => child.kill(signal));\n  }\n}\n\nmain().catch((error: unknown) => {\n  console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);\n  process.exit(1);\n});\n"],"mappings":";;;;;;;;;;AAYA,MAAM,MAAM;AAEZ,eAAe,OAAsB;CACnC,MAAM,SAAS,qBAAqB,QAAQ,IAAI,uBAAuB;CAGvE,MAAM,SAAS,MAAM,iBAFC,qBAAqB,QAAQ,IAEA,EAAE,OAAO,sBAAsB,KAAQ;AAC1F,SAAQ,IAAI,GAAG,IAAI,YAAY,OAAO,QAAQ,KAAK,IAAI,CAAC,WAAW,OAAO,UAAU;CAEpF,MAAM,CAAC,KAAK,GAAG,QAAQ,OAAO;CAC9B,MAAM,QAAQ,MAAM,KAAe,MAAM;EACvC,KAAK,OAAO;EACZ,OAAO;EACP,KAAK;GACH,GAAG,QAAQ;GACX,GAAG,oBAAoB,OAAO,OAAO,EAAE,EAAE,OAAO;GACjD;EACF,CAAC;AACF,OAAM,GAAG,SAAS,SAAS;AACzB,UAAQ,KAAK,QAAQ,EAAE;GACvB;AACF,MAAK,MAAM,UAAU,CAAC,WAAW,SAAS,CACxC,SAAQ,GAAG,cAAc,MAAM,KAAK,OAAO,CAAC;;AAIhD,MAAM,CAAC,OAAO,UAAmB;AAC/B,SAAQ,MAAM,GAAG,IAAI,GAAG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GAAG;AACjF,SAAQ,KAAK,EAAE;EACf"}

package/dist/handshake-BPtWruO8.mjs

@@ -0,0 +1,69 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { readFileSync } from "node:fs";
+import { setTimeout } from "node:timers/promises";
+//#region src/app-env.ts
+/**
+* The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own
+* template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`
+* names, for example.
+*/
+const nextAppEnv = {
+	ZITADEL_URL: "baseUrl",
+	NEXT_PUBLIC_ZITADEL_PROJECT_ID: "projectId",
+	ZITADEL_PROJECT_SECRET: "projectSecret"
+};
+function applyAppEnvTemplate(template, handle) {
+	const env = {};
+	for (const [name, field] of Object.entries(template)) {
+		const value = handle[field];
+		if (typeof value !== "string" || value.length === 0) throw new Error(`app env template maps "${name}" to handle field "${field}", which the instance handle does not carry`);
+		env[name] = value;
+	}
+	return env;
+}
+//#endregion
+//#region src/handshake.ts
+/**
+* The handshake file carries an InstanceHandle across process boundaries:
+* written by the script that boots + bootstraps the instance, read by
+* Playwright workers (fixtures) and the app dev-server wrapper.
+*/
+async function writeHandshake(path, handle) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(handle, null, 2)}\n`, { mode: 384 });
+}
+function readHandshakeSync(path) {
+	const contents = readFileSync(path, "utf8");
+	let value;
+	try {
+		value = JSON.parse(contents);
+	} catch (error) {
+		throw new Error(`handshake file ${path} contains invalid JSON: ${error.message}`, { cause: error });
+	}
+	return validateHandle(value, path);
+}
+async function waitForHandshake(path, timeoutMs = 6e4) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) try {
+		return validateHandle(JSON.parse(await readFile(path, "utf8")), path);
+	} catch (error) {
+		if (Date.now() >= deadline) throw new Error(`handshake file not readable within ${timeoutMs}ms: ${path} (${error.message})`, { cause: error });
+		await setTimeout(250);
+	}
+}
+function validateHandle(value, source) {
+	const handle = value;
+	for (const field of [
+		"baseUrl",
+		"projectId",
+		"projectSecret",
+		"schemaId"
+	]) if (typeof handle?.[field] !== "string" || handle[field].length === 0) throw new Error(`handshake file ${source} is missing "${field}"`);
+	if (!URL.canParse(handle.baseUrl)) throw new Error(`handshake file ${source} has a malformed "baseUrl": ${handle.baseUrl}`);
+	return handle;
+}
+//#endregion
+export { nextAppEnv as a, applyAppEnvTemplate as i, waitForHandshake as n, writeHandshake as r, readHandshakeSync as t };
+
+//# sourceMappingURL=handshake-BPtWruO8.mjs.map

package/dist/handshake-BPtWruO8.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-BPtWruO8.mjs","names":["sleep"],"sources":["../src/app-env.ts","../src/handshake.ts"],"sourcesContent":["import type { InstanceHandle } from \"./types\";\n\n/**\n * Declarative mapping from an app's env var names to InstanceHandle fields.\n * A template (not a function) so it can cross process boundaries: the\n * Playwright config serializes it into the app-runner's environment, where it\n * is applied to the handle read from the handshake file.\n */\nexport type AppEnvTemplate = Record<string, keyof InstanceHandle>;\n\n/**\n * The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own\n * template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`\n * names, for example.\n */\nexport const nextAppEnv: AppEnvTemplate = {\n  ZITADEL_URL: \"baseUrl\",\n  NEXT_PUBLIC_ZITADEL_PROJECT_ID: \"projectId\",\n  ZITADEL_PROJECT_SECRET: \"projectSecret\",\n};\n\nexport function applyAppEnvTemplate(\n  template: AppEnvTemplate,\n  handle: InstanceHandle,\n): Record<string, string> {\n  const env: Record<string, string> = {};\n  for (const [name, field] of Object.entries(template)) {\n    const value = handle[field];\n    if (typeof value !== \"string\" || value.length === 0) {\n      // Fail instead of silently dropping the var: an app booted without one\n      // of its env vars produces a much harder-to-read failure downstream.\n      throw new Error(\n        `app env template maps \"${name}\" to handle field \"${field}\", which the instance handle does not carry`,\n      );\n    }\n    env[name] = value;\n  }\n  return env;\n}\n","import { readFileSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { setTimeout as sleep } from \"node:timers/promises\";\n\nimport type { InstanceHandle } from \"./types\";\n\n/**\n * The handshake file carries an InstanceHandle across process boundaries:\n * written by the script that boots + bootstraps the instance, read by\n * Playwright workers (fixtures) and the app dev-server wrapper.\n */\nexport async function writeHandshake(path: string, handle: InstanceHandle): Promise<void> {\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, `${JSON.stringify(handle, null, 2)}\\n`, { mode: 0o600 });\n}\n\nexport function readHandshakeSync(path: string): InstanceHandle {\n  const contents = readFileSync(path, \"utf8\");\n  let value: unknown;\n  try {\n    value = JSON.parse(contents);\n  } catch (error) {\n    throw new Error(`handshake file ${path} contains invalid JSON: ${(error as Error).message}`, {\n      cause: error,\n    });\n  }\n  return validateHandle(value, path);\n}\n\nexport async function waitForHandshake(path: string, timeoutMs = 60_000): Promise<InstanceHandle> {\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    try {\n      return validateHandle(JSON.parse(await readFile(path, \"utf8\")), path);\n    } catch (error) {\n      if (Date.now() >= deadline) {\n        throw new Error(\n          `handshake file not readable within ${timeoutMs}ms: ${path} (${(error as Error).message})`,\n          { cause: error },\n        );\n      }\n      await sleep(250);\n    }\n  }\n}\n\nfunction validateHandle(value: unknown, source: string): InstanceHandle {\n  const handle = value as Partial<InstanceHandle> | null;\n  for (const field of [\"baseUrl\", \"projectId\", \"projectSecret\", \"schemaId\"] as const) {\n    if (typeof handle?.[field] !== \"string\" || handle[field].length === 0) {\n      throw new Error(`handshake file ${source} is missing \"${field}\"`);\n    }\n  }\n  if (!URL.canParse(handle.baseUrl as string)) {\n    throw new Error(`handshake file ${source} has a malformed \"baseUrl\": ${handle.baseUrl}`);\n  }\n  return handle as InstanceHandle;\n}\n"],"mappings":";;;;;;;;;;AAeA,MAAa,aAA6B;CACxC,aAAa;CACb,gCAAgC;CAChC,wBAAwB;CACzB;AAED,SAAgB,oBACd,UACA,QACwB;CACxB,MAAM,MAA8B,EAAE;AACtC,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,SAAS,EAAE;EACpD,MAAM,QAAQ,OAAO;AACrB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAGhD,OAAM,IAAI,MACR,0BAA0B,KAAK,qBAAqB,MAAM,6CAC3D;AAEH,MAAI,QAAQ;;AAEd,QAAO;;;;;;;;;ACzBT,eAAsB,eAAe,MAAc,QAAuC;AACxF,OAAM,MAAM,QAAQ,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC/C,OAAM,UAAU,MAAM,GAAG,KAAK,UAAU,QAAQ,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAO,CAAC;;AAGhF,SAAgB,kBAAkB,MAA8B;CAC9D,MAAM,WAAW,aAAa,MAAM,OAAO;CAC3C,IAAI;AACJ,KAAI;AACF,UAAQ,KAAK,MAAM,SAAS;UACrB,OAAO;AACd,QAAM,IAAI,MAAM,kBAAkB,KAAK,0BAA2B,MAAgB,WAAW,EAC3F,OAAO,OACR,CAAC;;AAEJ,QAAO,eAAe,OAAO,KAAK;;AAGpC,eAAsB,iBAAiB,MAAc,YAAY,KAAiC;CAChG,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,SACE,KAAI;AACF,SAAO,eAAe,KAAK,MAAM,MAAM,SAAS,MAAM,OAAO,CAAC,EAAE,KAAK;UAC9D,OAAO;AACd,MAAI,KAAK,KAAK,IAAI,SAChB,OAAM,IAAI,MACR,sCAAsC,UAAU,MAAM,KAAK,IAAK,MAAgB,QAAQ,IACxF,EAAE,OAAO,OAAO,CACjB;AAEH,QAAMA,WAAM,IAAI;;;AAKtB,SAAS,eAAe,OAAgB,QAAgC;CACtE,MAAM,SAAS;AACf,MAAK,MAAM,SAAS;EAAC;EAAW;EAAa;EAAiB;EAAW,CACvE,KAAI,OAAO,SAAS,WAAW,YAAY,OAAO,OAAO,WAAW,EAClE,OAAM,IAAI,MAAM,kBAAkB,OAAO,eAAe,MAAM,GAAG;AAGrE,KAAI,CAAC,IAAI,SAAS,OAAO,QAAkB,CACzC,OAAM,IAAI,MAAM,kBAAkB,OAAO,8BAA8B,OAAO,UAAU;AAE1F,QAAO"}