Testing Strategy and E2E

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• tests/e2e_test.go
• tests/concurrent_smoke_test.go
• tests/compose_config_test.go
• internal/cli/init_test.go
• internal/compose/shared_services_e2e_test.go

The testing strategy for Docktree is designed to ensure the reliability of a CLI tool that orchestrates complex Docker Compose environments across multiple Git worktrees. The project utilizes a multi-tiered testing approach, ranging from unit tests for internal logic to comprehensive end-to-end (E2E) integration tests that simulate real-world usage patterns, including concurrent operations and port allocation.

The primary goal of the testing suite is to verify observable behavior and edge cases without relying on excessive internal plumbing mocks. Developers are encouraged to use fixtures located in testdata/ rather than live Docker instances where possible, though integration tests explicitly require Docker with the Compose plugin for full validation.

Sources: CONTRIBUTING.md:1-127

Testing Architecture and Tiers

Docktree categorizes its tests into distinct tiers to balance execution speed with environment fidelity.

Tier	Location	Command	Purpose
Unit Tests	internal/...	just test	Validates internal library logic (parsing, config merging, synthesis).
Integration/E2E	tests/	just test-all	Tests CLI commands against fake or real Docker environments.
Race Detection	Project-wide	go test -race ./...	Identifies concurrency issues in state management and port registry.

Sources: CONTRIBUTING.md:71-77, tests/concurrent_smoke_test.go:19-20

Test Execution Flow

The following diagram illustrates how tests are typically structured, particularly for E2E scenarios involving the CLI:

The project uses cli.Run within tests to bypass shell overhead while still testing the full CLI command path.
Sources: tests/e2e_test.go:21-45, tests/e2e_test.go:193-197

Integration and End-to-End (E2E) Testing

E2E tests verify the complete lifecycle of a Docktree-managed worktree, including initialization, service startup, and resource cleanup.

CLI Command Flow Validation

The E2E suite simulates multiple worktrees to ensure that:

• Project names are unique per worktree.
• Ports are correctly remapped to avoid host-level collisions.
• Override files (.override.yml) are generated correctly with rewritten container names.
• The global state registry tracks active instances.

Sources: tests/e2e_test.go:21-105

Fake Docker Harness

To facilitate testing without a full Docker daemon in CI environments, the project employs a "Fake Docker" script. This shell script mimics the output of docker compose ps, network ls, and volume ls based on files created in a temporary directory.

Concurrency and Smoke Testing

Docktree emphasizes robust handling of concurrent operations, as users may spin up multiple worktrees simultaneously.

Concurrent Up/Down Verification

The concurrent_smoke_test.go file contains tests that spin up multiple instances (e.g., 8 instances) in parallel. It validates:

• Unique Port Allocation: Ensures no two instances are assigned the same host port.
• Global State Consistency: Checks that the instances.json and ports.json in XDG_CONFIG_HOME are not corrupted by simultaneous writes.
• Race Conditions: Uses the Go race detector to find unsynchronized access to shared state files.

Sources: tests/concurrent_smoke_test.go:21-50

Port Exhaustion

Specialized tests verify system behavior when the available port range (e.g., 49900-49999) is smaller than the total demand from concurrent instances. This ensures the CLI returns appropriate error codes rather than panicking.
Sources: tests/concurrent_smoke_test.go:250-265

Compose Synthesis Testing

The synthesis logic—which splits a standard docker-compose.yml into platform-tier and worktree-tier projects—is validated through E2E synthesis tests.

Shared Services Synthesis

The internal/compose/shared_services_e2e_test.go file validates the full synthesis pipeline:

• Platform Project: Contains only shared services (e.g., Postgres, Redis) and attaches them to a specific platform network.
• Worktree Project: Omits shared services, strips depends_on references to them, and rewrites environment variables like DATABASE_URL to include unique tenant database names.

Sources: internal/compose/shared_services_e2e_test.go:20-40

Clean Command and Resource Reclamation

The clean command is critical for removing resources tied to deleted Git worktrees. Testing ensures that:

• Containers, networks, and volumes are removed when the corresponding worktree directory no longer exists.
• Ports are released back into the registry.
• Global instance state is purged.

Sources: tests/e2e_test.go:154-184, tests/compose_config_test.go:175-200

Testing Guidelines for Contributors

According to the CONTRIBUTING.md, the following standards must be met for new code:

• Coverage: Add tests for new behavior and failing tests for bug fixes.
• Fixtures: Use testdata/ fixtures. Do not add mocks if a real fixture can cover the logic.
• CI Parity: Ensure go test -race -count=1 ./... passes locally, as this mirrors the CI environment.

Sources: CONTRIBUTING.md:79-84

Docktree's testing strategy ensures that the complex interactions between Git, Docker Compose, and host-level resource management remain stable across concurrent environments and diverse project topologies.