Context

Integration and prose tests in the mongo-go-driver currently rely on shared orchestration infrastructure, which creates a bottleneck and increases test execution time.

The Go Driver team should organically develop a testcontainer-based testing pattern as an alternative to the existing prose tests in the internal/test directory. This will allow tests to run in parallel containerized environments, scaling with the number of available CPU cores rather than competing for shared orchestration resources.

Benefits:

• Tests run in parallel using isolated containers, scaling with available CPU cores instead of waiting for shared orchestration
• Each test gets its own MongoDB instance, eliminating state conflicts and flaky tests
• Separate internal/test module allows test-only dependencies (testcontainers, testify, etc.) without polluting consumer dependency trees or triggering confusing CVEs in downstream projects
• Faster local test execution and quicker CI feedback loops
• Easy to test against multiple MongoDB versions concurrently (4.0, 5.0, 6.0, 7.0, 8.0)

Definition of done

1. Create new internal/test module with testcontainers dependencies
2. Implement internal/test/container/mongo.go with MongoDB container utilities (NewMongo, WithMongoImage, WithMongoClientOptions)
3. Implement internal/test/container/teardown.go for test cleanup lifecycle
4. Add proof-of-concept test (wire_protocol_test.go) demonstrating the pattern across multiple MongoDB versions (4.0, 5.0, 6.0, 7.0, 8.0)
5. Create etc/run-containerized-tests.sh script and add test-containerized task to Taskfile.yml
6. Add Evergreen configuration for containerized-tests buildvariant
7. Update go.work to include ./internal/test workspace
8. Verify tests run successfully in local and CI environments

internal/test/
├── go.mod (new module: go.mongodb.org/mongo-driver/v2/internal/test)
├── go.sum
├── doc.go
├── wire_protocol_test.go (proof-of-concept)
└── container/
    ├── mongo.go (core utilities)
    └── teardown.go (cleanup helpers)

Pitfalls

• Requires Docker daemon running locally and in CI, adding infrastructure complexity
• Multiple parallel containers can exhaust system resources ed
• Container startup overhead means single tests are slower than shared orchestration; benefits only realized with parallelization
• Team needs to understand testcontainers lifecycle management and debugging containerized test failures
• Complex topologies (sharded clusters, multi-node replica sets) are harder to orchestrate with testcontainers than with dedicated test infrastructure
• Two testing patterns to maintain during transition period (orchestration + testcontainers)