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: 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: 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: Optional[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: Optional[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.
- property 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
- property 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: Path, test_id: int) 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
- 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.