Skip to content
Docs
Changelog

End-to-end tests

Web and iOS end-to-end tests with e2e on the built Worker and one locked local database that a killed run never leaves behind.

Markdown

apps/e2e runs e2e against the app the way production runs it: the built Worker in local workerd, on a temporary PostgreSQL cluster, with email verification on. The web suite drives Chromium through @e2e-dev/web; the mobile suite drives the Expo development build on an iOS simulator through @e2e-dev/mobile (callstack's agent-device). Tests use exact locators built from the apps' own English catalogs; agent steps are used where they add something, and replay from a cache.

Run

pnpm --filter web build                              # the suites test dist/, they do not build it
pnpm --filter @template-cloudflare/e2e test:web      # or: pnpm test:e2e (builds first)
pnpm --filter @template-cloudflare/e2e test:mobile   # iOS, needs a current development build
pnpm --filter @template-cloudflare/e2e doctor:web    # what e2e run needs, without starting anything
pnpm --filter @template-cloudflare/e2e doctor:mobile

Pass e2e run options after the script (test:web tests/web/todos.e2e.ts, --headed, --trace on). Reports, JUnit, traces, videos of failed tests and the stack log go to apps/e2e/.e2e/ (ignored). The scripts set E2E_TELEMETRY_DISABLED=1; set it yourself when you call e2e directly.

SuiteFlows
Web (e2e.config.ts)Sign up, the check-your-inbox screen, verification, sign in; the seeded Member signs in once (a setup test saves the session); create and delete a todo; /docs renders; an anonymous /dashboard goes to /login; the same todo flow driven by agent goals.
Mobile (e2e.mobile.config.ts)The seeded Member signs in (after onboarding, the first time on a simulator) and finds a todo created for them through the RPC API in the todo list.

One stack, and nothing left behind

The app command of both suites is scripts/e2e-stack.mjs. It runs scripts/test-local-postgres.mjs --serve with wrangler dev -c dist/server/wrangler.json --local --local-upstream as the workerd smoke does, on a free port the runner picks, plus Metro for the mobile suite. All tests share that one server and database (workers: 1).

  • One stack per machine. The stack holds a lock directory, template-e2e-stack.lock in the OS temp directory, from its first line to its last. A second run, from any checkout, fails at once with APP_UNREACHABLE quoting refused: template-e2e-stack is held by pid <pid> …; wait for that run or kill -TERM <pid>.
  • A lock whose owner is dead is taken over. The owner is checked by pid and start time, so a reused pid does not count. The new run first stops what the dead one recorded in the lock (Metro's process group, the database harness) and every orphaned cluster with its served wrangler/workerd group, then starts.
  • A killed runner takes its stack down. The runner stops its app command on every exit path it sees; for SIGKILL, a closed terminal or an agent's timeout it sees none, so the stack watches its parent and stops itself within a second.
  • Nothing on disk. The Worker's variables, KV/cache state (--persist-to) and the stack record live in the lock directory and go with it; the cluster directory is removed; the verification emails miniflare writes under dist/server/.wrangler/tmp/email are removed.

node scripts/e2e-cleanup-proof.mjs proves it: a normal run, a kill -9 of the runner, a kill -9 of the runner, the stack and the harness followed by a run that sweeps and passes, and two runs started together. Each prints the lock, cluster directories, listening ports and stack processes left afterwards, which must be none.

Accounts and secrets

Nothing reads an .env file or reaches a remote database. The stack writes a fresh BETTER_AUTH_SECRET and the local database URL for the Worker into the lock directory. The test accounts in apps/e2e/support/accounts.ts exist only in the run's database: the seeded Member is signed up through the API and verified in that database (as a person opening the emailed link would), the sign-up flow verifies its own address the same way. Passwords reach the browser through credentials and secrets, so reports, traces and model input show <secret:…>.

Agent steps and the model

todos.agent.e2e.ts drives the todo screen by goals (agent.act), which shows whether the screen is operable from its accessibility tree alone. It needs a model that supports tool calls and images (apps/e2e/support/model.ts):

  • Locally, sign in once with a ChatGPT Plus or Pro plan: pnpm --filter @template-cloudflare/e2e exec e2e login openai (stored in ~/.config/e2e/oauth.json).
  • In CI, an OPENAI_API_KEY repository secret.
  • E2E_MODEL picks another model id the account serves (e2e models openai).

Without a model the test is skipped with that reason and every locator test still runs. A goal that a later check confirms is recorded in apps/e2e/recordings/ and replays without a model call; commit the recordings once a model has made them (CI reads them, never writes), and review them like test code. The delete item carries data-agent-confirm: that gates the in-page ui-sdk agent (Agent on the live page), not this runner, which presses the menu item like a person.

Mobile

scripts/e2e-mobile.mjs picks the simulator, under its own lock (template-e2e-simulator.lock):

  • a booted simulator that has the development build (<BUNDLE_IDENTIFIER>.dev) is reused and stays booted;
  • otherwise a shut-down one that has it is booted and shut down again afterwards, also by the next run when this one was killed;
  • a simulator without the build is never touched, so another project's run is not disturbed. Nothing is created, installed or built for you. E2E_DEVICE=<udid> picks one.

The engine starts an agent-device daemon that outlives the run; the one this checkout's install starts is stopped afterwards. agent-device replaces a daemon of another version in its state directory, and ~/.agent-device is shared by every project on the machine, so the wrapper gives the suite its own (template-e2e-agent-device in the OS temp dir; AGENT_DEVICE_STATE_DIR overrides it) and never replaces or stops another project's daemon. The development build must contain the native modules the JavaScript needs: an older build fails on launch with Cannot find native module …. Build a current one with pnpm --filter mobile exec expo run:ios (it writes apps/mobile/ios; delete it afterwards) or install an EAS development build. A simulator build made with CODE_SIGNING_ALLOWED=NO has no entitlements, so SecureStore fails (A required entitlement isn't present) and no session is kept; keep Xcode's ad-hoc signing. Metro listens on 8082 (E2E_METRO_PORT) and bundles EXPO_PUBLIC_SERVER_URL for the stack's Worker; the Worker trusts the <scheme>-dev:// origin as a preview does.

CI

.github/workflows/e2e.yml runs the web suite on every same-repository pull request and every push to main: the runner's own PostgreSQL server binaries, the built Worker, Chromium, and the run's report.json, junit.xml, results/ and logs/ from apps/e2e/.e2e/ uploaded as the e2e-web artifact (never sessions/, which holds signed-in browser state). It has no deploy or database secret; OPENAI_API_KEY is optional. The job follows what e2e init --ci github-actions writes for e2e 0.24, adapted to the repository's pinned actions, pnpm, the local stack and same-repository pull requests; it has no iOS or Android job, so the iOS suite runs locally.

Key files

Edit on GitHubDocumentation is in English.
Cookie settings
We use essential cookies to make our app work. With your consent, we also use optional cookies to improve your experience.

Read our Cookie Policy and Privacy Policy.