ensure-tox: make idempotent and update testing

This role currently does

 which tox || pip install --user tox

and then sets "tox_exectuable" iff it has installed tox into the
user's pip environment.

This isn't idempotent -- if you run ensure-tox again, it will again
run "which tox" and miss that it already installed tox in the private
pip environment.  Instead, make it look for
"which {{ tox_executable }}" ... this way it will find the install it
just did if it runs again.

There seems to be no reason to only set "tox_exectuable" in the case
this role had to install tox.  Make this *always* set tox_exectuable
so that you can run ensure-tox and then be sure tox_exectuable is
something sane.

The current testing assumes that tox is installed in the base image.
We are working to remove this assumption; remove this part of the
test.

Rework the testing to first clear out any existing tox, which is
present on most images but will have no effect on the -plain images.
Then test when we install fresh it goes into the user pip install
area, and then test if we explicitly set tox_exectuable it overrides.

Change-Id: I36cfb62f2a2e2b9c2bbe92b46ed0b8098a873732

roles/ensure-tox/README.rst

@@ -1,14 +1,19 @@
 Ensure tox is installed
 
-If tox is not already installed, it will be installed via pip in the
+Look for ``tox``, and if not found, install it via ``pip`` in the user
-user install directory (i.e., "pip install --user").
+install directory (i.e., ``pip install --user``).
+
+After running this role, ``tox_executable`` will be set as the path to
+a valid ``tox``.
 
 **Role Variables**
 
 .. zuul:rolevar:: tox_executable
    :default: ``tox``
 
-   Optional path to point tox executable
+   Look for an existing ``tox`` at this specific path.  Note the
+   default (``tox``) effectively means to find tox in the current
+   ``$PATH``.
 
 .. zuul:rolevar:: tox_prefer_python2
    :default: ``false``

roles/ensure-tox/tasks/main.yaml

@@ -16,17 +16,23 @@
     fi
     {% endif %}
 
-    type tox || $PIP install --user tox
+    type {{ tox_executable }} || $PIP install --user tox
   args:
     executable: /bin/bash
   register: result
   changed_when: "'Successfully installed' in result.stdout"
 
-- name: Set tox_executable fact
+- name: Set tox_executable fact to pip installed
   set_fact:
     tox_executable: "{{ ansible_user_dir }}/.local/bin/tox"
     cacheable: true
   when: result is changed
 
+- name: Set tox_exectuable fact to found tox
+  set_fact:
+    tox_executable: "{{ tox_executable }}"
+    cacheable: true
+  when: result is not changed
+
 - name: Output tox version
   command: "{{ tox_executable }} --version"

test-playbooks/ensure-tox.yaml

@@ -1,35 +1,5 @@
 - hosts: all
-  name: Test ensure-tox when tox is installed in system default
+  name: Remove any pre-installed tox
-  tasks:
-    - name: Verify tox is pre-installed on OpenDev images
-      command: "tox --version"
-    - name: Run ensure-tox with tox already installed
-      include_role:
-        name: ensure-tox
-    - name: Verify tox_executable is not set by ensure-tox
-      assert:
-        that:
-          - tox_executable is not defined
-
-- hosts: all
-  name: Test ensure-tox when tox_executable is already set and tox is installed
-  tasks:
-    - name: Install tox inside a virtualenv
-      pip:
-        name: tox
-        virtualenv: "{{ ansible_user_dir }}/tox-venv"
-    - name: Run ensure-tox with tox not installed
-      include_role:
-        name: ensure-tox
-      vars:
-        tox_executable: "{{ ansible_user_dir }}/tox-venv/bin/tox"
-    - name: Verify tox_executable is not set by ensure-tox
-      assert:
-        that:
-          - tox_executable is not defined
-
-- hosts: all
-  name: Remove pre-installed tox
   tasks:
     - name: Remove tox package with pip
       shell: pip uninstall -y tox
@@ -45,12 +15,8 @@
       failed_when: result.rc == 0
 
 - hosts: all
-  name: Test ensure-tox when tox is not installed
+  name: Test ensure-tox installs into user environment
   tasks:
-    - name: Remove tox package
-      shell: pip uninstall tox || pip3 uninstall tox
-      failed_when: false
-      become: true
     - name: Verify tox is not installed
       command: "tox --version"
       register: result
@@ -66,3 +32,21 @@
       command: "{{ tox_executable }} --version"
       register: result
       failed_when: result.rc != 0
+
+- hosts: all
+  name: Test ensure-tox when tox_executable is set to an already installed tox
+  tasks:
+    - name: Install tox inside a virtualenv
+      pip:
+        name: tox
+        virtualenv: "{{ ansible_user_dir }}/tox-venv"
+    - name: Run ensure-tox pointing to an already installed tox
+      include_role:
+        name: ensure-tox
+      vars:
+        tox_executable: "{{ ansible_user_dir }}/tox-venv/bin/tox"
+    - name: Verify tox_executable is set to the virtualenv tox
+      assert:
+        that:
+          - tox_executable == '{{ ansible_user_dir}}/tox-venv/bin/tox'
+