Testing and release

Atlas ships small PRs through one pipeline: PR → required CI checks → squash merge to main → deploy.yml (migrations first, then Vercel). Nobody deploys production by hand and nobody force-pushes main. One task = one branch = one PR.

Before you start

• GitHub Actions: all workflows. Production: https://atlas-of-todays-world.vercel.app.
• Supabase: production and atlas-dev. Tests run against atlas-dev only.
• Related skills: atlas-backend (DB tests, migrations), atlas-security (workflow hardening), atlas-performance (Lighthouse budgets), atlas-accessibility (axe).
• Incident and restore steps: reference.

Test layers

Guards in tests/unit/ protect the architecture: client-bundle (no zod or @supabase/ssr in client code), migration-versions, cache-purge (no cache refresh after a zero-row write), route-table, public-form-errors, sanitized-length.

What to run when

• A bug fix starts with a test that reproduces it.
• Server Action: unit test the validation and the result mapping (mock the Supabase client, as src/features/auth/actions.test.ts does) and a DB test for allowed / denied.
• Prefer role-based locators (getByRole) and web-first assertions in Playwright; no fixed waits.
• Never point e2e at production. tests/support/accounts.ts refuses the production ref.

CI (.github/workflows/ci.yml)

Runs on every PR and push to main. Its two job names are the required checks on main. Do not rename them (branch rules):

• "Typy, lint, testy": typecheck → lint → format:check → test → check:audit.
• "Build, smoke a e2e": build (log saved) → scripts/check-static-routes.mjs → start → test:smoke. Despite the name it runs no e2e. Uses atlas-dev public values.

Full tests (full-tests.yml) run nightly at 01:30 UTC and on demand: Storybook build, coverage, test:db, jscpd, knip, audit, e2e in 3 shards against atlas-dev, and Lighthouse. They never block a deploy. A red nightly run means "fix it before the next feature". Run it manually on your branch (Run workflow) when a PR touches DB, auth or e2e-covered flows.

PR rules

• Branch from main; one task per branch. Fill in the PR template (what and why, how tested, Definition of Done, Security impact for auth / RLS / migrations / proxy / lib/security).
• PR title = commit message (squash merge). Use English Conventional Commits: feat(scope): ..., fix(scope): ..., refactor: ..., chore(deps): ..., content: ..., test: ..., docs: .... Imperative, lower case after the colon. Breaking: feat!:.
• Pre-commit (.husky/pre-commit) runs lint-staged: ESLint --fix + Prettier on staged ts/tsx/mjs, Prettier on json/css/yml. Do not bypass it with --no-verify.
• Previews: a PR gets a Vercel preview only with the preview label (not from forks or Dependabot). Previews read the production database and run no migrations: never test writes there, and a preview cannot show a new migration.

Migrations to atlas-dev

• Migrate atlas-dev (migrate-dev.yml) applies new migrations to atlas-dev on every push to main that touches supabase/migrations/**. The script refuses the production ref.
• When e2e or a teammate needs your migration before merge, run that workflow on your branch (Run workflow → your branch). From then on, the file is applied and must not change.
• Confirm in atlas-dev migrations.

Deploy (.github/workflows/deploy.yml)

1. Squash merge to main → CI runs on main.
2. CI green → Deploy to Vercel starts (workflow_run). Job migrate: supabase db push --include-seed to production.
3. Job deploy (only if migrate succeeded): vercel deploy --prod; the build runs on Vercel (deployments).
4. A failed migration stops the deploy and production keeps the old app. Check which migrations were applied in production migrations and fix forward with a new migration in a new PR.

Never run vercel deploy --prod or supabase db push against production yourself, and never push straight to main.

Check production after a deploy

Within a few minutes of the deploy run turning green:

1. curl -s https://atlas-of-todays-world.vercel.app/api/health → "status":"ok", "db":"ok" and "version" equal to the first 7 characters of the merge commit SHA.
2. curl -sI https://atlas-of-todays-world.vercel.app/topics | grep -i x-vercel-cache → HIT (or PRERENDER on the first request). A steady MISS or no header on a public page means it went dynamic: treat it as a bug.
3. BASE_URL=https://atlas-of-todays-world.vercel.app npm run test:smoke → all checks pass.
4. Open the page you changed and, for admin changes, do one real save in the admin.
5. Watch Vercel logs and Supabase logs for new errors.

Owner rule: follow every deploy until the change is live, then tell the owner. After any push that ends in a production deploy, do not stop at "pushed": follow the CI run and the Deploy to Vercel run (gh run list --commit <sha>, gh run watch <id>), then check the live site https://atlas-of-todays-world.vercel.app (/api/health version = the commit, then the changed page itself) until the change actually shows there. (The domain www.atlasoftodaysworld.org still serves the old Webflow site; check it too once it points to this app.) As soon as it does, tell the owner it is live and where to see it. If CI, the migration or the deploy fails, or the change does not show, tell the owner straight away with what failed.

Operations

• Uptime: Keep-alive calls /api/health daily at 06:17 UTC (it also keeps Supabase Free awake; a failure emails the owner). An external monitor (UptimeRobot, owner's account) watches /api/health and a public page.
• Backups: Supabase Free has no platform backups. Záloha DB (backup.yml, 02:40 UTC) dumps schema, roles and data, encrypts with age to the owner's key (variable BACKUP_AGE_RECIPIENT) and keeps the artifact 14 days. Storage files are not in the dump.
• Restore drill quarterly into a throwaway database, never production or atlas-dev: steps in reference.
• Dead links: Kontrola odkazů every Monday 05:41 UTC.
• Rollback: revert the PR through a new PR (the normal pipeline). DB changes are never rolled back with "down" migrations; fix forward. Vercel Instant Rollback is the owner's emergency call.

Checklist

• [ ] Right tests for the change (table above) pass locally; a bug fix has a reproducing test.
• [ ] New DB test file is listed in test:db.
• [ ] PR title is a Conventional Commit; template filled in, Security impact where needed.
• [ ] Both required checks green; migration applied to atlas-dev before e2e relies on it.
• [ ] After merge: deploy run green, /api/health shows the new version, X-Vercel-Cache: HIT, smoke passes.
• [ ] The change is visible on the live site and the owner has been told it is live.

Anti-patterns

• Testing admin writes on a preview deployment: it writes to production data.
• Renaming a CI job: the required check disappears and merges stall (or pass unchecked).
• --no-verify, force-push to main, or a manual production deploy "just this once".
• Editing a migration after migrate-dev applied it: atlas-dev and production drift.
• Treating a red nightly run as noise: it is the only run of e2e, DB tests and Lighthouse.

Sources

• Playwright: Best practices - https://playwright.dev/docs/best-practices
• Kent C. Dodds: The testing trophy - https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications
• Conventional Commits 1.0.0 - https://www.conventionalcommits.org/en/v1.0.0/
• Supabase: Database backups - https://supabase.com/docs/guides/platform/backups
• Google SRE: Postmortem culture - https://sre.google/sre-book/postmortem-culture/
• Trunk-based development - https://trunkbaseddevelopment.com/