gopkg.in/docker/docker.v23@v23.0.11/TESTING.md (about)

     1  # Testing
     2  
     3  This document contains the Moby code testing guidelines. It should answer any 
     4  questions you may have as an aspiring Moby contributor.
     5  
     6  ## Test suites
     7  
     8  Moby has two test suites (and one legacy test suite):
     9  
    10  * Unit tests - use standard `go test` and
    11    [gotest.tools/assert](https://godoc.org/gotest.tools/assert) assertions. They are located in
    12    the package they test. Unit tests should be fast and test only their own 
    13    package.
    14  * API integration tests - use standard `go test` and
    15    [gotest.tools/assert](https://godoc.org/gotest.tools/assert) assertions. They are located in
    16    `./integration/<component>` directories, where `component` is: container,
    17    image, volume, etc. These tests perform HTTP requests to an API endpoint and
    18    check the HTTP response and daemon state after the call.
    19  
    20  The legacy test suite `integration-cli/` is deprecated. No new tests will be 
    21  added to this suite. Any tests in this suite which require updates should be 
    22  ported to either the unit test suite or the new API integration test suite.
    23  
    24  ## Writing new tests
    25  
    26  Most code changes will fall into one of the following categories.
    27  
    28  ### Writing tests for new features
    29  
    30  New code should be covered by unit tests. If the code is difficult to test with
    31  unit tests, then that is a good sign that it should be refactored to make it
    32  easier to reuse and maintain. Consider accepting unexported interfaces instead
    33  of structs so that fakes can be provided for dependencies.
    34  
    35  If the new feature includes a completely new API endpoint then a new API 
    36  integration test should be added to cover the success case of that endpoint.
    37  
    38  If the new feature does not include a completely new API endpoint consider 
    39  adding the new API fields to the existing test for that endpoint. A new 
    40  integration test should **not** be added for every new API field or API error 
    41  case. Error cases should be handled by unit tests.
    42  
    43  ### Writing tests for bug fixes
    44  
    45  Bugs fixes should include a unit test case which exercises the bug.
    46  
    47  A bug fix may also include new assertions in existing integration tests for the
    48  API endpoint.
    49  
    50  ### Writing new integration tests
    51  
    52  Note the `integration-cli` tests are deprecated; new tests will be rejected by
    53  the CI.
    54  
    55  Instead, implement new tests under `integration/`.
    56  
    57  ### Integration tests environment considerations
    58  
    59  When adding new tests or modifying existing tests under `integration/`, testing
    60  environment should be properly considered. `skip.If` from 
    61  [gotest.tools/skip](https://godoc.org/gotest.tools/skip) can be used to make the 
    62  test run conditionally. Full testing environment conditions can be found at 
    63  [environment.go](https://github.com/moby/moby/blob/6b6eeed03b963a27085ea670f40cd5ff8a61f32e/testutil/environment/environment.go)
    64  
    65  Here is a quick example. If the test needs to interact with a docker daemon on 
    66  the same host, the following condition should be checked within the test code
    67  
    68  ```go
    69  skip.If(t, testEnv.IsRemoteDaemon())
    70  // your integration test code
    71  ```
    72  
    73  If a remote daemon is detected, the test will be skipped.
    74  
    75  ## Running tests
    76  
    77  ### Unit Tests
    78  
    79  To run the unit test suite:
    80  
    81  ```
    82  make test-unit
    83  ```
    84  
    85  or `hack/test/unit` from inside a `BINDDIR=. make shell` container or properly
    86  configured environment.
    87  
    88  The following environment variables may be used to run a subset of tests:
    89  
    90  * `TESTDIRS` - paths to directories to be tested, defaults to `./...`
    91  * `TESTFLAGS` - flags passed to `go test`, to run tests which match a pattern
    92    use `TESTFLAGS="-test.run TestNameOrPrefix"`
    93  
    94  ### Integration Tests
    95  
    96  To run the integration test suite:
    97  
    98  ```
    99  make test-integration
   100  ```
   101  
   102  This make target runs both the "integration" suite and the "integration-cli"
   103  suite.
   104  
   105  You can specify which integration test dirs to build and run by specifying
   106  the list of dirs in the TEST_INTEGRATION_DIR environment variable.
   107  
   108  You can also explicitly skip either suite by setting (any value) in
   109  TEST_SKIP_INTEGRATION and/or TEST_SKIP_INTEGRATION_CLI environment variables.
   110  
   111  Flags specific to each suite can be set in the TESTFLAGS_INTEGRATION and
   112  TESTFLAGS_INTEGRATION_CLI environment variables.
   113  
   114  If all you want is to specify a test filter to run, you can set the
   115  `TEST_FILTER` environment variable. This ends up getting passed directly to `go
   116  test -run` (or `go test -check-f`, depending on the test suite). It will also
   117  automatically set the other above mentioned environment variables accordingly.
   118  
   119  ### Go Version
   120  
   121  You can change a version of golang used for building stuff that is being tested
   122  by setting `GO_VERSION` variable, for example:
   123  
   124  ```
   125  make GO_VERSION=1.12.8 test
   126  ```