Testing Guide

This document explains how to run tests locally to catch CI failures before pushing.

Local Testing Environment

We use Docker Compose to match the CI environment exactly. This ensures tests that pass locally will also pass in CI.

Setup

# Start Docker services (PostgreSQL + Redis)
docker-compose -f docker-compose.test.yml up -d

# Verify services are running
docker-compose -f docker-compose.test.yml ps

Running Tests

PDF Shared Package (with Docker services)

# Using the convenience script (recommended)
pnpm test:pdf-shared

# Or manually with Docker services
docker-compose -f docker-compose.test.yml up -d
cd packages/pdf-shared
python -m pytest tests/ -v --tb=short

Other Test Commands

# Python tests — packages/pdf-shared + apps/dagster ONLY (requires local setup)
pnpm test:python

# Temporal worker tests — NOT run by pnpm test:python
pnpm --filter @repo/temporal-worker test

# Dagster tests
pnpm test:dagster

# All Node/TypeScript tests
pnpm test

Cleanup

# Stop services (keep volumes)
docker-compose -f docker-compose.test.yml down

# Stop services and remove volumes (full reset)
docker-compose -f docker-compose.test.yml down -v

Pre-Push Workflow

CRITICAL: Always run these BEFORE pushing to origin:

# 1. Start Docker services
docker-compose -f docker-compose.test.yml up -d

# 2. Run all tests
pnpm test:pdf-shared       # PDF Shared (CI-matched environment)
pnpm test:python           # Python: packages/pdf-shared + apps/dagster
pnpm --filter @repo/temporal-worker test   # Temporal worker
pnpm test                  # All Node/TS tests

# 3. Lint and build
pnpm lint                  # Includes feature flag checks
pnpm build                 # TypeScript compilation

# 4. If all pass, commit and push
git add .
git commit -m "..."
git push origin feat/your-feature

Troubleshooting

PostgreSQL Connection Errors

If you see “role ‘root’ does not exist”, it means the services aren’t running or haven’t fully initialized.

# Check service status
docker-compose -f docker-compose.test.yml logs postgres

# Restart services
docker-compose -f docker-compose.test.yml restart postgres
docker-compose -f docker-compose.test.yml restart redis

Port Already in Use

docker-compose.test.yml maps PostgreSQL to host port 5433 (${TEST_PG_PORT:-5433}:5432) and Redis to host port 6380 (${TEST_REDIS_PORT:-6380}:6379) so test containers do not collide with local dev containers on 5432/6379. If port 5433 or 6380 is already in use:

# Find and stop conflicting containers
docker ps
docker stop <container_id>

# Or override the host ports via env vars
TEST_PG_PORT=5434 TEST_REDIS_PORT=6381 docker-compose -f docker-compose.test.yml up -d

Services Won’t Start

# Full reset
docker-compose -f docker-compose.test.yml down -v
docker-compose -f docker-compose.test.yml up -d

# Check logs
docker-compose -f docker-compose.test.yml logs

CI vs Local Testing

What Matches CI

✅ PostgreSQL 16 (alpine) with test user (host port 5433 locally via docker-compose.test.yml) ✅ Redis 7 (host port 6380 locally via docker-compose.test.yml) ✅ Environment variables for mocking external services ✅ Python 3.11 (your local version) ✅ All test dependencies (from uv.lock)

What May Differ

⚠️ Your local OS (tests run on Ubuntu in CI) ⚠️ Node version (CI uses Node 22.22.0 per .nvmrc; run nvm use locally) ⚠️ System dependencies (ensure Python 3.11+, git, Docker)

Performance Notes

• First run: ~30s (waiting for services to initialize)
• Subsequent runs: ~2-5s (services already running)
• To speed up: Keep services running between test runs

GitHub Actions CI

Our CI pipeline uses the same services configured in .github/workflows/test-pdf-shared.yml. If tests pass locally with docker-compose, they will pass in CI.

Pre-Push Hook

We enforce testing before push with a Git pre-push hook (.husky/pre-push). This automatically:

• Checks if PDF Shared files changed → runs pnpm test:pdf-shared
• Checks if Python files changed → runs pnpm lint:python:safe
• Checks if TS/JS files changed → runs pnpm lint && pnpm build

If any check fails, the push is blocked. Fix the issue and try pushing again.

Bypassing the Hook (If Necessary)

Only use this if you know what you’re doing:

# Force push without running checks (NOT RECOMMENDED)
git push --no-verify

# Or disable hook temporarily
chmod -x .husky/pre-push
git push
chmod +x .husky/pre-push

⚠️ Warning: Bypassing checks will cause CI failures. Don’t do this unless you have a very good reason.

Questions?

If a test passes locally but fails in CI, it’s likely an environment difference:

1. Check .github/workflows/test-pdf-shared.yml for env vars
2. Run docker-compose -f docker-compose.test.yml logs to see service logs
3. Verify you’re using the correct DATABASE_URL for docker-compose.test.yml: postgresql://test:test@localhost:5433/test (or 5432 inside CI service containers)