# Sequential Test Execution

> Invoke as a PreToolUse hook on Bash commands to prevent concurrent test runs. Detects running test containers before launching new test processes, blocking execution with feedback if another test is active to ensure isolation.

- Skill: `masanao-ohba/sequential-test-execution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add masanao-ohba/sequential-test-execution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masanao-ohba/sequential-test-execution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masanao-ohba (https://skillmd.com/u/masanao-ohba)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/masanao-ohba/sequential-test-execution

---


# 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=...
```