app-e2e-tests

App E2E tests (environment-aware)

One suite in tests/e2e/, same specs against every environment of the project. Environments (fusebase env) supply everything varying between stages: base URLs, org/app ids, test users.

When e2e is being added as part of an environment migration, first follow the local guide App Environment Migration Guide, then use this skill for the Playwright harness and CI details.

When adding e2e to an existing project, first follow the local guide E2E Playwright Setup Guide: audit environments, prefer non-prod targets, warn before any prod run, scaffold from the CLI template, and wire GitLab CI.

Scaffold

fusebase scaffold --template e2e --dir tests/e2e
cd tests/e2e && npx playwright install chromium
FUSEBASE_ENV=<env> npm test

Layout — one project per app

playwright.config.ts generates one Playwright project per app in fusebase.json (name = the app's key, falling back to subdomain), each pinned to that app's env-effective URL. Specs live in:

• specs/common/** — universal specs, run for EVERY app, app-aware via test.info().project.name.
• specs/<appKey>/** — that app's own specs.

Adding an app: give it a short key in fusebase.json (e.g. probe), mkdir specs/<key>, add specs, add the key to the CI matrix APP list. Run a single app with --project=<appKey>.

Cross-app / portal flows (registration → access propagation across apps + portal) span more than one app and have NO single baseURL — they do not belong to any app's project. Put them in specs/integration/; the config adds an integration project whose specs build each app's URL via appBaseUrl(env, key). Add integration to the CI matrix APP list. Recipes: examples/cross-app-access.spec.ts, examples/portal-access.spec.ts. (Product-scoped magic links + one org = shared session across app subdomains, which is exactly what these flows assert.)

Non-negotiables

1. Stage guard stays. specs/common/stage.spec.ts asserts each app's deployed fusebase-env.json matches the target env AND app. Never delete it — a run against the wrong stage/app is worse than no run.
2. No hardcoded env data. Hosts, org/app ids, credentials come only from helpers/env.ts (environments/<name>.json + .env.<name>) and the project's baseURL. A spec that embeds a URL or id silently breaks on another environment or app.
3. Fixtures self-skip. Use the fixtureUser(env, key) + test.skip pattern (see examples/role-matrix.spec.ts) so specs stay runnable while fixtures roll out per env.
4. Cleanup. Tests that create data must delete it — prod-test environments are real orgs.
5. No secrets in git. Passwords via PW_USER_<KEY>_PASSWORD in .env.<name> locally / CI variables in pipelines. Reports and traces are gitignored.