Docs

Test your app's sign-in

Run end-to-end tests of your app against a real local Zitadel with @zitadel/testing, its Playwright fixtures and login helpers.

@zitadel/testing is the test kit for apps that use Zitadel. It boots a real Zitadel server from your test run, with SQLite and without Docker. It creates a project with the default login flow, then seeds users and sessions through the API. Its Playwright fixtures and helpers drive the real login in a browser.

This guide adds two tests to a Next.js app: one that signs a seeded user in, and one that starts signed in and tests a page behind the sign-in.

The kit is in preview: until 1.0.0, a minor version can change its API, and its release note marks that Breaking:. It runs on macOS and Linux only. Its full API is in its README.

Before you start

  • A Next.js app from zitadel setup (Quickstart). Next.js is the only framework whose test setup an end-to-end run of this repository proves; see Other frameworks.
  • Node.js 24 or later, as for the CLI.

The kit does not use the project setup created or the runtime zitadel start runs. Each test run boots its own Zitadel server on a port you choose and creates a fresh project in it. When the run ends, the kit stops that server and deletes its data.

Let the CLI add the tests

In a Next.js app that setup wired up, tests add writes the config and both tests this guide shows. It adds the kit and Playwright as dev dependencies, installs them, and adds a test:e2e script:

npx @zitadel/cli@latest tests add

Then follow its next steps: install Playwright's Chromium, and run npm run test:e2e. The sections below show what it writes, for an app you wire up by hand.

Install the kit

Install the kit and Playwright as dev dependencies, then Playwright's Chromium:

npm install --save-dev @zitadel/testing@latest @playwright/test
npx playwright install chromium

The kit runs the zitadel CLI, which finds the @zitadel/server binary on its own. There is no binary path or environment variable to set.

Add the kit's files and Playwright's output to .gitignore. .zitadel-testing/ holds the test server's handshake file, which carries the test project's secret:

.gitignore
.zitadel-testing/
test-results/
playwright-report/

Configure Playwright

withZitadel() returns the webServer entries that boot the test server and then your app's dev server against it. It hands the app the test server's URL, project ID and secret through environment variables, which win over the values setup wrote to .env.local:

playwright.config.mts
import { defineConfig } from "@playwright/test";
import { nextAppEnv, withZitadel } from "@zitadel/testing/playwright";

const appOrigin = "http://localhost:3100";

export default defineConfig({
  testDir: "./e2e",
  use: { baseURL: appOrigin },
  ...withZitadel({
    configDir: import.meta.dirname,
    port: 8092,
    appOrigin,
    app: {
      command: ["npx", "next", "dev", "--hostname", "localhost", "--port", "3100"],
      cwd: import.meta.dirname,
      readyPath: "/login",
      env: nextAppEnv,
    },
  }),
});
  • port is the test server's port. It must be free, so pick one your local runtime does not use (that one listens on 8080 by default).
  • appOrigin is where the test run serves your app. The kit registers it as the test project's origin. Use a port other than your dev server's, so both can run at once.
  • readyPath is a page Playwright polls until the app answers.
  • nextAppEnv maps the test server to the variables a Next.js app reads.

The .mts extension makes Node load the file as an ES module, which import.meta.dirname needs. Without it, an app whose package.json has no "type": "module" fails to load the config.

Sign a seeded user in

seed.user() creates a user with a unique email and a password, ready to sign in. loginWithPassword() fills the login component's identifier and password steps:

e2e/sign-in.spec.ts
import { expect, loginWithPassword, test } from "@zitadel/testing/playwright";

test("a seeded user signs in with their password", async ({ page, seed }) => {
  const user = await seed.user();

  await page.goto("/login");
  await loginWithPassword(page, user);

  await expect(page).toHaveURL(/\/profile(?:[/?#]|$)/, { timeout: 30_000 });
});

The helpers find the login component's controls by their automation hooks, not by their text, so they keep working when you change copy or locale. They never check your app's state: assert what your app shows after the sign-in yourself.

Start a test signed in

Most tests of your app's pages should not test the sign-in again. The authenticatedPage fixture seeds a user, signs it in without a browser, and puts the session cookie into a page of its own:

e2e/signed-in.spec.ts
import { expect, test } from "@zitadel/testing/playwright";

test("a signed-in user sees the profile page", async ({ authenticatedPage }) => {
  const { page } = authenticatedPage;

  await page.goto("/profile");

  await expect(page).toHaveURL(/\/profile(?:[/?#]|$)/);
  await expect(page.getByTestId("zitadel-session-logout")).toBeVisible({ timeout: 30_000 });
});

setup protects /profile, so a signed-out visitor is sent to /login instead, and the test fails. zitadel-session-logout is the sign-out control of the session card on that page. The default page fixture stays signed out, for tests of the sign-in itself.

Run the tests

npx playwright test

Both tests pass. The first run takes longest: the test server creates its database, then your app's dev server compiles. Each test gets its own user, so tests run in parallel against the one test server.

More the kit can do

The README documents each of these with an example:

Other frameworks

Only the Next.js setup above is proven by an end-to-end run. For another framework, the app must take the test server's URL, project ID and secret from the environment withZitadel() hands it. A Vite app from zitadel setup (React, Vue, Solid, Svelte or Qwik) does, so pass viteAppEnv as the app's env. Its dev proxy reads ZITADEL_URL from the process environment first, then from .env.development.local, .env.development, .env.local and .env. Without one, it uses the server setup ran against. A Vite app set up by an older CLI has that server fixed in vite.config.*. Run zitadel doctor --fix to make it read ZITADEL_URL too. The README explains the env template: Quick start.

Limits

  • Password flows only, without a browser. authenticatedPage and seed.session() complete the default password flows. A step that asks for anything else, such as a code or a second factor, fails with the step's name. Drive those flows in the browser instead.
  • No email or SMS codes. The kit cannot read a verification code yet, so a flow that sends one cannot run to the end.
  • One test server per process. The kit's API client keeps its credentials per process. Do not call two test servers from one process; Playwright's workers are separate processes.
  • macOS and Linux. Windows is not supported yet.

When a run fails

  • The test server does not boot. Another process holds its port: choose another, or stop what holds it. npx @zitadel/cli@latest stop --all stops every runtime the CLI started, including ones a crashed run left behind. A failed boot keeps the test server's directory and prints its path.
  • Playwright says the app's URL is already in use. The kit always starts the app itself. Stop the dev server on appOrigin's port, or move appOrigin to a free port.
  • You need the server's log of a run that booted. Give the test server a directory of your own, which the kit keeps: add zitadel: { dir: join(import.meta.dirname, ".zitadel-testing", "server") } to withZitadel()'s options, with join from node:path. The log is .zitadel/local/server.log in that directory.

Was this helpful?