diff --git a/test/integration/README.md b/test/integration/README.md index e5006f5fda2..057784c113c 100644 --- a/test/integration/README.md +++ b/test/integration/README.md @@ -9,6 +9,12 @@ Some tests may require credentials. Credentials may be specified with `credenti Tests should be run as root. +Quick Start +=========== + +To get started quickly using Docker containers for testing, +see [Tests in Docker containers](#tests-in-docker-containers). + Configuration ============= @@ -94,20 +100,54 @@ Run the tests: Tests in Docker containers ========================== -It is possible to run tests in Docker containers. +If you have a Linux system with Docker installed, running integration tests using the same Docker containers used by +the Ansible continuous integration (CI) system is recommended. + +> Using Docker Engine to run Docker on a non-Linux host is not recommended. Some tests, such as those that manage +> services or use local SSH connections are known to fail in such an environment. For best results, install Docker on a +> full Linux distribution such as Ubuntu, running on real hardware or in a virtual machine. -For example, to run test `test_ping` from non_destructive suite on Ubuntu 14.04 container: +## Running Integration Tests + +To run all integration test targets with the default settings in a Centos 7 container, run `make integration` from the repository root. + +You can also run specific tests or select a different Linux distribution. +For example, to run the test `test_ping` from the non_destructive target on a Ubuntu 14.04 container: - go to the repository root -- and execute `TARGET=ubuntu1404 MAKE_TARGET=non_destructive TEST_FLAGS='--tags test_ping' ./test/utils/run_tests.sh` +- and execute `make integration IMAGE=ansible/ansible:ubuntu1404 TARGET=non_destructive TEST_FLAGS='--tags test_ping'` + +## Container Images + +Use the prefix `ansible/ansible:` with the image names below. -Available targets (containers): +> Running `make integration` will automatically download the container image you have specified, if it is not already +> available. However, you will be responsible for keeping the container images up-to-date using `docker pull`. + +### Python 2 + +Most container images are for testing with Python 2: - centos6 - centos7 - fedora-rawhide - fedora23 - opensuseleap - - ubuntu1204 - - ubuntu1404 + - ubuntu1204 (requires `PRIVILEGED=true`) + - ubuntu1404 (requires `PRIVILEGED=true`) - ubuntu1604 + +### Python 3 + +To test with Python 3 you must set `PYTHON3=1` and use the following images: + + - ubuntu1604py3 + +## Additional Options + +There are additional environment variables that can be used. A few of the more useful ones: + + - `KEEP_CONTAINERS=onfailure` - Containers will be preserved if tests fail. + - `KEEP_CONTAINERS=1` - Containers will always be preserved. + - `SHARE_SOURCE=1` - Changes to source from the host or container will be shared between host and container. + _**CAUTION:** Files created by the container will be owned by root on the host._ diff --git a/test/utils/run_tests.sh b/test/utils/run_tests.sh deleted file mode 100755 index e8996b0ddab..00000000000 --- a/test/utils/run_tests.sh +++ /dev/null @@ -1,47 +0,0 @@ -#!/bin/sh - -if [ "${SHIPPABLE}" = "true" ]; then - echo "It appears this job is running on Shippable instead of Travis." - if [ "${IS_PULL_REQUEST}" = "true" ]; then - echo "Please rebase the branch used for this pull request." - else - echo "This branch needs to be updated to work with Shippable." - fi - exit 1 -fi - -set -e -set -u -set -x - -LINKS="--link=httptester:ansible.http.tests --link=httptester:sni1.ansible.http.tests --link=httptester:sni2.ansible.http.tests --link=httptester:fail.ansible.http.tests" - -if [ "${TARGET}" = "sanity" ]; then - ./test/code-smell/replace-urlopen.sh . - ./test/code-smell/use-compat-six.sh lib - ./test/code-smell/boilerplate.sh - ./test/code-smell/required-and-default-attributes.sh - if test x"$TOXENV" != x'py24' ; then tox ; fi - if test x"$TOXENV" = x'py24' ; then python2.4 -V && python2.4 -m compileall -fq -x 'module_utils/(a10|rax|openstack|ec2|gce|docker_common|azure_rm_common|vca|vmware|gcp|gcdns).py' lib/ansible/module_utils ; fi -else - if [ ! -e /tmp/cid_httptester ]; then - docker pull ansible/ansible:httptester - docker run -d --name=httptester ansible/ansible:httptester > /tmp/cid_httptester - fi - export C_NAME="testAbull_$$_$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 8 | head -n 1)" - docker pull ansible/ansible:${TARGET} - - # enable colors if output is going to a terminal - COLOR_SETTINGS="" - if [ -t 1 ]; then - COLOR_SETTINGS="--env TERM=$TERM" - fi - - docker run -d --volume="${PWD}:/root/ansible:Z" $LINKS --name "${C_NAME}" $COLOR_SETTINGS --env HTTPTESTER=1 ${TARGET_OPTIONS:=''} ansible/ansible:${TARGET} > /tmp/cid_${TARGET} - docker exec -ti $(cat /tmp/cid_${TARGET}) /bin/sh -c "export TEST_FLAGS='${TEST_FLAGS:-''}'; cd /root/ansible; . hacking/env-setup; (cd test/integration; LC_ALL=en_US.utf-8 make ${MAKE_TARGET:-})" - docker kill $(cat /tmp/cid_${TARGET}) - - if [ "X${TESTS_KEEP_CONTAINER:-""}" = "X" ]; then - docker rm -vf "${C_NAME}" - fi -fi