Sequential Test Execution

Ensures test runs execute one at a time to prevent resource conflicts.

Core Principle

One Test Run at a Time

Test environments share databases, ports, and network resources. Concurrent test execution causes migration conflicts, port collisions, and flaky test results.

Detection Method

Uses Docker container state (not file locks) to detect running tests:

• Self-recovering: docker compose run --rm auto-removes containers on exit
• No stale locks: docker ps reflects actual running state
• Graceful degradation: If Docker is unavailable, tests proceed normally

Hook Behavior

PreToolUse (Bash)

1. Extract command from TOOL_INPUT
2. Check if command is a test execution command
3. Query docker-compose.test.yml for running web containers
4. Running container found → exit 2 (block with message)
5. No running container → exit 0 (allow)

PostToolUse (Bash)

1. Only triggers on docker compose test commands
2. Logs completion timestamp and exit code to $TMPDIR/claude-workflow/test-execution.log
3. Always exit 0 (informational only)

When Blocked

If a test run is blocked:

1. Wait for the existing test container to complete
2. Retry the test command after completion
3. Do NOT force-remove the running container

Test Command Patterns Detected

docker compose -f docker-compose.test.yml run ...
phpunit
jest
pytest
composer test
npm test
TEST_ONLY=...