More tests and documentation

ansible_runner/interface.py

@@ -903,6 +903,8 @@ def get_role_list(collection=None, playbook_dir=None, **kwargs):
     '''
     Run an ``ansible-doc`` command to get list of installed collection roles.
 
+    Only roles that have an argument specification defined are returned.
+
     .. note:: Version added: 2.2
 
     :param str collection: A fully qualified collection name used to filter the results.

docs/python_interface.rst

@@ -106,11 +106,11 @@ While running the command within the container the current local working diretor
 
 *Version added: 2.2*
 
-This function will execute the ``ansible-doc`` command to return the list of installed roles.
-This data can be fetched from either the local environment or from within a container image
-based on the parameters passed. It will run in the foreground and return a tuple of output
-and error response when finished. Successful output will be in JSON format as returned from
-``ansible-doc``.
+This function will execute the ``ansible-doc`` command to return the list of installed roles
+that have an argument specification defined. This data can be fetched from either the local
+environment or from within a container image based on the parameters passed. It will run in
+the foreground and return a tuple of output and error response when finished. Successful output
+will be in JSON format as returned from ``ansible-doc``.
 
 ``get_role_argspec()`` helper function
 --------------------------------------
@@ -328,6 +328,34 @@ Usage examples
   print("out: {}".format(out))
   print("err: {}".format(err))
 
+.. code-block:: python
+
+  # get all roles with an arg spec installed locally
+  out, err = ansible_runner.get_role_list()
+  print("out: {}".format(out))
+  print("err: {}".format(err))
+
+.. code-block:: python
+
+  # get roles with an arg spec from the `foo.bar` collection in a container
+  out, err = ansible_runner.get_role_list(collection='foo.bar', process_isolation=True, container_image='network-ee')
+  print("out: {}".format(out))
+  print("err: {}".format(err))
+
+.. code-block:: python
+
+  # get the arg spec for role `baz` from the locally installed `foo.bar` collection
+  out, err = ansible_runner.get_role_argspec('baz', collection='foo.bar')
+  print("out: {}".format(out))
+  print("err: {}".format(err))
+
+.. code-block:: python
+
+  # get the arg spec for role `baz` from the `foo.bar` collection installed in a container
+  out, err = ansible_runner.get_role_argspec('baz', collection='foo.bar', process_isolation=True, container_image='network-ee')
+  print("out: {}".format(out))
+  print("err: {}".format(err))
+
 Providing custom behavior and inputs
 ------------------------------------
 

test/integration/test_interface.py

@@ -363,34 +363,45 @@ def test_get_role_list(project_fixtures, skipif_pre_ansible211):
     Test get_role_list() running locally, specifying a playbook directory
     containing our test role.
     """
-    use_role_example = str(project_fixtures / 'music' / 'project')
+    pdir = str(project_fixtures / 'music' / 'project')
     expected_role = {
         "collection": "",
         "entry_points": {
             "main": "The main entry point for the Into_The_Mystic role."
         }
     }
 
-    resp, err = get_role_list(playbook_dir=use_role_example)
+    resp, err = get_role_list(playbook_dir=pdir)
     assert isinstance(resp, dict)
+
+    # So that tests can work locally, where multiple roles might be returned,
+    # we check for this single role.
     assert 'Into_The_Mystic' in resp
     assert resp['Into_The_Mystic'] == expected_role
 
 
 @pytest.mark.test_all_runtimes
 def test_get_role_list_within_container(project_fixtures, runtime, skipif_pre_ansible211):
     """
-    Test get_role_list() running in a container. Because the test container
-    has no roles/collections installed, the returned output should be empty.
+    Test get_role_list() running in a container.
     """
+    pdir = str(project_fixtures / 'music')
+    expected = {
+        "Into_The_Mystic": {
+            "collection": "",
+            "entry_points": {
+                "main": "The main entry point for the Into_The_Mystic role."
+            }
+        }
+    }
     container_kwargs = {
         'process_isolation_executable': runtime,
         'process_isolation': True,
         'container_image': defaults.default_container_image
     }
-    resp, err = get_role_list(**container_kwargs)
+    resp, err = get_role_list(private_data_dir=pdir, playbook_dir="/runner/project", **container_kwargs)
     assert isinstance(resp, dict)
-    assert resp == {}
+    assert resp == expected
 
 
 def test_get_role_argspec(project_fixtures, skipif_pre_ansible211):
@@ -426,3 +437,45 @@ def test_get_role_argspec(project_fixtures, skipif_pre_ansible211):
     assert isinstance(resp, dict)
     assert 'Into_The_Mystic' in resp
     assert resp['Into_The_Mystic']['entry_points'] == expected_epoint
+
+
+@pytest.mark.test_all_runtimes
+def test_get_role_argspec_within_container(project_fixtures, runtime, skipif_pre_ansible211):
+    """
+    Test get_role_argspec() running inside a container. Since the test container
+    does not currently contain any collections or roles, specify playbook_dir
+    pointing to the project dir of private_data_dir so that we will find a role.
+    """
+    pdir = str(project_fixtures / 'music')
+    expected_epoint = {
+        "main": {
+            "options": {
+                "foghorn": {
+                    "default": True,
+                    "description": "If true, the foghorn blows.",
+                    "required": False,
+                    "type": "bool"
+                },
+                "soul": {
+                    "choices": [
+                        "gypsy",
+                        "normal"
+                    ],
+                    "description": "Type of soul to rock",
+                    "required": True,
+                    "type": "str"
+                }
+            },
+            "short_description": "The main entry point for the Into_The_Mystic role."
+        }
+    }
+
+    container_kwargs = {
+        'process_isolation_executable': runtime,
+        'process_isolation': True,
+        'container_image': defaults.default_container_image
+    }
+    resp, err = get_role_argspec('Into_The_Mystic', private_data_dir=pdir, playbook_dir="/runner/project", **container_kwargs)
+    assert isinstance(resp, dict)
+    assert 'Into_The_Mystic' in resp
+    assert resp['Into_The_Mystic']['entry_points'] == expected_epoint