Pavilion Test Run Objects¶
Table of Contents
pavilion.pav_test module¶
Contains test run object definition and helper functions.
-
class
pavilion.test_run.
TestRun
(pav_cfg: pavilion.config.PavConfig, config, var_man=None, _id=None, rebuild=False, build_only=False)¶ The central pavilion test object. Handle saving, monitoring and running tests.
Test LifeCycle 1. Test Object is Created –
TestRun.__init__
- Test id and directory (
working_dir/test_runs/0000001
) are created. - Most test information files (config, status, etc) are created.
- Build script is created.
- Build hash is generated.
- Run script dry run generation is performed.
- Test is built. –
test.build()
- Test is finalized. –
test.finalize()
- Variables and config go through final resolution.
- Final run script is generated.
- Test is run. –
test.run()
- Results are gathered. –
test.gather_results()
Variables: - id (int) – The test id number.
- full_id (str) – The full test id number, including the config label. This may also be a string path to the test itself.
- cfg_label (str) – The config label for the configuration directory that defined this test. This is ephemeral, and may change between Pavilion invocations based on available configurations.
- config (dict) – The test’s configuration.
- test.path (Path) – The path to the test’s test_run directory.
- suite_path (Path) – The path to the test suite file that this test came from. May be None for artificially generated tests.
- results (dict) – The test results. Set None if results haven’t been gathered.
- builder (TestBuilder) – The test builder object, with information on the test’s build.
- build_origin_path (Path) – The path to the symlink to the original build directory. For bookkeeping.
- status (StatusFile) – The status object for this test.
- opt (TestRunOptions) – Test run options defined by OPTIONS_DEFAULTS
-
__init__
(pav_cfg: pavilion.config.PavConfig, config, var_man=None, _id=None, rebuild=False, build_only=False)¶ Create an new TestRun object. If loading an existing test instance, use the
TestRun.from_id()
method.Parameters: - pav_cfg – The pavilion configuration.
- config (dict) – The test configuration dictionary.
- build_only (bool) – Only build this test run, do not run it.
- rebuild (bool) – After determining the build name, deprecate it and select a new, non-deprecated build.
- _id (int) – The test id of an existing test. (You should be using TestRun.load).
-
build
(cancel_event=None, tracker: pavilion.build_tracker.BuildTracker = None)¶ Build the test using its builder object and symlink copy it to it’s final location. The build tracker will have the latest information on any encountered errors.
Parameters: - cancel_event (threading.Event) – Event to tell builds when to die.
- tracker – A build tracker for tracking multi-threaded builds.
Returns: True if build successful
-
gather_results
(run_result: int, regather: bool = False, log_file: TextIO = None)¶ Process and log the results of the test, including the default set of result keys.
Parameters: - run_result (int) – The return code of the test run.
- regather (bool) – Gather results without performing any changes to the test itself.
- log_file (IO[str]) – The file to save result logs to.
-
is_built
¶ Whether the build for this test exists.
Returns: True if the build exists (or the test doesn’t have a build), False otherwise. Return type: bool
-
job
¶ The job id of this test (saved to a
jobid
file). This should be set by the scheduler plugin as soon as it’s known.
-
classmethod
load
(pav_cfg, working_dir: pathlib.Path, test_id: int) → pavilion.test_run.test_run.TestRun¶ Load an old TestRun object given a test id.
Parameters: - pav_cfg – The pavilion config
- working_dir – The working directory where this test run lives.
- test_id (int) – The test’s id number.
Return type:
-
load_results
()¶ Load results from the results file.
:returns A dict of results, or None if the results file doesn’t exist. :rtype: dict
-
run
()¶ Run the test.
Return type: bool
Returns: The return code of the test command.
Raises: - TimeoutError – When the run times out.
- TestRunError – We don’t actually raise this, but might in the future.
-
save_results
(results)¶ Save the results to the test specific results file and the general pavilion results file.
Parameters: results (dict) – The results dictionary.
-
set_run_complete
()¶ Write a file in the test directory that indicates that the test has completed a run, one way or another. This should only be called when we’re sure their won’t be any more status changes.
-
wait
(timeout=None)¶ Wait for the test run to be complete. This works across hosts, as it simply checks for files in the run directory.
Parameters: timeout (Union(None,float)) – How long to wait in seconds. If this is None, wait forever. Raises: TimeoutError – if the timeout expires.
- Test id and directory (