Most S3 compatibility test suites are tightly coupled to a single server or buried inside a server's own CI. That makes it hard to answer the question: does this server handle the same operations the same way as the others? This repo answers that question directly.

s3-compat is a structured Go test suite that runs the same test scenarios against MinIO, SeaweedFS, Garage, RustFS, and liteio. Each server has a feature flag profile so tests skip gracefully for capabilities the server does not support. Results are collected as JSON and rendered into a markdown compatibility matrix.

# Copy the example config
cp configs/targets.example.yml configs/targets.yml

# Start MinIO (the default target)
docker compose -f docker/docker-compose.yml up -d minio

# Run tests against MinIO
make test

# Or run everything and generate the matrix
make test-all matrix

Against a single target:

S3COMPAT_TARGET=minio go test ./... -v -timeout 300s

Against all targets (saves JSON results):

make test-all

Against real AWS S3:

# Set credentials and point at the aws target
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
S3COMPAT_TARGET=aws go test ./... -v -timeout 300s

Generate the compatibility matrix:

make matrix
# writes COMPAT.md and prints it to stdout

1. Add a service to docker/docker-compose.yml.
2. Add a profile to configs/targets.yml with the endpoint, credentials, and feature flags.
3. Run S3COMPAT_TARGET=<name> go test ./... -v.

Feature-gated test packages (to be added) sit under tests/<feature>/ and call skip.Feature at the top of each test.

GitHub Actions runs all five targets in parallel on every push to main and every pull request. Garage runs in a separate job because it requires a dynamic credential injection step. The matrix job collects all result artifacts and uploads COMPAT.md.

See .github/workflows/compat.yml for the full pipeline.

Apache-2.0