---
name: run-e2e-specs-from-isolated-worktree
description: "Run serverAppConfigs Playwright e2e specs against the live fleet from a feature branch when git checkout is workspace-policy-blocked — isolated worktree + symlinked deps, with the variadic --project and gitignored-auth traps."
---

## When

You are authoring/verifying a `tests/e2e/*.spec.ts` change for `dank/serverAppConfigs` and the shared workspace blocks `git checkout` / branch switch (concurrent-agent safety). You must run the new specs against the LIVE fleet (they are guard-chain tests: Anubis PoW + authentik outpost + app) but a fresh worktree has no `node_modules`, no `.auth`, and no `.env.local`.

This is NOT `deploy.sh` (which runs the full e2e gate itself from the main-tracking checkout — see `serverappconfigs-deploy-execution-context`). Use this to iterate/verify individual specs on a branch before opening a PR.

## Setup the worktree

The main deploy checkout (has the deps + auth state) is `/home/blank/Projects/serverAppConfig`. Branch off `origin/main` into a throwaway worktree:

```bash
git -C <repo> worktree add -b feat/<topic> /tmp/wt-<topic> origin/main
ME=/home/blank/Projects/serverAppConfig/tests/e2e
ln -sfn "$ME/node_modules" /tmp/wt-<topic>/tests/e2e/node_modules
cp -r "$ME/.auth"          /tmp/wt-<topic>/tests/e2e/.auth
cp    "$ME/.env.local"     /tmp/wt-<topic>/tests/e2e/.env.local   # gitignored
```

- **`.env.local` is mandatory** — without it the config throws `missing E2E_STANDARD_USER — set it in tests/e2e/.env.local or the environment` at load, even for `--list`. It is gitignored (a bats seam forbids tracking it), so a fresh worktree never has it.
- `.auth` holds `qa-e2e.json` / `qa-e2e-admin.json` (the `standard`/`admin`/`guest` storage states); copying it avoids re-login, though the `setup` project refreshes it anyway.
- The node_modules symlink resolves fine for playwright.

## Validate wiring before running

```bash
cd /tmp/wt-<topic>/tests/e2e && npx playwright test --list
```

Confirms your new spec's NUMBER PREFIX is matched into a project. **A spec whose prefix is not in any project's `testMatch` silently never runs** — a green suite with a test that does not exist. The gate is the bats seam `tests/e2e_scaffold.bats` → "every e2e spec is matched by a playwright project". So a new spec `21-foo.spec.ts` MUST also edit `playwright.config.ts`'s `standard` (or other) `testMatch: /(10|12|...|21)-.*\.spec\.ts/`.

## Running — the `--project` trap

`--project` is **variadic**: the space form swallows the positional filters as extra project names.

```bash
# WRONG: "21-notebook" parsed as a second project → Project(s) not found
npx playwright test --project standard 21-notebook 22-foo

# RIGHT: equals form, then positional title/file filters
npx playwright test --project=standard 21-notebook 22-foo
npx playwright test --project=guest 14-guard -g "notebook.franksdank.cloud is gated"
```

`standard`/`admin`/`guest`/`frankbook` all `dependencies: ["setup"]`, so `00-auth.setup.ts` runs first and logs in the qa-e2e accounts (~24 s each). Expect ~50 s wall for a couple of specs.

## Verify the spec is meaningful, not vacuous

These specs prove the guard chain handed off to the **app**, so assert a positive app marker (title / app content string / the app's own API returning `status:"success"`), never just `status < 500` or "not the IdP shell" — the latter passes on a 404 or a parked login wall (the 13-sso / 17-hermes class of silent-green bug).

## Cleanup

```bash
git -C <repo> worktree remove --force /tmp/wt-<topic>   # symlink + copied auth are throwaway; branch already pushed
```

Full `./tests/run.sh` (bats, incl. `e2e_scaffold`) must pass before commit; the deploy's own Playwright gate is the canonical live run after merge.