Implement TestContainers with docker-compose.test.yml

[Ozymandros]

You are assisting in implementing a complete integration testing environment using Python, pytest, and Testcontainers. The goal is to run the entire backend inside an ephemeral Docker environment for each test session (or optionally per test), without modifying the backend implementation. Follow these requirements precisely:

1. Testcontainers + docker-compose.test.yml

   • Implement a testing setup where Testcontainers launches the entire backend stack using a dedicated docker-compose.test.yml.
   • This file must override the production docker-compose.yml and MUST remove all persistent volumes (e.g., database volumes).
   • The testing compose file should define ephemeral containers only.
   • Ensure that the database container does NOT use persistent volumes and resets automatically on each test run.

2. pytest integration

   • Create a conftest.py that defines:
     • A @pytest.fixture(scope="session") that starts the full backend stack using DockerCompose from Testcontainers.
     • The fixture must expose the backend URL(s) to the tests.
     • The fixture must automatically tear down the entire stack after the test session ends.
   • Optionally provide a second fixture for scope="function" to run the backend per test instead of per session.

3. Directory structure

   • Provide a recommended project structure:

     project/
       backend/
       tests/
         integration/
           test_*.py
         conftest.py
       docker-compose.yml
       docker-compose.test.yml
     

4. docker-compose.test.yml

   • Generate a complete example of a testing compose file that:
     • Overrides the database service to remove volumes.
     • Uses lightweight images suitable for CI.
     • Exposes required ports.
     • Ensures all services are ephemeral.

5. Python example

   • Provide a full example of a pytest integration test that:
     • Uses the backend URL from the fixture.
     • Performs a simple health-check request.
     • Demonstrates how to interact with the backend API.

6. Cleanup guarantees

   • Ensure that Testcontainers destroys:
     • All containers
     • All networks
     • All temporary volumes
   • Confirm that no persistent state survives between test runs.

7. No backend code modifications

   • The backend must run exactly as-is inside the container.
   • All testing isolation must be achieved externally via Testcontainers and docker-compose overrides.

8. Output format

   • Provide:
     • docker-compose.test.yml
     • conftest.py
     • example test file
     • explanation of how everything works together
     • instructions for running the tests in CI and locally