Repository files navigation

Setup integration test environment via docker compose.This library simplify run and debug tests from IDE: just run, this library setup environment automatically and tear down after test executionAlso it support run tests during CI as part of docker compose service.So your tests will work inside docker-compose (as part of CI process) and outside of docker-compose (as standard IDE workflow).

1. Add reference

   dotnet add ComposeTestEnvironment.xUnit

2. Create docker file with dotnet sdk and copy to it all project.

   Seedockerfile.tests for example.

3. Create docker-compose yaml file.

   Specify necessary environment services, don't expose internal ports.

   Specify service based on image in step 2, with commanddotnet test, with special environment variableUNDER_COMPOSE (seetestcompose.yml).

4. Add environment descriptor to you test assembly

   Create classComposeDescriptor with default constructor inherited fromDockerComposeDescriptor.

   Specify docker compose file name (this library scans all parent directories for the file with the same name).

   Specify default ports for services specified by you docker-compose file.

5. UseIClassFixture<DockerComposeEnvironmentFixture<ComposeDescriptor>>.

   Or you can create class inherited fromDockerComposeEnvironmentFixture<ComposeDescriptor>.

   You can inject into initialization pipeline your code.

6. Setup your CI system to run tests

To run tests:

docker-compose --file testcompose.yml up --abort-on-container-exit --builddocker-compose --file testcompose.yml killdocker-compose --file testcompose.yml down --rmi local

Integration tests (or end-to-end) usually need to setup some environment. During the era of docker I don't wantto install any of software on my desktop or have additional shared service with all environment installed. So Iput all necessary environment services in docker-compose file.

Also I adept of zero configuration approach. I.e. aftergit clone you should be able to rundotnet test and onthe main branch you should have all tests passed without additional setup and configuration. Also I would like torun/debug my tests directly from my favorite IDE.

The simplest answer - create docker-compose file and start environment before tests doesn't work:

• you should expose ports from containers, so you should have free ports, you cannot run tests on different branches in parallel
• you should support different description of necessary environment for local test run and for CI test run
• you should detect mode of test run to change connection string, etc.

This test addon tries to fix these issues:

• you specify all necessary environment in single docker-compose file
• in this docker-compose file you also run tests as additional service (viadotnet test command)
• on local test run (or run/debug tests from IDE):
  • it finds free ports on localhost
  • generates new docker-compose file with exposed ports
  • provides ability to «service discovery» (i.e. you should use different hosts/ports to connect to the servicesdepending on type of run)
  • stops previously run container
  • starts docker compose file before first test used
  • wait for service starts (based on ports and/or specific message in service output or you can provide your own logic for this)
  • tear down docker compose before test stop (if necessary, you can leave container running)
  • on any docker related failure print docker output to test output
  • print docker output as xunit diagnostic message
• it doesnt use test collection to setup and teardown environment (as all tests in collections executed without parallelism)

See:

• testcompose.yml - docker-compose environment with service to run test
• ComposeDescriptor.cs - environment descriptor in code.
• SampleComposeFixture.cs - xUnit class fixture, you should mark your testsviaIClassFixture<SampleComposeFixture> to work with environment services
• SqlTest.cs - example of test

1. How to display docker compose logsCreate xunit.runner.json:

{"$schema":"https://xunit.net/schema/current/xunit.runner.schema.json","diagnosticMessages":true}

Put into your test cspoj:

   <ItemGroup>        <Content Include="xunit.runner.json" CopyToOutputDirectory="PreserveNewest" />    </ItemGroup>

Now

dotnettest

will display docker container logs

2. How to don't clean containers after test finish

OverrideDockerComposeDescriptor.DownOnComplete property to return false.

3. Failed to connect to container udp port via tcp protocool

Sometimes docker images exposes udp ports. I don't know how to determine protocol of exposed port inside docker compose. In thiscase you can ignore wait for this specific port by overridingDockerComposeDescriptor.IgnoreWaitForPortListening

1. Run tests inside docker compose containerProvide discovery mechanism (service name as host).Delay test start until service respond on specified tcp port

2. Run tests from IDEFind free ports, bind to them docker compose servicesDiscovery uses localhost with exposed portsDelay test start until all services respond on tcp portCompose pull before test runCompose down before test run (to stop compose after terminate debug)Compose down after test run

3. (Not yet implemented) Run tests from IDE, attach to existing containers, start new if necessaryFind existing running composeIf good - use it, if not start it as in 2. But do not tear down it after test execution finished (to reuse it on next time)