Integration test readme update

Updates the readme to mention running the tests using golem.
Also provides instructions for making test development easier.

Signed-off-by: Derek McGowan <derek@mcgstyle.net> (github: dmcgowan)
This commit is contained in:
Derek McGowan 2016-04-12 14:03:56 -07:00
parent 55f1b7651f
commit ab2394446c

View file

@ -1,136 +1,63 @@
# Docker Registry Integration Testing # Docker Registry Integration Testing
These integration tests cover interactions between the Docker daemon and the These integration tests cover interactions between registry clients such as
registry server. All tests are run using the docker cli. the docker daemon and the registry server. All tests can be run using the
[golem integration test runner](https://github.com/docker/golem)
The compose configuration is intended to setup a testing environment for Docker The integration tests configure components using docker compose
using multiple registry configurations. These configurations include different (see docker-compose.yaml) and the runner can be using the golem
combinations of a v1 and v2 registry as well as TLS configurations. configuration file (see golem.conf).
## Running inside of Docker ## Running integration tests
### Get integration container
The container image to run the integation tests will need to be pulled or built
locally.
*Building locally* ### Run using multiversion script
```
$ docker build -t distribution/docker-integration .
```
### Run script The integration tests in the `contrib/docker-integration` directory can be simply
run by executing the run script `./run_multiversion.sh`. If there is no running
daemon to connect to, run as `./run_multiversion.sh -d`.
Invoke the tests within Docker through the `run.sh` script. This command will build the distribution image from the locally checked out
version and run against multiple versions of docker defined in the script. To
run a specific version of the registry or docker, Golem will need to be
executed manually.
``` ### Run manually using Golem
$ ./run.sh
```
Run with aufs driver and tmp volume Using the golem tool directly allows running against multiple versions of
**NOTE: Using a volume will prevent multiple runs from needing to the registry and docker. Running against multiple versions of the registry
re-pull images** can be useful for testing changes in the docker daemon which are not
``` covered by the default run script.
$ DOCKER_GRAPHDRIVER=aufs DOCKER_VOLUME=/tmp/volume ./run.sh
```
### Example developer flow #### Installing Golem
These tests are useful for developing both as a registry and docker Golem is distributed as an executable binary which can be installed from
core developer. The following setup may be used to do integration the [release page](https://github.com/docker/golem/releases/tag/v0.1).
testing between development versions
Insert into your `.zshrc` or `.bashrc` #### Running golem with docker
``` Additionally golem can be run as a docker image requiring no additonal
# /usr/lib/docker for Docker-in-Docker installation.
# Set this directory to make each invocation run much faster, without
# the need to repull images.
export DOCKER_VOLUME=$HOME/.docker-test-volume
# Use overlay for all Docker testing, try aufs if overlay not supported `docker run --privileged -v "$GOPATH/src/github.com/docker/distribution/contrib/docker-integration:/test" -w /test distribution/golem golem -rundaemon .`
export DOCKER_GRAPHDRIVER=overlay
# Name this according to personal preference #### Golem custom images
function rdtest() {
if [ "$1" != "" ]; then
DOCKER_BINARY=$GOPATH/src/github.com/docker/docker/bundles/$1/binary/docker
if [ ! -f $DOCKER_BINARY ]; then
current_version=`cat $GOPATH/src/github.com/docker/docker/VERSION`
echo "$DOCKER_BINARY does not exist"
echo "Current checked out docker version: $current_version"
echo "Checkout desired version and run 'make binary' from $GOPATH/src/github.com/docker/docker"
return 1
fi
fi
$GOPATH/src/github.com/docker/distribution/contrib/docker-integration/run.sh Golem tests version of software by defining the docker image to test.
}
```
Run with Docker release version Run with registry 2.2.1 and docker 1.10.3
```
$ rdtest
```
Run using local development version of docker `golem -i golem-dind:latest,docker:1.10.3-dind,1.10.3 -i golem-distribution:latest,registry:2.2.1 .`
```
$ cd $GOPATH/src/github.com/docker/docker
$ make binary
$ rdtest `cat VERSION`
```
## Running manually outside of Docker
### Install Docker Compose #### Use golem caching for developing tests
[Docker Compose Installation Guide](https://docs.docker.com/compose/install/) Golem allows caching image configuration to reduce test start up time.
Using this cache will allow tests with the same set of images to start
up quickly. This can be useful when developing tests and needing the
test to run quickly. If there are changes which effect the image (such as
building a new registry image), then startup time will be slower.
### Start compose setup Run this command multiple times and after the first time test runs
``` should start much quicker.
docker-compose up `golem -cache ~/.cache/docker/golem -i golem-dind:latest,docker:1.10.3-dind,1.10.3 -i golem-distribution:latest,registry:2.2.1 .`
```
### Install Certificates
The certificates must be installed in /etc/docker/cert.d in order to use TLS
client auth and use the CA certificate.
```
sudo sh ./install_certs.sh
```
### Test with Docker
Tag an image as with any other private registry. Attempt to push the image.
```
docker pull hello-world
docker tag hello-world localhost:5440/hello-world
docker push localhost:5440/hello-world
docker tag hello-world localhost:5441/hello-world
docker push localhost:5441/hello-world
# Perform login using user `testuser` and password `passpassword`
```
### Set /etc/hosts entry
Find the non-localhost ip address of local machine
### Run bats
Run the bats tests after updating /etc/hosts, installing the certificates, and
running the `docker-compose` script.
```
bats -p .
```
## Configurations
Port | V2 | TLS | Authentication
--- | --- | --- | ---
5000 | yes | no | none
5002 | yes | no | none
5440 | yes | yes | none
5441 | yes | yes | basic (testuser/passpassword)
5442 | yes | yes | TLS client
5443 | yes | yes | TLS client (no CA)
5444 | yes | yes | TLS client + basic (testuser/passpassword)
5445 | yes | yes (no CA) | none
5446 | yes | yes (no CA) | basic (testuser/passpassword)
5447 | yes | yes (no CA) | TLS client
5448 | yes | yes (SSLv3) | none