allow ANSIBLE_KEEP_REMOTE_FILES for local test runner (#33357)

* allow ANSIBLE_KEEP_REMOTE_FILES for local test runner
* add ANSIBLE_KEEP_REMOTE_FILES to tox.ini, update docs
* Clarify handling of environment variables.

docs/docsite/rst/dev_guide/testing_running_locally.rst

@@ -33,6 +33,19 @@ An API key is required to use this feature.
 
 See the `list of supported platforms and versions <https://github.com/ansible/ansible/blob/devel/test/runner/completion/remote.txt>`_ for additional details.
 
+Environment Variables
+---------------------
+
+When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are:
+
+* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options. 
+* Not exposed to the test environment unless whitelisted in ``test/runner/lib/util.py`` in the ``common_environment`` function.
+* Not exposed to the test environment when using the ``--tox`` option unless whitelisted in ``test/runner/tox.ini`` by the ``passenv`` definition.
+
+    Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would 
+    require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set 
+    and the tests executed. This is useful for debugging tests inside a container by following the 
+    :ref:`Debugging AnsibleModule-based modules <debugging_ansiblemodule_based_modules>` instructions.
 
 Interactive Shell
 =================
@@ -42,6 +55,7 @@ Use the ``ansible-test shell`` command to get an interactive shell in the same e
 * ``ansible-test shell --docker`` - Open a shell in the default docker container.
 * ``ansible-test shell --tox --python 3.6`` - Open a shell in the Python 3.6 ``tox`` environment.
 
+
 Code Coverage
 =============
 

test/runner/lib/util.py

@@ -385,6 +385,7 @@ def common_environment():
         # MacOS High Sierra Compatibility
         # http://sealiesoftware.com/blog/archive/2017/6/5/Objective-C_and_fork_in_macOS_1013.html
         'OBJC_DISABLE_INITIALIZE_FORK_SAFETY',
+        'ANSIBLE_KEEP_REMOTE_FILES',
     )
 
     env.update(pass_vars(required=required, optional=optional))

test/runner/tox.ini

@@ -5,7 +5,7 @@ minversion = 2.5.0
 [testenv]
 changedir = {toxinidir}/../../
 commands = {posargs}
-passenv = HOME LC_ALL SHIPPABLE*
+passenv = HOME LC_ALL SHIPPABLE* ANSIBLE_KEEP_REMOTE_FILES
 args_are_paths = False
 deps = setuptools == 35.0.2
     wheel < 0.30.0 ; python_version < '2.7'