Claude Code Project Instructions

Platform Requirement: Linux Only

CRITICAL: This application is designed to run exclusively on Linux. See ADR-014 for full details.

Test Execution Rules

ALL tests MUST be executed on Linux - either in the Dev Container or on a Linux host
NEVER run tests directly on Windows - test results from Windows are unreliable
Always use the Dev Container for testing when developing on Windows

How to Run Tests Correctly

# If on Windows, first open VS Code and "Reopen in Container"
# Then run tests inside the container:
npm test           # Run all unit tests
npm run test:unit  # Run unit tests only
npm run test:integration  # Run integration tests (requires DB/Redis)

Running Tests via Podman (from Windows host)

The command to run unit tests in the Linux container via podman:

podman exec -it flyer-crawler-dev npm run test:unit

The command to run integration tests in the Linux container via podman:

podman exec -it flyer-crawler-dev npm run test:integration

For running specific test files:

podman exec -it flyer-crawler-dev npm test -- --run src/hooks/useAuth.test.tsx

Why Linux Only?

Path separators: Code uses POSIX-style paths (/) which may break on Windows
Shell scripts in scripts/ directory are Linux-only
External dependencies like pdftocairo assume Linux installation paths
Unix-style file permissions are assumed throughout

Test Result Interpretation

Tests that pass on Windows but fail on Linux = BROKEN tests (must be fixed)
Tests that fail on Windows but pass on Linux = PASSING tests (acceptable)

Development Workflow

Open project in VS Code
Use "Reopen in Container" (Dev Containers extension required)
Wait for container initialization to complete
Run npm test to verify environment is working
Make changes and run tests inside the container

Quick Reference

Command	Description
`npm test`	Run all unit tests
`npm run test:unit`	Run unit tests only
`npm run test:integration`	Run integration tests
`npm run dev:container`	Start dev server (container)
`npm run build`	Build for production

2.4 KiB Raw Blame History