Job dependencies

This commit introduces job dependency feature. With this feature, you can
define common dependency for each test inside job or with Job API inside suite.
With this feature, it should be easier to create tests which share their
dependencies.

It reads all the dependencies from the json file, where the user can specify
all the dependencies needed for this job. It uses the same json format as is
used in test docstrings. Part of this commit is a documentation update which
describes this feature more deeply.

Reference: avocado-framework#5504
Signed-off-by: Jan Richter <[email protected]>

Author: richtja

avocado/plugins/dependency.py

@@ -11,8 +11,17 @@
 #
 # Copyright: Red Hat Inc. 2021
 # Authors: Willian Rampazzo <[email protected]>
+import json
 
-from avocado.core.plugin_interfaces import PreTest
+from avocado.core.dependencies.dependency import Dependency
+from avocado.core.exceptions import JobBaseException
+from avocado.core.plugin_interfaces import JobPre, PreTest
+
+
+class DependencyResolverError(JobBaseException):
+    """
+    Error raised when issue occurred during dependency file resolution.
+    """
 
 
 class DependencyResolver(PreTest):
@@ -36,3 +45,33 @@ def pre_test_runnables(test_runnable, suite_config=None):  # pylint: disable=W02
         for dependency in unique_dependencies:
             dependency_runnables.append(dependency.to_runnable(test_runnable.config))
         return dependency_runnables
+
+
+class SuiteDependency(JobPre):
+    name = "suite-dependency"
+    description = "Applies a set of dependencies to every test within the suite"
+
+    def pre(self, job):
+        for suite in job.test_suites:
+            dependency_file_path = suite.config.get("job.run.dependency")
+            if dependency_file_path:
+                try:
+                    with open(
+                        dependency_file_path, encoding="utf-8"
+                    ) as dependency_file:
+                        try:
+                            dependencies_dict = json.load(dependency_file)
+                        except json.JSONDecodeError as e:
+                            raise DependencyResolverError(
+                                f"Issue with parsing dependency file at {dependency_file_path}: {e}"
+                            )
+                except FileNotFoundError as e:
+                    raise DependencyResolverError(
+                        f"Dependency file not found at {dependency_file_path}: {e}"
+                    )
+                dependencies = []
+                for dependency in dependencies_dict:
+                    dependencies.append(Dependency.from_dictionary(dependency))
+                for runnable in suite.tests:
+                    dependencies.extend(runnable.dependencies)
+                    runnable.dependencies = dependencies

avocado/plugins/run.py

@@ -170,6 +170,19 @@ def configure(self, parser):
             long_arg="--job-category",
         )
 
+        help_msg = (
+            "Path to the json file with list of dependencies needed for each test."
+        )
+        settings.register_option(
+            section="job.run",
+            key="dependency",
+            help_msg=help_msg,
+            parser=parser,
+            default=None,
+            metavar="FILE",
+            long_arg="--job-dependency",
+        )
+
         settings.add_argparser_to_option(
             namespace="job.run.timeout",
             metavar="SECONDS",

docs/source/guides/user/chapters/dependencies.rst

@@ -93,6 +93,52 @@ Defining a dependency in the class docstring will fulfill the dependency for
 every test within a test class. Defining a dependency in the test docstring
 will fulfill the dependency for that single test only.
 
+Defining a job dependency
+-------------------------
+
+Managing dependencies across multiple tests within a job can be streamlined
+using the Job Dependency Feature. If your tests share common dependencies,
+there's no need to specify them individually for each test. Instead, you can
+utilize the Job Dependency Feature to apply a set of dependencies to every
+test within the job.
+
+Once it is enabled, Avocado will read the list of common dependencies from
+the specified JSON file and automatically apply them to each test within
+the job.
+
+Enabling the Job Dependency
++++++++++++++++++++++++++++
+
+To enable this feature, you have two options:
+
+  1. Command-line Option:
+       Use of the `--job-dependency` option of the avocado run command
+       to specify the path to the dependency JSON file::
+
+        avocado run --job-dependency=dependencies.json tests/
+
+  2. Configuration File:
+       Alternatively, you can set the path to the dependency JSON file
+       using the `job.run.dependency` configuration option in the Avocado
+       configuration file.
+
+.. tip:: If you're using the Job API, you have the flexibility to define
+         different dependencies for each suite. Simply modify the
+         `job.run.dependency` value in the suite configuration during suite
+         creation.
+
+Dependency File Format
+++++++++++++++++++++++
+
+The dependency file follows the same format as the test dependency defined
+in the docstring. If you have multiple dependencies, ensure to encapsulate
+them within a JSON list::
+
+    [
+    {"type": "package", "name": "hello"},
+    {"type": "package", "name": "bash"}
+    ]
+
 Supported types of dependencies
 -------------------------------
 

selftests/check.py

@@ -26,11 +26,11 @@
     "job-api-6": 4,
     "job-api-7": 1,
     "nrunner-interface": 70,
-    "nrunner-requirement": 20,
+    "nrunner-requirement": 24,
     "unit": 669,
     "jobs": 11,
     "functional-parallel": 302,
-    "functional-serial": 5,
+    "functional-serial": 6,
     "optional-plugins": 0,
     "optional-plugins-golang": 2,
     "optional-plugins-html": 3,

selftests/functional/serial/requirements.py

@@ -104,6 +104,32 @@ def test_a(self):
         self.check_hello()
 '''
 
+TEST_WITHOUT_DEPENDENCY = """from avocado import Test
+from avocado.utils import process
+
+class SuccessTest(Test):
+
+    def check_hello(self):
+        result = process.run("hello", ignore_status=True)
+        self.assertEqual(result.exit_status, 0)
+        self.assertIn('Hello, world!', result.stdout_text,)
+
+    def test_a(self):
+        self.check_hello()
+
+    def test_b(self):
+        self.check_hello()
+
+    def test_c(self):
+        self.check_hello()
+"""
+
+DEPENDENCY_FILE = """
+[
+	{"type": "package", "name": "hello"}
+]
+"""
+
 
 class BasicTest(TestCaseTmpDir, Test):
     """
@@ -246,3 +272,25 @@ def test_dependency_duplicates(self):
                 "PASS 1",
                 result.stdout_text,
             )
+
+    @skipUnless(os.getenv("CI"), skip_install_message)
+    def test_job_dependency(self):
+        with script.Script(
+            os.path.join(self.tmpdir.name, "test_multiple_success.py"),
+            TEST_WITHOUT_DEPENDENCY,
+        ) as test:
+            command = self.get_command(test.path)
+            with script.Script(
+                os.path.join(self.tmpdir.name, "dependency.json"), DEPENDENCY_FILE
+            ) as dependency_config:
+                command = f"{command} --job-dependency={dependency_config.path}"
+                result = process.run(command, ignore_status=True)
+                self.assertEqual(result.exit_status, exit_codes.AVOCADO_ALL_OK)
+                self.assertIn(
+                    "PASS 3",
+                    result.stdout_text,
+                )
+                self.assertNotIn(
+                    "vim-common",
+                    result.stdout_text,
+                )

setup.py

@@ -419,6 +419,7 @@ def run(self):
                 "teststmpdir = avocado.plugins.teststmpdir:TestsTmpDir",
                 "human = avocado.plugins.human:HumanJob",
                 "testlogsui = avocado.plugins.testlogs:TestLogsUI",
+                "suite-dependency = avocado.plugins.dependency:SuiteDependency",
             ],
             "avocado.plugins.test.pre": [
                 "dependency = avocado.plugins.dependency:DependencyResolver",