Pavilion Test Run Objects

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__

  1. Test id and directory (working_dir/test_runs/0000001) are created.

  2. Most test information files (config, status, etc) are created.

  3. Build script is created.

  4. Build hash is generated.

  5. Run script dry run generation is performed.

  1. Test is built. – test.build()

  2. Test is finalized. – test.finalize()

    1. Variables and config go through final resolution.

    2. Final run script is generated.

  3. Test is run. – test.run()

  4. 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

TestRun

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.