picoclaw/integration/README.md

Integration Test Suites

This directory contains Docker-backed integration test suites that are auto-discovered by CI.

How It Works

• The shared runner is defined in integration/docker-compose.runner.yml.
• Each suite lives in integration/suites/<suite-name>/.
• CI and local runs use scripts/run-integration-tests.sh.
• The runner discovers every suite automatically, so adding a new suite does not require editing the GitHub Actions workflow.

Suite Layout

Each suite directory must contain:

• suite.env
• at least one docker-compose.yml or docker-compose.*.yml

Example:

integration/suites/my-suite/
├── docker-compose.yml
└── suite.env

Required Manifest Fields

suite.env is sourced by the runner script and must define:

• TEST_COMMAND: shell command executed inside the integration runner container

Optional fields:

• RUNNER_SERVICE: override the default runner service name (integration-runner)

Example:

TEST_COMMAND='go test ./pkg/mcp -run TestIntegration_RealConfiguredServer -v'

Docker Conventions

Suite compose files can:

• define dependency services needed by the tests
• extend or override the shared integration-runner service
• inject environment variables into the runner for the tests to consume

The provided mcp-streamable suite is a good reference:

• it starts a local streamable HTTP MCP server
• wires the runner to that service through Docker networking
• runs the Go integration test against the containerized server

Running Locally

Run all suites:

bash ./scripts/run-integration-tests.sh

Run one suite:

bash ./scripts/run-integration-tests.sh mcp-streamable

Adding a New Suite

1. Create integration/suites/<name>/docker-compose.yml.
2. Create integration/suites/<name>/suite.env.
3. Put any fixture service code under integration/fixtures/ if it is reusable.
4. Make sure the suite is self-contained and deterministic.
5. Validate it locally with bash ./scripts/run-integration-tests.sh <name>.

Once committed, the suite will be picked up automatically by the CI integration job.