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

GODRIVER-3722 implements test containers to run CSE prose tests but does not attempt to containerize mongod for CI, instead relying on the evergreen config bootstrap and port-forwarding the host mongodb server via MONGODB_URI. We should strongly consider containerizing that bootstrap instead, using the image provided in drivers evergreen tools or developing our own. We could then pool containers by port for testing prose tests in parallel. 

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)