atex 0.8__py3-none-any.whl → 0.9__py3-none-any.whl

atex/executor/executor.py

@@ -1,4 +1,6 @@
 import os
+import enum
+import time
 import select
 import threading
 import contextlib
@@ -27,10 +29,12 @@ class Executor:
         tests_data = atex.fmf.FMFTests(tests_repo, "/plans/default")
 
         with Executor(tests_data, conn) as e:
-            e.upload_tests(tests_repo)
-            e.setup_plan()
-            e.run_test("/some/test", "results/here.json", "uploaded/files/here")
+            e.upload_tests()
+            e.plan_prepare()
+            Path("output_here").mkdir()
+            e.run_test("/some/test", "output_here")
             e.run_test(...)
+            e.plan_finish()
 
     One Executor instance may be used to run multiple tests sequentially.
     In addition, multiple Executor instances can run in parallel on the same
@@ -39,27 +43,31 @@ class Executor:
         conn.cmd(["mkdir", "-p", "/shared"])
 
         with Executor(tests_data, conn, state_dir="/shared") as e:
-            e.upload_tests(tests_repo)
-            e.setup_plan()
+            e.upload_tests()
+            e.plan_prepare()
 
         # in parallel (ie. threading or multiprocessing)
         with Executor(tests_data, unique_conn, state_dir="/shared") as e:
             e.run_test(...)
     """
 
-    def __init__(self, fmf_tests, connection, *, state_dir=None):
+    def __init__(self, fmf_tests, connection, *, env=None, state_dir=None):
         """
         'fmf_tests' is a class FMFTests instance with (discovered) tests.
 
         'connection' is a class Connection instance, already fully connected.
 
+        'env' is a dict of extra environment variables to pass to the
+        plan prepare/finish scripts and to all tests.
+
         'state_dir' is a string or Path specifying path on the remote system for
         storing additional data, such as tests, execution wrappers, temporary
         plan-exported variables, etc. If left as None, a tmpdir is used.
         """
         self.lock = threading.RLock()
-        self.conn = connection
         self.fmf_tests = fmf_tests
+        self.conn = connection
+        self.env = env or {}
         self.state_dir = state_dir
         self.work_dir = None
         self.tests_dir = None
@@ -96,6 +104,9 @@ class Executor:
                 # use the tmpdir as work_dir, avoid extra mkdir over conn
                 self.work_dir = tmp_dir
 
+        # create / truncate the TMT_PLAN_ENVIRONMENT_FILE
+        self.conn.cmd(("truncate", "-s", "0", self.plan_env_file), check=True)
+
     def cleanup(self):
         with self.lock:
             work_dir = self.work_dir
@@ -109,8 +120,12 @@ class Executor:
             self.plan_env_file = None
 
     def __enter__(self):
-        self.setup()
-        return self
+        try:
+            self.setup()
+            return self
+        except Exception:
+            self.cleanup()
+            raise
 
     def __exit__(self, exc_type, exc_value, traceback):
         self.cleanup()
@@ -131,13 +146,32 @@ class Executor:
             f"remote:{self.tests_dir}",
         )
 
-    def setup_plan(self):
+    def _run_prepare_scripts(self, scripts):
+        # make envionment for 'prepare' scripts
+        env = {
+            **self.fmf_tests.plan_env,
+            **self.env,
+            "TMT_PLAN_ENVIRONMENT_FILE": self.plan_env_file,
+        }
+        env_args = (f"{k}={v}" for k, v in env.items())
+        # run the scripts
+        for script in scripts:
+            self.conn.cmd(
+                ("env", *env_args, "bash"),
+                input=script,
+                text=True,
+                check=True,
+                stdout=None if util.in_debug_mode() else subprocess.DEVNULL,
+                stderr=subprocess.STDOUT,
+            )
+
+    def plan_prepare(self):
         """
         Install packages and run scripts extracted from a TMT plan by a FMFTests
         instance given during class initialization.
 
-        Also prepare additional environment for tests, ie. create and export
-        a path to TMT_PLAN_ENVIRONMENT_FILE.
+        Also run additional scripts specified under the 'prepare' step inside
+        the fmf metadata of a plan.
         """
         # install packages from the plan
         if self.fmf_tests.prepare_pkgs:
@@ -151,65 +185,74 @@ class Executor:
                 stderr=subprocess.STDOUT,
             )
 
-        # make envionment for 'prepare' scripts
-        self.conn.cmd(("truncate", "-s", "0", self.plan_env_file), check=True)
-        env = self.fmf_tests.plan_env.copy()
-        env["TMT_PLAN_ENVIRONMENT_FILE"] = self.plan_env_file
-        env_args = (f"{k}={v}" for k, v in env.items())
+        # run 'prepare' scripts from the plan
+        if scripts := self.fmf_tests.prepare_scripts:
+            self._run_prepare_scripts(scripts)
 
-        # run the prepare scripts
-        for script in self.fmf_tests.prepare_scripts:
-            self.conn.cmd(
-                ("env", *env_args, "bash"),
-                input=script,
-                text=True,
-                check=True,
-                stdout=None if util.in_debug_mode() else subprocess.DEVNULL,
-                stderr=subprocess.STDOUT,
-            )
+    def plan_finish(self):
+        """
+        Run any scripts specified under the 'finish' step inside
+        the fmf metadata of a plan.
+        """
+        if scripts := self.fmf_tests.finish_scripts:
+            self._run_prepare_scripts(scripts)
 
-    def run_test(self, test_name, json_file, files_dir, *, env=None):
+    class State(enum.Enum):
+        STARTING_TEST = enum.auto()
+        READING_CONTROL = enum.auto()
+        WAITING_FOR_EXIT = enum.auto()
+        RECONNECTING = enum.auto()
+
+    def run_test(self, test_name, output_dir, *, env=None):
         """
         Run one test on the remote system.
 
         'test_name' is a string with test name.
 
-        'json_file' is a destination file (string or Path) for results.
-
-        'files_dir' is a destination dir (string or Path) for uploaded files.
+        'output_dir' is a destination dir (string or Path) for results reported
+        and files uploaded by the test. Results are always stored in a line-JSON
+        format in a file named 'results', files are always uploaded to directory
+        named 'files', both inside 'output_dir'.
+        The path for 'output_dir' must already exist and be an empty directory
+        (ie. typically a tmpdir).
 
         'env' is a dict of extra environment variables to pass to the test.
 
         Returns an integer exit code of the test script.
         """
+        output_dir = Path(output_dir)
         test_data = self.fmf_tests.tests[test_name]
 
-        # start with fmf-plan-defined environment
-        env_vars = self.fmf_tests.plan_env.copy()
-        # append fmf-test-defined environment into it
-        for item in fmf.listlike(test_data, "environment"):
-            env_vars.update(item)
-        # append additional variables typically exported by tmt
-        env_vars["TMT_PLAN_ENVIRONMENT_FILE"] = self.plan_env_file
-        env_vars["TMT_TEST_NAME"] = test_name
-        env_vars["ATEX_TEST_NAME"] = test_name
-        # append variables given to this function call
-        if env:
-            env_vars.update(env)
-
         # run a setup script, preparing wrapper + test scripts
         setup_script = scripts.test_setup(
             test=scripts.Test(test_name, test_data, self.fmf_tests.test_dirs[test_name]),
             tests_dir=self.tests_dir,
             wrapper_exec=f"{self.work_dir}/wrapper.sh",
             test_exec=f"{self.work_dir}/test.sh",
+            test_yaml=f"{self.work_dir}/metadata.yaml",
         )
         self.conn.cmd(("bash",), input=setup_script, text=True, check=True)
 
+        # start with fmf-plan-defined environment
+        env_vars = {
+            **self.fmf_tests.plan_env,
+            "TMT_PLAN_ENVIRONMENT_FILE": self.plan_env_file,
+            "TMT_TEST_NAME": test_name,
+            "TMT_TEST_METADATA": f"{self.work_dir}/metadata.yaml",
+        }
+        # append fmf-test-defined environment into it
+        for item in fmf.listlike(test_data, "environment"):
+            env_vars.update(item)
+        # append the Executor-wide environment passed to __init__()
+        env_vars.update(self.env)
+        # append variables given to this function call
+        if env:
+            env_vars.update(env)
+
         with contextlib.ExitStack() as stack:
-            reporter = stack.enter_context(Reporter(json_file, files_dir))
-            testout_fd = stack.enter_context(reporter.open_tmpfile())
+            reporter = stack.enter_context(Reporter(output_dir, "results", "files"))
             duration = Duration(test_data.get("duration", "5m"))
+            control = testcontrol.TestControl(reporter=reporter, duration=duration)
 
             test_proc = None
             control_fd = None
@@ -223,23 +266,19 @@ class Executor:
                     test_proc.wait()
                 raise TestAbortedError(msg) from None
 
+            exception = None
+
             try:
-                # TODO: probably enum
-                state = "starting_test"
+                state = self.State.STARTING_TEST
                 while not duration.out_of_time():
                     with self.lock:
                         if self.cancelled:
                             abort("cancel requested")
 
-                    if state == "starting_test":
+                    if state == self.State.STARTING_TEST:
                         control_fd, pipe_w = os.pipe()
                         os.set_blocking(control_fd, False)
-                        control = testcontrol.TestControl(
-                            control_fd=control_fd,
-                            reporter=reporter,
-                            duration=duration,
-                            testout_fd=testout_fd,
-                        )
+                        control.reassign(control_fd)
                         # reconnect/reboot count (for compatibility)
                         env_vars["TMT_REBOOT_COUNT"] = str(reconnects)
                         env_vars["TMT_TEST_RESTART_COUNT"] = str(reconnects)
@@ -249,13 +288,13 @@ class Executor:
                         test_proc = self.conn.cmd(
                             ("env", *env_args, f"{self.work_dir}/wrapper.sh"),
                             stdout=pipe_w,
-                            stderr=testout_fd,
+                            stderr=reporter.testout_fobj.fileno(),
                             func=util.subprocess_Popen,
                         )
                         os.close(pipe_w)
-                        state = "reading_control"
+                        state = self.State.READING_CONTROL
 
-                    elif state == "reading_control":
+                    elif state == self.State.READING_CONTROL:
                         rlist, _, xlist = select.select((control_fd,), (), (control_fd,), 0.1)
                         if xlist:
                             abort(f"got exceptional condition on control_fd {control_fd}")
@@ -264,9 +303,9 @@ class Executor:
                             if control.eof:
                                 os.close(control_fd)
                                 control_fd = None
-                                state = "waiting_for_exit"
+                                state = self.State.WAITING_FOR_EXIT
 
-                    elif state == "waiting_for_exit":
+                    elif state == self.State.WAITING_FOR_EXIT:
                         # control stream is EOF and it has nothing for us to read,
                         # we're now just waiting for proc to cleanly terminate
                         try:
@@ -279,7 +318,7 @@ class Executor:
                                 self.conn.disconnect()
                                 # if reconnect was requested, do so, otherwise abort
                                 if control.reconnect:
-                                    state = "reconnecting"
+                                    state = self.State.RECONNECTING
                                     if control.reconnect != "always":
                                         control.reconnect = None
                                 else:
@@ -291,13 +330,18 @@ class Executor:
                         except subprocess.TimeoutExpired:
                             pass
 
-                    elif state == "reconnecting":
+                    elif state == self.State.RECONNECTING:
                         try:
                             self.conn.connect(block=False)
                             reconnects += 1
-                            state = "starting_test"
+                            state = self.State.STARTING_TEST
                         except BlockingIOError:
                             pass
+                        except ConnectionError:
+                            # can happen when ie. ssh is connecting over a LocalForward port,
+                            # causing 'read: Connection reset by peer' instead of timeout
+                            # - just retry again after a short delay
+                            time.sleep(0.5)
 
                     else:
                         raise AssertionError("reached unexpected state")
@@ -305,12 +349,19 @@ class Executor:
                 else:
                     abort("test duration timeout reached")
 
-                # testing successful, do post-testing tasks
+                # testing successful
 
                 # test wrapper hasn't provided exitcode
                 if control.exit_code is None:
                     abort("exitcode not reported, wrapper bug?")
 
+                return control.exit_code
+
+            except Exception as e:
+                exception = e
+                raise
+
+            finally:
                 # partial results that were never reported
                 if control.partial_results:
                     for result in control.partial_results.values():
@@ -320,59 +371,32 @@ class Executor:
                             control.nameless_result_seen = True
                         if testout := result.get("testout"):
                             try:
-                                reporter.link_tmpfile_to(testout_fd, testout, name)
+                                reporter.link_testout(testout, name)
                             except FileExistsError:
                                 raise testcontrol.BadReportJSONError(
                                     f"file '{testout}' already exists",
                                 ) from None
                         reporter.report(result)
 
-                # test hasn't reported a result for itself, add an automatic one
-                # as specified in RESULTS.md
-                # {"status": "pass", "testout": "output.txt"}
-                if not control.nameless_result_seen:
-                    reporter.link_tmpfile_to(testout_fd, "output.txt")
+                # if an unexpected infrastructure-related exception happened
+                if exception:
+                    try:
+                        reporter.link_testout("output.txt")
+                    except FileExistsError:
+                        pass
                     reporter.report({
-                        "status": "pass" if control.exit_code == 0 else "fail",
+                        "status": "infra",
+                        "note": repr(exception),
                         "testout": "output.txt",
                     })
 
-                return control.exit_code
-
-            except Exception:
-                # if the test hasn't reported a result for itself, but still
-                # managed to break something, provide at least the default log
-                # for manual investigation - otherwise test output disappears
-                if not control.nameless_result_seen:
+                # if the test hasn't reported a result for itself
+                elif not control.nameless_result_seen:
                     try:
-                        reporter.link_tmpfile_to(testout_fd, "output.txt")
-                        reporter.report({
-                            "status": "infra",
-                            "testout": "output.txt",
-                        })
-                    # in case outout.txt exists as a directory
+                        reporter.link_testout("output.txt")
                     except FileExistsError:
                         pass
-                raise
-
-
-#__all__ = [
-#    info.name for info in _pkgutil.iter_modules(__spec__.submodule_search_locations)
-#]
-#
-#
-#import importlib as _importlib
-#import pkgutil as _pkgutil
-#
-#
-#def __dir__():
-#    return __all__
-#
-#
-## lazily import submodules
-#def __getattr__(attr):
-#    # importing a module known to exist
-#    if attr in __all__:
-#        return _importlib.import_module(f".{attr}", __name__)
-#    else:
-#        raise AttributeError(f"module '{__name__}' has no attribute '{attr}'")
+                    reporter.report({
+                        "status": "pass" if control.exit_code == 0 else "fail",
+                        "testout": "output.txt",
+                    })

atex/executor/reporter.py

@@ -1,70 +1,72 @@
 import os
 import json
-import ctypes
-import ctypes.util
-import contextlib
 from pathlib import Path
 
 from .. import util
 
 
-libc = ctypes.CDLL(ctypes.util.find_library("c"), use_errno=True)
-
-# int linkat(int olddirfd, const char *oldpath, int newdirfd, const char *newpath, int flags)
-libc.linkat.argtypes = (
-    ctypes.c_int,
-    ctypes.c_char_p,
-    ctypes.c_int,
-    ctypes.c_char_p,
-    ctypes.c_int,
-)
-libc.linkat.restype = ctypes.c_int
-
-# fcntl.h:#define AT_EMPTY_PATH                0x1000  /* Allow empty relative pathname */
-AT_EMPTY_PATH = 0x1000
-
-# fcntl.h:#define AT_FDCWD             -100    /* Special value used to indicate
-AT_FDCWD = -100
-
-
-def linkat(*args):
-    if (ret := libc.linkat(*args)) == -1:
-        errno = ctypes.get_errno()
-        raise OSError(errno, os.strerror(errno))
-    return ret
-
-
 class Reporter:
     """
     Collects reported results (in a format specified by RESULTS.md) for
     a specific test, storing them persistently.
     """
 
-    def __init__(self, json_file, files_dir):
-        """
-        'json_file' is a destination file (string or Path) for results.
+    # internal name, stored inside 'output_dir' and hardlinked to
+    # 'testout'-JSON-key-specified result entries; deleted on exit
+    TESTOUT = "testout.temp"
 
-        'files_dir' is a destination dir (string or Path) for uploaded files.
+    def __init__(self, output_dir, results_file, files_dir):
         """
-        self.json_file = json_file
-        self.files_dir = Path(files_dir)
-        self.json_fobj = None
+        'output_dir' is a destination dir (string or Path) for results reported
+        and files uploaded.
 
-    def __enter__(self):
-        if self.json_file.exists():
-            raise FileExistsError(f"{self.json_file} already exists")
-        self.json_fobj = open(self.json_file, "w")
+        'results_file' is a file name inside 'output_dir' the results will be
+        reported into.
+
+        'files_dir' is a dir name inside 'output_dir' any files will be
+        uploaded to.
+        """
+        output_dir = Path(output_dir)
+        self.testout_file = output_dir / self.TESTOUT
+        self.results_file = output_dir / results_file
+        self.files_dir = output_dir / files_dir
+        self.output_dir = output_dir
+        self.results_fobj = None
+        self.testout_fobj = None
+
+    def start(self):
+        if self.testout_file.exists():
+            raise FileExistsError(f"{self.testout_file} already exists")
+        self.testout_fobj = open(self.testout_file, "wb")
+
+        if self.results_file.exists():
+            raise FileExistsError(f"{self.results_file} already exists")
+        self.results_fobj = open(self.results_file, "w", newline="\n")
 
         if self.files_dir.exists():
             raise FileExistsError(f"{self.files_dir} already exists")
         self.files_dir.mkdir()
 
-        return self
+    def stop(self):
+        if self.results_fobj:
+            self.results_fobj.close()
+            self.results_fobj = None
+
+        if self.testout_fobj:
+            self.testout_fobj.close()
+            self.testout_fobj = None
+            Path(self.testout_file).unlink()
+
+    def __enter__(self):
+        try:
+            self.start()
+            return self
+        except Exception:
+            self.stop()
+            raise
 
     def __exit__(self, exc_type, exc_value, traceback):
-        if self.json_fobj:
-            self.json_fobj.close()
-            self.json_fobj = None
+        self.stop()
 
     def report(self, result_line):
         """
@@ -72,35 +74,28 @@ class Reporter:
 
         'result_line' is a dict in the format specified by RESULTS.md.
         """
-        json.dump(result_line, self.json_fobj, indent=None)
-        self.json_fobj.write("\n")
-        self.json_fobj.flush()
+        json.dump(result_line, self.results_fobj, indent=None)
+        self.results_fobj.write("\n")
+        self.results_fobj.flush()
 
-    @contextlib.contextmanager
-    def open_tmpfile(self, open_mode=os.O_WRONLY):
-        """
-        Open an anonymous (name-less) file for writing and yield its file
-        descriptor (int) as context, closing it when the context is exited.
-        """
-        flags = open_mode | os.O_TMPFILE
-        fd = os.open(self.files_dir, flags, 0o644)
-        try:
-            yield fd
-        finally:
-            os.close(fd)
+    def _dest_path(self, file_name, result_name=None):
+        result_name = util.normalize_path(result_name) if result_name else "."
+        # /path/to/files_dir / path/to/subtest / path/to/file.log
+        file_path = self.files_dir / result_name / util.normalize_path(file_name)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        return file_path
 
-    def link_tmpfile_to(self, fd, file_name, result_name=None):
+    def open_file(self, file_name, result_name=None, mode="wb"):
         """
-        Store a file named 'file_name' in a directory relevant to 'result_name'
-        whose 'fd' (a file descriptor) was created by .open_tmpfile().
-
-        This function can be called multiple times with the same 'fd', and
-        does not close or otherwise alter the descriptor.
+        Open a file named 'file_name' in a directory relevant to 'result_name'.
+        Returns an opened file-like object that can be used in a context manager
+        just like with regular open().
 
-        If 'result_name' is not given, link files to the test (name) itself.
+        If 'result_name' (typically a subtest) is not given, open the file
+        for the test (name) itself.
         """
-        result_name = util.normalize_path(result_name) if result_name else "."
-        # /path/to/files_dir / path/to/subresult / path/to/file.log
-        file_path = self.files_dir / result_name / util.normalize_path(file_name)
-        file_path.parent.mkdir(parents=True, exist_ok=True)
-        linkat(fd, b"", AT_FDCWD, bytes(file_path), AT_EMPTY_PATH)
+        return open(self._dest_path(file_name, result_name), mode)
+
+    def link_testout(self, file_name, result_name=None):
+        # TODO: docstring
+        os.link(self.testout_file, self._dest_path(file_name, result_name))

atex/executor/scripts.py

@@ -1,4 +1,5 @@
 import collections
+import yaml
 from pathlib import Path
 
 from .. import util, fmf
@@ -102,7 +103,7 @@ def _install_packages(pkgs, extra_opts=None):
     """)  # noqa: E501
 
 
-def test_setup(*, test, wrapper_exec, test_exec, **kwargs):
+def test_setup(*, test, wrapper_exec, test_exec, test_yaml, **kwargs):
     """
     Generate a bash script that should prepare the remote end for test
     execution.
@@ -111,12 +112,12 @@ def test_setup(*, test, wrapper_exec, test_exec, **kwargs):
     scripts: a test script (contents of 'test' from FMF) and a wrapper script
     to run the test script.
 
+    'test' is a class Test instance.
+
     'wrapper_exec' is the remote path where the wrapper script should be put.
 
     'test_exec' is the remote path where the test script should be put.
 
-    'test' is a class Test instance.
-
     Any 'kwargs' are passed to test_wrapper().
     """
     out = "#!/bin/bash\n"
@@ -134,6 +135,11 @@ def test_setup(*, test, wrapper_exec, test_exec, **kwargs):
     if recommend := list(fmf.test_pkg_requires(test.data, "recommend")):
         out += _install_packages(recommend, ("--skip-broken",)) + "\n"
 
+    # write out test data
+    out += f"cat > '{test_yaml}' <<'ATEX_SETUP_EOF'\n"
+    out += yaml.dump(test.data).rstrip("\n")  # don't rely on trailing \n
+    out += "\nATEX_SETUP_EOF\n"
+
     # make the wrapper script
     out += f"cat > '{wrapper_exec}' <<'ATEX_SETUP_EOF'\n"
     out += test_wrapper(