CI Job Structure and Fix Strategies#

Path-Based Trigger Rules#

The CI workflow (ci.yml) uses dorny/paths-filter to determine which jobs run:

Draft PRs skip expensive tests (E2E, integration, component).

Job Details#

frontend-app-lint#

Check name: Frontend App Lint
What it checks: Biome linting, Biome formatting, TypeScript type checking (via Turborepo)
Fix commands:

cd frontend && pnpm format # Biome formatting
cd frontend && pnpm lint:fix # Biome lint auto-fix + i18n check
cd frontend && pnpm types # TypeScript type checking across all packages

Common failures: Biome lint errors, TypeScript type errors, missing i18n translations.

frontend-app-unit-tests#

Check name: Frontend App Unit Tests
Framework: Vitest
Fix commands:

cd frontend && pnpm test:unit:ci # Run all unit tests
cd frontend && pnpm test:unit:file "path/to/test" # Run a specific test

Artifact on failure: email-snapshots-diff (image snapshot diffs, 3-day retention)

frontend-app-component-tests#

Check name: Frontend App Component Tests
Framework: Cypress component testing
Fix commands:

cd frontend/app && pnpm test:component:ci

Artifact on failure: cypress-report-component-<SHA> (1-day retention)

frontend-app-e2e-tests#

Check name: Frontend App E2E Tests (1) through Frontend App E2E Tests (4)
Framework: Cypress E2E with cypress-split for parallelization
Parallel containers: 4 (job-index 0-3)
Retries: 2 per test (configured in cypress.config.mjs)
Fix commands:

cd frontend/app && pnpm test:e2e:ci # Requires local Supabase + app running
cd frontend/app && pnpm test:e2e # Opens Cypress interactive runner

Artifact on failure: cypress-report-e2e-<SHA>-<JOB_INDEX> (1-day retention)
Report contents:

• html/index.html — Mochawesome HTML report (contains embedded JSON with all test results)
• html/videos/*.mp4 — Video recordings (0-byte files = test passed, only failed tests have content)
• html/screenshots/ — Failure screenshots (if configured)

Key files:

• Config: frontend/app/cypress.config.mjs
• Test specs: frontend/app/cypress/e2e/
• Support: frontend/app/cypress/e2e-support/e2e.ts
• Utilities: frontend/app/cypress/utils/
• Fixtures: frontend/app/cypress/fixtures/

Timeouts (from config):

• requestTimeout: 32s
• pageLoadTimeout: 16s
• responseTimeout: 16s
• defaultCommandTimeout: 16s

backend#

Check name: Backend
What it checks: Black formatting, Ruff linting, Mypy type checking, unit tests
Fix commands:

cd backend && poetry run black . # Auto-format
cd backend && poetry run ruff check . # Lint (add --fix for auto-fix)
cd backend && poetry run mypy --pretty . # Type check
cd backend && make test-unit # Unit tests (DEPLOY_ENV="test-unit")

backend-integration#

Check name: Backend Integration Tests
What it checks: Integration tests requiring Supabase
Fix commands:

cd backend && poetry run python -m pytest tests/path/to/test.py

supabase#

Check name: Supabase Tests
What it checks: pgTap database tests
Fix commands:

supabase test db

schemas-check#

Check name: Migrations / Schemas Sync Check
What it checks: Migration files sync with schema files, max one migration per PR, branch up-to-date with main
Fix commands:

supabase db reset && ./scripts/generate-schemas.sh # Regenerate schemas

Common failures: Branch not up-to-date with main (requires merge/rebase), schema files out of sync.

ci-status#

Check name: ci-status
Purpose: Aggregation gate — fails if ANY other job fails. Not a real failure to fix; fix the underlying job instead.

Artifact Retention#

All test report artifacts have 1-day retention. The next-build artifact is deleted automatically when all tests pass.