ci-local-parity

name	ci-local-parity
description	Run Volatio CI locally before pushing (ci-local.sh), mirrors GitHub Actions exactly, catches failures fast. Use when preparing to push, debugging CI failures, or verifying changes will pass.

ci-local-parity

⛔ MANDATORY RULE: RUN BEFORE EVERY PUSH

You MUST run ./scripts/ci-local.sh and wait for completion before ANY git push.

Do NOT:

• Push without running local CI first
• Interrupt the script - it needs to complete fully
• Iterate on failures via remote CI (wastes 8-10 min per attempt)

When to Use

• ALWAYS before pushing changes to remote (non-negotiable)
• Debugging CI failures locally
• Verifying lint/typecheck/tests pass
• Ensuring schema changes work with CI database (postgres:16, not TimescaleDB)

Golden Path

# Run full CI pipeline locally
./scripts/ci-local.sh
# Wait for: "✓ CI WOULD PASS - SAFE TO PUSH"
git push

Quick Variants

# Full CI (mirrors GitHub Actions exactly)
./scripts/ci-local.sh

# Quick mode (skip E2E tests - for fast iteration)
./scripts/ci-local.sh --quick

# E2E tests only (when you know lint/types pass)
./scripts/ci-local.sh --e2e-only

# Skip Python checks (if no Python changes)
./scripts/ci-local.sh --no-python

# Makefile shortcuts
make ci          # Full CI
make ci-quick    # Skip E2E
make ci-e2e      # E2E only

What the Script Checks

1. ✅ Lint (Biome) - Same as CI
2. ✅ Typecheck - Same as CI
3. ✅ Unit Tests with Coverage - Same as CI
4. ✅ Python Lint (Ruff) + Tests (pytest) - Same as CI
5. ✅ E2E Tests (Playwright) - Using CI database

Why This Matters

• CI uses postgres:16 (NOT TimescaleDB) - schema issues show up here
• CI uses a fresh database - tests must handle empty state
• CI environment variables differ from local dev
• Finding issues locally is 10x faster than waiting for CI

Common CI Failure Patterns

Lint Failures

# Run Biome check locally
pnpm lint

# Auto-fix
pnpm lint:fix

TypeScript Errors

# Run typecheck
pnpm typecheck

Unit Test Failures

# Run unit tests with --run (not watch mode!)
pnpm test -- --run

Python Lint/Test Failures

# Ruff check
cd research && ruff check .

# Pytest
cd research && pytest

E2E Test Failures

# Run specific failing test - ALWAYS use --reporter=list to prevent hang!
./scripts/e2e.sh e2e/failing-test.spec.ts --timeout=60000 --reporter=list

⚠️ CRITICAL: Preventing Test Hangs

Tests can hang silently without proper flags:

# ❌ HANGS FOREVER - watch mode with no output
pnpm test
./scripts/e2e.sh  # (no --reporter=list)

# ✅ EXITS CLEANLY
pnpm test -- --run
./scripts/e2e.sh --reporter=list
./scripts/ci-local.sh  # (handles this internally)

If a command produces no output for 30+ seconds, it's probably hung. Kill it and use correct flags.

All Auth Tests Failing

If ALL auth tests fail (auth.spec.ts, server-health.spec.ts, auth.setup.ts), check:

1. Next.js warmup missing - Dashboard must be warmed up before tests run
2. AUTH_SECRET mismatch - API and Dashboard must use same secret
3. Admin user not seeded - Test user [e-mail] must exist

The ci-local.sh script handles all these, but manual test runs might miss them.

Debug Checklist for CI Failures

1. Check if services are running: docker compose ps
2. Check database exists: Run docker-db-queries skill
3. Check for schema drift: pnpm --filter @volatio/db push
4. Check test user is seeded: ./scripts/e2e.sh handles this
5. Check for port zombies: make kill-servers
6. Check Next.js cache: rm -rf apps/dashboard/.next