github.com/jogo/docker@v1.7.0-rc1/docs/sources/project/test-and-docs.md (about) 1 page_title: Run tests and test documentation 2 page_description: Describes Docker's testing infrastructure 3 page_keywords: make test, make docs, Go tests, gofmt, contributing, running tests 4 5 # Run tests and test documentation 6 7 Contributing includes testing your changes. If you change the Docker code, you 8 may need to add a new test or modify an existing one. Your contribution could 9 even be adding tests to Docker. For this reason, you need to know a little 10 about Docker's test infrastructure. 11 12 Many contributors contribute documentation only. Or, a contributor makes a code 13 contribution that changes how Docker behaves and that change needs 14 documentation. For these reasons, you also need to know how to build, view, and 15 test the Docker documentation. 16 17 In this section, you run tests in the `dry-run-test` branch of your Docker 18 fork. If you have followed along in this guide, you already have this branch. 19 If you don't have this branch, you can create it or simply use another of your 20 branches. 21 22 ## Understand testing at Docker 23 24 Docker tests use the Go language's test framework. In this framework, files 25 whose names end in `_test.go` contain test code; you'll find test files like 26 this throughout the Docker repo. Use these files for inspiration when writing 27 your own tests. For information on Go's test framework, see <a 28 href="http://golang.org/pkg/testing/" target="_blank">Go's testing package 29 documentation</a> and the <a href="http://golang.org/cmd/go/#hdr-Test_packages" 30 target="_blank">go test help</a>. 31 32 You are responsible for _unit testing_ your contribution when you add new or 33 change existing Docker code. A unit test is a piece of code that invokes a 34 single, small piece of code ( _unit of work_ ) to verify the unit works as 35 expected. 36 37 Depending on your contribution, you may need to add _integration tests_. These 38 are tests that combine two or more work units into one component. These work 39 units each have unit tests and then, together, integration tests that test the 40 interface between the components. The `integration` and `integration-cli` 41 directories in the Docker repository contain integration test code. 42 43 Testing is its own specialty. If you aren't familiar with testing techniques, 44 there is a lot of information available to you on the Web. For now, you should 45 understand that, the Docker maintainers may ask you to write a new test or 46 change an existing one. 47 48 ### Run tests on your local host 49 50 Before submitting any code change, you should run the entire Docker test suite. 51 The `Makefile` contains a target for the entire test suite. The target's name 52 is simply `test`. The make file contains several targets for testing: 53 54 <style type="text/css"> 55 .monospaced {font-family: Monaco, Consolas, "Lucida Console", monospace !important;} 56 </style> 57 <table> 58 <tr> 59 <th>Target</th> 60 <th>What this target does</th> 61 </tr> 62 <tr> 63 <td class="monospaced">test</td> 64 <td>Run all the tests.</td> 65 </tr> 66 <tr> 67 <td class="monospaced">test-unit</td> 68 <td>Run just the unit tests.</td> 69 </tr> 70 <tr> 71 <td class="monospaced">test-integration-cli</td> 72 <td>Run the test for the integration command line interface.</td> 73 </tr> 74 <tr> 75 <td class="monospaced">test-docker-py</td> 76 <td>Run the tests for Docker API client.</td> 77 </tr> 78 <tr> 79 <td class="monospaced">docs-test</td> 80 <td>Runs the documentation test build.</td> 81 </tr> 82 </table> 83 84 Run the entire test suite on your current repository: 85 86 1. Open a terminal on your local host. 87 88 2. Change to the root your Docker repository. 89 90 $ cd docker-fork 91 92 3. Make sure you are in your development branch. 93 94 $ git checkout dry-run-test 95 96 4. Run the `make test` command. 97 98 $ make test 99 100 This command does several things, it creates a container temporarily for 101 testing. Inside that container, the `make`: 102 103 * creates a new binary 104 * cross-compiles all the binaries for the various operating systems 105 * runs the all the tests in the system 106 107 It can take several minutes to run all the tests. When they complete 108 successfully, you see the output concludes with something like this: 109 110 111 [PASSED]: top - sleep process should be listed in privileged mode 112 [PASSED]: version - verify that it works and that the output is properly formatted 113 PASS 114 coverage: 70.8% of statements 115 ---> Making bundle: test-docker-py (in bundles/1.5.0-dev/test-docker-py) 116 +++ exec docker --daemon --debug --host unix:///go/src/github.com/docker/docker/bundles/1.5.0-dev/test-docker-py/docker.sock --storage-driver vfs --exec-driver native --pidfile /go/src/github.com/docker/docker/bundles/1.5.0-dev/test-docker-py/docker.pid 117 ................................................................. 118 ---------------------------------------------------------------------- 119 Ran 65 tests in 89.266s 120 121 122 ### Run test targets inside the development container 123 124 If you are working inside a Docker development container, you use the 125 `hack/make.sh` script to run tests. The `hack/make.sh` script doesn't 126 have a single target that runs all the tests. Instead, you provide a single 127 command line with multiple targets that does the same thing. 128 129 Try this now. 130 131 1. Open a terminal and change to the `docker-fork` root. 132 133 2. Start a Docker development image. 134 135 If you are following along with this guide, you should have a 136 `dry-run-test` image. 137 138 $ docker run --privileged --rm -ti -v `pwd`:/go/src/github.com/docker/docker dry-run-test /bin/bash 139 140 3. Run the tests using the `hack/make.sh` script. 141 142 root@5f8630b873fe:/go/src/github.com/docker/docker# hack/make.sh dynbinary binary cross test-unit test-integration-cli test-docker-py 143 144 The tests run just as they did within your local host. 145 146 147 Of course, you can also run a subset of these targets too. For example, to run 148 just the unit tests: 149 150 root@5f8630b873fe:/go/src/github.com/docker/docker# hack/make.sh dynbinary binary cross test-unit 151 152 Most test targets require that you build these precursor targets first: 153 `dynbinary binary cross` 154 155 156 ## Running individual or multiple named tests 157 158 We use [gocheck](https://labix.org/gocheck) for our integration-cli tests. 159 You can use the `TESTFLAGS` environment variable to run a single test. The 160 flag's value is passed as arguments to the `go test` command. For example, from 161 your local host you can run the `TestBuild` test with this command: 162 163 $ TESTFLAGS='-check.f DockerSuite.TestBuild*' make test-integration-cli 164 165 To run the same test inside your Docker development container, you do this: 166 167 root@5f8630b873fe:/go/src/github.com/docker/docker# TESTFLAGS='-check.f TestBuild*' hack/make.sh binary test-integration-cli 168 169 ## If tests under Boot2Docker fail due to disk space errors 170 171 Running the tests requires about 2GB of memory. If you are running your 172 container on bare metal, that is you are not running with Boot2Docker, your 173 Docker development container is able to take the memory it requires directly 174 from your local host. 175 176 If you are running Docker using Boot2Docker, the VM uses 2048MB by default. 177 This means you can exceed the memory of your VM running tests in a Boot2Docker 178 environment. When the test suite runs out of memory, it returns errors similar 179 to the following: 180 181 server.go:1302 Error: Insertion failed because database is full: database or 182 disk is full 183 184 utils_test.go:179: Error copy: exit status 1 (cp: writing 185 '/tmp/docker-testd5c9-[...]': No space left on device 186 187 To increase the memory on your VM, you need to reinitialize the Boot2Docker VM 188 with new memory settings. 189 190 1. Stop all running containers. 191 192 2. View the current memory setting. 193 194 $ boot2docker info 195 { 196 "Name": "boot2docker-vm", 197 "UUID": "491736fd-4075-4be7-a6f5-1d4cdcf2cc74", 198 "Iso": "/Users/mary/.boot2docker/boot2docker.iso", 199 "State": "running", 200 "CPUs": 8, 201 "Memory": 2048, 202 "VRAM": 8, 203 "CfgFile": "/Users/mary/VirtualBox VMs/boot2docker-vm/boot2docker-vm.vbox", 204 "BaseFolder": "/Users/mary/VirtualBox VMs/boot2docker-vm", 205 "OSType": "", 206 "Flag": 0, 207 "BootOrder": null, 208 "DockerPort": 0, 209 "SSHPort": 2022, 210 "SerialFile": "/Users/mary/.boot2docker/boot2docker-vm.sock" 211 } 212 213 214 3. Delete your existing `boot2docker` profile. 215 216 $ boot2docker delete 217 218 4. Reinitialize `boot2docker` and specify a higher memory. 219 220 $ boot2docker init -m 5555 221 222 5. Verify the memory was reset. 223 224 $ boot2docker info 225 226 6. Restart your container and try your test again. 227 228 229 ## Testing just the Windows client 230 231 This explains how to test the Windows client on a Windows server set up as a 232 development environment. You'll use the **Git Bash** came with the Git for 233 Windows installation. **Git Bash** just as it sounds allows you to run a Bash 234 terminal on Windows. 235 236 1. If you don't have one, start a Git Bash terminal. 237 238 ![Git Bash](/project/images/git_bash.png) 239 240 2. Change to the `docker` source directory. 241 242 $ cd /c/gopath/src/github.com/docker/docker 243 244 3. Set `DOCKER_CLIENTONLY` as follows: 245 246 $ export DOCKER_CLIENTONLY=1 247 248 This ensures you are building only the client binary instead of both the 249 binary and the daemon. 250 251 4. Set `DOCKER_TEST_HOST` to the `tcp://IP_ADDRESS:2376` value; substitute your 252 machine's actual IP address, for example: 253 254 $ export DOCKER_TEST_HOST=tcp://263.124.23.200:2376 255 256 5. Make the binary and the test: 257 258 $ hack/make.sh binary test-integration-cli 259 260 Many tests are skipped on Windows for various reasons. You see which tests 261 were skipped by re-running the make and passing in the 262 `TESTFLAGS='-test.v'` value. 263 264 265 You can now choose to make changes to the Docker source or the tests. If you 266 make any changes just run these commands again. 267 268 269 ## Build and test the documentation 270 271 The Docker documentation source files are under `docs/sources`. The content is 272 written using extended Markdown. We use the static generator <a 273 href="http://www.mkdocs.org/" target="_blank">MkDocs</a> to build Docker's 274 documentation. Of course, you don't need to install this generator 275 to build the documentation, it is included with container. 276 277 You should always check your documentation for grammar and spelling. The best 278 way to do this is with <a href="http://www.hemingwayapp.com/" 279 target="_blank">an online grammar checker</a>. 280 281 When you change a documentation source file, you should test your change 282 locally to make sure your content is there and any links work correctly. You 283 can build the documentation from the local host. The build starts a container 284 and loads the documentation into a server. As long as this container runs, you 285 can browse the docs. 286 287 1. In a terminal, change to the root of your `docker-fork` repository. 288 289 $ cd ~/repos/docker-fork 290 291 2. Make sure you are in your feature branch. 292 293 $ git status 294 On branch dry-run-test 295 Your branch is up-to-date with 'origin/dry-run-test'. 296 nothing to commit, working directory clean 297 298 3. Build the documentation. 299 300 $ make docs 301 302 When the build completes, you'll see a final output message similar to the 303 following: 304 305 Successfully built ee7fe7553123 306 docker run --rm -it -e AWS_S3_BUCKET -e NOCACHE -p 8000:8000 "docker-docs:dry-run-test" mkdocs serve 307 Running at: http://0.0.0.0:8000/ 308 Live reload enabled. 309 Hold ctrl+c to quit. 310 311 4. Enter the URL in your browser. 312 313 If you are running Boot2Docker, replace the default localhost address 314 (0.0.0.0) with your DOCKERHOST value. You can get this value at any time by 315 entering `boot2docker ip` at the command line. 316 317 5. Once in the documentation, look for the red notice to verify you are seeing the correct build. 318 319 ![Beta documentation](/project/images/red_notice.png) 320 321 6. Navigate to your new or changed document. 322 323 7. Review both the content and the links. 324 325 8. Return to your terminal and exit out of the running documentation container. 326 327 328 ## Where to go next 329 330 Congratulations, you have successfully completed the basics you need to 331 understand the Docker test framework. In the next steps, you use what you have 332 learned so far to [contribute to Docker by working on an 333 issue](/project/make-a-contribution/).