From cf4d436e07009e91e74664789953a8a5d6b2d823 Mon Sep 17 00:00:00 2001
From: Matt Clay <matt@mystile.com>
Date: Thu, 22 Sep 2016 23:51:53 -0700
Subject: [PATCH] Remove run_tests.sh and update docs. (#17719)

Removed the obsolete test/utils/run_tests.sh script in favor of
using the newer test/utils/shippable/integration.sh instead.
---
 test/integration/README.md | 52 +++++++++++++++++++++++++++++++++-----
 test/utils/run_tests.sh    | 47 ----------------------------------
 2 files changed, 46 insertions(+), 53 deletions(-)
 delete mode 100755 test/utils/run_tests.sh

diff --git a/test/integration/README.md b/test/integration/README.md
index e5006f5fda..057784c113 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.
 
-For example, to run test `test_ping` from non_destructive suite on Ubuntu 14.04 container:
+> 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.
+
+## 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'`
 
-Available targets (containers):
+## Container Images
+
+Use the prefix `ansible/ansible:` with the image names below.
+
+> 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 e8996b0dda..0000000000
--- 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