Skip to main content

Test framework API

The following API functions are provided by the SST test framework. Tests may use these in combination with any built-in Python functions.

note

Whenever this reference refers to the sst-test-elements utility, the same is true of sst-test-core. The utilities are identical other than the search paths they use to locate tests.

run_sst​

The run_sst function should be used to run SST in a test. It runs SST as a subprocess in a separate thread and monitors the SST run time. run_sst will assert a test failure if the test times out (reaches timeout_sec) or if the return code does not match expected_rc. In all other cases, the test function invoking run_sst must assert a pass or failure.

run_sst(sdl_file, out_file, err_file=None, set_cwd=None, mpi_out_files="", other_args="", 
    num_ranks=None, num_threads=None, global_args=None, timeout_sec=120, expected_rc=0, 
    check_sdl_file=True, send_signal=signal.NSIG, signal_sec=3)

Parameters:

  • sdl_file (type: string) The SST input configuration file to run.
  • out_file (type: string) The full path of the output file. This is where stdout and potentially stderr will be piped.
  • err_file (type: string) If specified, stderr will be piped to this file rather than to the out_file. This should be a full path.
  • set_cwd (type: string) The path from which SST should be run. By default this will be the current directory. This should not be used unless a specific run directory is required.
  • mpi_out_files (type: string) Full path for intermediate (per-rank) output files generated by MPI.
  • other_args (type: string) Any arguments that should be provided to SST.
  • num_ranks (type: int) The number of ranks to run SST with. This will override the argument provided to sst-test-elements and in general should not be used.
  • num_threads (type: int) The number of threads to run SST with. This will override the argument provided to sst-test-elements and in general should not be used.
  • global_args (type: string) SST arguments generated by the sst-test-elements framework arguments. This argument should not be used by tests, they should use other_args instead.
  • timeout_sec (type: int) A timeout period in seconds after which SST will be terminated.
  • expected_rc (type: int) The expected return code from SST.
  • check_sdl_file (type: bool) If True, run_test will check that the sdl_file exists before trying to run it.
  • send_signal (type: signal) A signal to send to SST after signal_sec seconds. If signal.NSIG, no signal will be sent.
  • signal_sec (type: int) The number of seconds to let SST run before sending the signal specified in send_signal.
  • returns The SST command that was run.

Output​

run_sst requires a file path, out_file, to which both stdout and stderr will be redirected. This file should be uniquely named to avoid over-writing it from other tests, and should be placed in the directory returned by get_test_output_run_dir().

When SST is running multiple processes, each process generates its own output file(s). The file naming convention is determined by the OpenMPI version so it is recommended to use the test framework's testing_merge_mpi_files() function to merge the per-rank files into a single file. Otherwise the test needs to be aware of the different naming schemes in order to locate the output files. The base name of the files can be set using the mpi_out_files parameter. By default, the test framework will set it to <out_file>.testfile.

Querying test framework parameters​

get_test_output_run_dir​

Returns the location of the output run_data/ directory. This corresponds to the --out_dir argument to sst-test-elements and sst-test-core.

run_dir = get_test_output_run_dir()

get_test_output_tmp_dir​

Returns the location of the output tmp_data/ directory. This corresponds to the --out_dir argument to sst-test-elements and sst-test-core.

tmp_dir = get_test_output_tmp_dir()

get_testcase_name​

Returns the name of the test function being run.

test_name = get_testcase_name()

get_testsuite_dir​

Returns the path to the test suite that is being run.

test_suite_dir = get_testsuite_dir()

get_testsuite_name​

Returns the name of the test suite being run.

test_suite_name = get_testsuite_name()

testing_check_get_num_ranks​

Returns the number of ranks that SST will be run with. This corresponds to the --ranks argument to sst-test-elements and sst-test-core.

rank_count = testing_check_get_num_ranks()

testing_check_get_num_threads​

Returns the number of threads that SST will be run with. This corresponds to the --threads argument to sst-test-elements and sst-test-core.

thread_count = testing_check_get_num_threads()

testing_check_is_in_concurrent_mode​

Returns whether the testing framework is concurrently running tests and test suites. This corresponds to the --concurrent argument to sst-test-elements and sst-test-core.

concurrent = testing_check_is_in_concurrent_mode()

Querying host environment​

These functions may be used in combination with any other functions provided by Python.

host_os_get_distribution_type​

Returns a string with the OS type for OS distributions supported by SST.

  • OSX for macOS
  • CENTOS for CentOS
  • RHEL for Red Hat Enterprise Linux
  • UBUNTU for Ubuntu
  • ROCKY for Rocky Linux
  • UNDEFINED for any others
dist = host_os_get_distribution_type()

host_os_get_distribution_version​

Returns the OS distribution version.

dist_version = host_os_get_distribution_version()

host_os_get_kernel_arch()​

DEPRECATED: Use Python's platform.machine() instead. Returns the kernel system architecture.

host_os_get_kernel_release​

DEPRECATED: Use Python's platform.release() instead. Returns the kernel release number.

host_os_get_kernel_type​

DEPRECATED: Use Python's platform.system() instead. Returns the string "Linux" or "Darwin".

host_os_get_num_cores_on_system​

DEPRECATED: Use Python's multiprocessing.cpu_count() instead. Returns the number of logical cores on the system.

host_os_get_system_node_name​

DEPRECATED: Use Python's platform.node() instead. Returns the system node name.

host_os_is_centos​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if running on CentOS.

host_os_is_linux​

DEPRECATED: Use host_os_get_distribution_type() or Python's platform.system() instead. Returns true if the OS is a Linux distribution.

host_os_is_osx​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if the OS is a macOS distribution.

host_os_is_rhel​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if running on RedHat.

host_os_is_rocky​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if running on Rocky Linux.

host_os_is_toss​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if running on TOSS.

host_os_is_ubuntu​

DEPRECATED: Use host_os_get_distribution_type() instead. Returns true if running on Ubuntu.

Querying SST-Core configuration​

sst_core_config_include_file_get_value​

Check SST Core's build configuration file, sst_config.h for a #define. Return the value of the define as the requested type.

val = sst_core_config_include_file_get_value(define, type, default=None, disable_warning=False)

Parameters

  • define (type: string): The #define name to look for.
  • type (type: Type): The type to return the value as. May be str, int, etc.
  • default (type: Any) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: Any) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

sst_core_config_include_file_get_value_int​

DEPRECATED: Use sst_core_config_include_file_get_value instead.

Check SST Core's build configuration file, sst_config.h, for a #define. Return the integer value of the define.

val = sst_core_config_include_file_get_value_int(define, default=None, disable_warning=False)

Parameters

  • define (type: string): The #define name to look for.
  • default (type: int) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: int) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

sst_core_config_include_file_get_value_str​

DEPRECATED: Use sst_core_config_include_file_get_value instead.

Check SST Core's build configuration file, sst_config.h, for a #define. Return the integer value of the define.

val = sst_core_config_include_file_get_value_str(define, default=None, disable_warning=False)

Parameters

  • define (type: string) The #define name to look for.
  • default (type: string) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: string) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

Querying SST-Elements configuration​

sst_elements_config_include_file_get_value​

Check the SST-Elements build configuration file, sst_element_config.h, for a #define. Return the value of the define as the requested type.

val = sst_elements_config_include_file_get_value(define, type, default=None, disable_warning=False)

Parameters

  • define (type: string) The #define name to look for.
  • type (type: Type): The type to return the value as. May be str, int, etc.
  • default (type: Any) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: Any) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

sst_elements_config_include_file_get_value_int​

DEPRECATED: Use sst_elements_config_include_file_get_value instead.

Check the SST-Elements build configuration file, sst_element_config.h, for a #define. Return the integer value of the define.

val = sst_elements_config_include_file_get_value_int(define, default=None, disable_warning=False)

Parameters

  • define (type: string) The #define name to look for.
  • default (type: int) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: int) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

sst_elements_config_include_file_get_value_str​

Check the SST-Elements build configuration file, sst_element_config.h, for a #define. Return the integer value of the define.

val = sst_elements_config_include_file_get_value_str(define, default=None, disable_warning=False)

Parameters

  • define (type: string) The #define name to look for.
  • default (type: string) Default return value if the #define is not found.
  • disable_warning (type: bool) Set to True to disable a warning in the test frameworks log if the #define is not found.
  • returns (type: string) The returned data or the default value if not found in the include file.
  • raises SSTTestCaseException if (1) the type is incorrect or (2) no data was found and a default was not provided.

Querying the SST ELI registry​

SST's ELI registry file (sstsimulator.conf) contains information about the libraries and tests that have been registered with SST-Core. See the sst-register page for details on the file contents. These functions allow tests to query that file.

skip_on_sstsimulator_conf_empty_str​

This is a skip decorator that searches the SST ELI registry and skips the test if the specified key is not found or is set to an empty string.

@skip_on_sstsimulator_conf_empty_str(section, key, reason)

Parameters

  • section (type: string) Which section to check.
  • key (type: string) Which key to look for.
  • reason (type: string) Message to log if the test is skipped.
  • returns Skip or not.

sstsimulator_conf_does_have_key​

Return whether the requested key exists in the SST ELI registry.

exists = sstsimulator_conf_does_have_key(section, key)

Parameters

  • section (type: string) Which section to check.
  • key (type: string) Which key to look for.
  • returns (type: bool) Whether key exists in section in the file.
  • raises SSTTestCaseException if an error occurs.

sstsimulator_conf_does_have_section​

Return whether the requested section exists in the SST ELI registry.

exists = sstsimulator_conf_does_have_section(section)

Parameters

  • section (type: string) Which section to check for.
  • returns (type: bool) Whether section exists in the file.
  • raises SSTTestCaseException if an error occurs.

sstsimulator_conf_get_all_keys_values_from_section​

Retrieve a list of keys and their values from a section in the SST ELI registry.

key_vals = sstsimulator_conf_get_all_keys_values_from_section(section)

Parameters

  • section (type: string) Which section to return keys and values from.
  • returns (list of tuples of key/val pairs) A list of key/val pairs under section in the file.
  • raises SSTTestCaseException if an error occurs.

sstsimulator_conf_get_section_keys​

Retrieve a list of keys under a section that exist in the SST ELI registry.

keys = sstsimulator_conf_get_section_keys(section)

Parameters

  • section (type: string) Which section to return keys from.
  • returns (list of strings) The list of keys under section in the file.
  • raises

sstsimulator_conf_get_sections​

Retrieve a list of sections that exist in the SST ELI registry.

section_list = sstsimulator_conf_get_sections()

Parameters

  • returns (list of strings) The list of sections in the file.
  • raises SSTTestCaseException if an error occurs.

sstsimulator_conf_get_value​

Retrieve the value of key from a section in the SST ELI registry and return as the requested type.

val = sstsimulator_conf_get_value(section, key, type, default=None)

Parameters

  • section (type: string) The section to search for the key.
  • key (type: string) The key to find.
  • type (type: Type): The type to return the value as. May be str, int, etc.
  • default (type: Any) Default return value if an error occurs.
  • returns (type: Any) The value of key or the default if key is not found.
  • raises SSTTestCaseException if key not found and default is not provided.

sstsimulator_conf_get_value_bool​

DEPRECATED: Use sstsimulator_conf_get_value instead.

Retrieve the value of key from a section in the SST ELI registry and return as a bool.

val = sstsimulator_conf_get_value_bool(section, key, default=None)

Parameters

  • section (type: string) The section to search for the key.
  • key (type: string) The key to find.
  • default (type: bool) Default return value if an error occurs.
  • returns (type: bool) The value of key or the default if key is not found.
  • raises SSTTestCaseException if key not found and default is not provided.

sstsimulator_conf_get_value_float​

DEPRECATED: Use sstsimulator_conf_get_value instead.

Retrieve the value of key from a section in the SST ELI registry and return as a float.

val = sstsimulator_conf_get_value_float(section, key, default=None)

Parameters

  • section (type: string) The section to search for the key.
  • key (type: string) The key to find.
  • default (type: float) Default return value if an error occurs.
  • returns (type: float) The value of key or the default if key is not found.
  • raises SSTTestCaseException if key not found and default is not provided.

sstsimulator_conf_get_value_int​

DEPRECATED: Use sstsimulator_conf_get_value instead.

Retrieve the value of key from a section in the SST ELI registry and return as an int.

val = sstsimulator_conf_get_value_int(section, key, default=None)

Parameters

  • section (type: string): The section to search for the key.
  • key (type: string) The key to find.
  • default (type: int) : Default return value if an error occurs.
  • returns (type: int) The value of key or the default if key is not found.
  • raises SSTTestCaseException if key not found and default is not provided.

sstsimulator_conf_get_value_str​

DEPRECATED: Use sstsimulator_conf_get_value instead.

Retrieve the value of key from a section in the SST ELI registry and return as a string.

val = sstsimulator_conf_get_value_str(section, key, default=None)

Parameters

  • section (type: string) The section to search for the key.
  • key (type: string) The key to find.
  • default (type: string) Default return value if an error occurs.
  • returns (type: string) The value of key or the default if key is not found.
  • raises SSTTestCaseException if key not found and default is not provided.

testing_is_PIN_Compiled​

Returns True if SST-Elements was compiled with a Pin library. This function queries the SST-Elements configuration file.

exists = testing_is_PIN_Compiled()

Parameters

  • returns (type: bool) Whether SST-Elements was compiled with a Pin library

testing_is_PIN_loaded​

Returns the value of the environment variable INTEL_PIN_DIRECTORY. The SST CI environment uses this environment variable. It must be manually set in other environments.

exists = testing_is_PIN_loaded()

Parameters

  • returns (type: bool) Whether the environment variable INTEL_PIN_DIRECTORY is set.

Comparing output files​

The functions in this section can be used to filter and diff output and reference files to determine if a test passed. Many of the functions accept a filter which expects a subclass of SST's LineFilter class.

LineFilter​

Several of the following SST test diff functions accept filters that are applied to files prior to diff. Filters must subclass SST's LineFilter class which looks like this.

class LineFilter:
    def filter(self, line):
        pass
    def reset(self):
        pass

The filter function takes a line to filter and returns the filtered (or unfiltered) line or None if the line should be completely filtered out. The following LineFilter types are provided by the SST framework.

  • StartsWithFilter(prefix) Removes lines that start with a given prefix.
  • IgnoreAllAfterFilter(prefix, keep_line=False) Removes a line that starts with the specified prefix and removes all lines after it.
  • IgnoreWhiteSpaceFilter() Replaces streams of whitespace (space or tabs) with a single space. New lines are not filtered.
  • RemoveRegexFromLineFilter(expr) Filters out portion of the line that matches the specified regular expression.

testing_compare_diff(test_name, outfile, reffile, ignore_ws=False)​

Compare two files for a diff. Optionally ignore whitespace during the diff.

result = testing_compare_diff(test_name, outfile, reffile, ignore_ws=False)

Parameters

  • test_name (type: string) Name for the generated diff file. A ".diff" extension will be appended.
  • outfile (type: string) Test output file (full path).
  • reffile (type: string) Reference file (full path).
  • ignore_ws (type: bool) Set to True to ignore whitespace differences between the files.
  • returns (type: bool) True if the reffile and outfile match. Additionally, the result of the diff will be written to tmp_data/<test_name>.diff.

testing_compare_filtered_diff​

Filter and then (optionally) sort outfile and reffile and perform a diff. This function generates a diff file in the test framework's /tmp_data output directory.

result = testing_compare_filtered_diff(test_name, outfile, reffile, sort=False, filters=[])

Parameters

  • test_name (type: string) Name for the generated diff file. A ".diff" extension will be appended.
  • outfile (type: string) Test output file.
  • reffile (type: string) Reference file.
  • sort (type: bool) If True, lines from outfile and reffile will be sorted before diffing.
  • filters (type: list[LineFilter]) List of filters to apply to the lines of the output and reference files. Filters will be applied in order, but will break early if any filter returns None. Filters must subclass the LineFilter class.
  • returns (type: bool) True if outfile matches reffile. Additionally, the result of the diff will be written to tmp_data/<test_name>.diff.

testing_compare_filtered_subset​

Filter and then determine if the set of lines in outfile is a subset of the set of lines in reffile.

result = testing_compare_filtered_subset(outfile, reffile, filters=[])

Parameters

  • outfile (type: string) Test output file.
  • reffile (type: string) Reference file.
  • filters (type: list[LineFilter]) List of filters to apply to the lines of the output and reference files. Filters will be applied in order, but will break early if any filter returns None. Filters must subclass the LineFilter class.
  • returns (type: bool) True if the set of lines in the filtered outfile is a subset of the lines in the filtered reffile.

testing_compare_sorted_diff​

Sort each file and then compare the sorted files for a diff. This function does not modify the files.

result = testing_compare_sorted_diff(test_name, outfile, reffile)

Parameters

  • test_name (type: string) Name for the generated diff file. A ".diff" extension will be appended.
  • outfile (type: string) Test output file (full path).
  • reffile (type: string) Reference file (full path).
  • returns (type: bool) True if the reffile and outfile match. Additionally, the result of the diff will be written to tmp_data/<test_name>.diff.

testing_get_diff_data​

Return the diff data file that was generated during a diff functions. This should be used after a call to testing_compare_sorted_diff(), testing_compare_diff() or testing_compare_filtered_diff() to return the diff data.

diff_data = testing_get_diff_data(test_name)

Parameters

  • test_name The name of the test. This is used to locate the <test_name>_diff_file temporary file that was generated.
  • returns The file contents from <test_name>_diff_file.

testing_parse_stat​

Return a parsed SST statistic from the statOutputConsole Accumulator output format, or 'None' if the line does not match the format. The returned list contains the fields from the statistic: [component, sum, sumSq, count, min, max].

stat_list = testing_parse_stat(line)

Parameters

  • line (type: string) String to parse into a statistic.
  • returns (type: list) A list of [component, sum, sumSq, count, min, max] or 'None' if not a statistic.

testing_remove_component_warning_from_files​

Remove warnings about threads and/or ranks not being assigned a component. These are warnings that are generated when SST is run with more threads and/or ranks than components. The file will be modified to remove these warnings.

testing_remove_component_warning_from_file(input_filepath)

Parameters

  • input_filepath (type: string) The file to filter.
  • returns None

testing_stat_output_diff​

This function does a diff between an output file (outfile) and a reference file (reffile) which contain SST statistics. The statistics must be Accumulator type statistics in the sst.statOutputConsole format. Statistics can be given a tolerance for whether the diff passes or fails.

result = testing_stat_output_diff(outfile, reffile, ignore_lines=[], tol_stats={}, new_stats=False)

Parameters

  • outfile (type: string) The output file.
  • reffile (type: string) The reference file.
  • ignore_lines (type: list) A list of strings. Any line in either the output or reference file that matches one of the strings will be ignored during the diff.
  • tol_stats (type: map) A dictionary mapping statistic names to tuples in the format (sum, sumSq, count, min, max) containing tolerance limits for each statistic field. Tolerances are treated as a +/- against the reference file's value and an 'X' can be used to indicate a "don't care" or unlimited tolerance limit. Statistics whose values fall within the tolerances will be treated as matching.
  • new_stats (type: bool) Whether to ignore statistics in the outfile that are not present in the reffile. Setting this to True will allow the diff to pass when new statistics are being collected in a model but the reffile has not been updated to include those statistics yet.
  • returns (type: tuple) A tuple (passed, stat_list, other_list). The passed value is True if the outfile matched the reffile and False otherwise. If any statistics diffed, they are included in stat_list. If any non-statistic lines diffed, they will be included in other_list. In both lists, lines prefixed with '<' are from the reffile and lines prefixed with '>' are from the outfile.

Example

lines_to_ignore = ["WARNING: No components are assigned to"]

tolerances = {
    # Outstanding requests statistic can diff by up to 20 in the 'count' field.
    "outstanding_requests" : [0, 0, 20, 0, 0],
    # Total cycles statistic can diff by up to '20' in each field. Ignore any diff in the 'sumSq' field.
    "total_cycles" : [20, 'X', 20, 20, 20] }

test_passed, stat_diffs, other_diffs = testing_stat_output_diff(outfile, reffile, lines_to_ignore, tolerances, True)

MPI file processing​

MPI often produces per-rank output files and it is convenient to concatenate these into a single file. The test frameworks has two functions for doing this. testing_merge_mpi_files works well for the output (stdout and stderr) files produced during tests. combine_per_rank_files works well for combining files with headers such as CSV statistics output.

combine_per_rank_files​

Combines per rank files into a single file. This function works for filenames with a base name "base" and extension "ext" that are formatted as "base_X.ext" where 'X' is a per-rank identifier. Filename should be provided as "base.ext". The files will be concatenated in order of 'X' and written to the base filename.

combine_per_rank_files(filename, header_lines_to_remove=0, remove_header_from_first_file=False)

Parameters

  • filename (type: string) base name of file in "base.ext" format.
  • header_lines_to_remove (type: int) number of header lines to remove from files.
  • remove_header_from_first_file (type: bool) controls whether header lines are removed from first file or not
  • returns None

testing_merge_mpi_files​

Merges a group of common MPI output files into a single output file. This works for the stdout/stderr files produced by OpenMPI 4.x and 5.x ONLY.

testing_merge_mpi_files(filepath_widlcard, mpiout_filename, outputfilepath, errorfilepath=None)

Parameters

  • filepath_wildcard (type: string) The wildcard Path to the files to be merged (OpenMPI 5.x).
  • mpiout_filename (type: string) The name of the MPI output directory (OpenMPI 4.x).
  • outputfilepath (type: string) The output file path to write the merged stdout to.
  • errorfilepath (type: string) The output file path to write the merged stderr to. If none, stderr redirects to stdout.
  • returns None

Test frameworks output: logging and debug​

The test framework creates a log as it runs. Verbosity is controlled by the framework's --quiet, --normal, --verbose (default), and --debug flags. In addition, the framework has an orthogonal "log failures" mode which supports generating more output when a test fails. The following functions allow tests to add additional output to the log depending on the framework's verbosity mode.

log​

Write a message to the log in normal, verbose, and debug modes.

log(msg)

Parameters

  • msg The message to write.

log_debug​

Log a debug message. Log will only happen in debug verbosity mode. Message will be prepended with "DEBUG: ".

log_debug(msg)

Parameters

  • msg The message to write.

log_error​

Log an error message. Log is generated regardless of verbosity. Message will be prepended with "ERROR: ".

log_error(msg)

Parameters

  • msg The message to write.

log_failure​

Log a message when a test fails. This will only be generated if the test framework was run with the --logfailmode command line argument.

log_failure(msg)

Parameters

  • msg The message to write.

log_fatal​

Log a fatal message and immediately exit the test framework. Log is generated regardless of verbosity. Message will be prepended with "FATAL: ".

log_fatal(msg)

Parameters

  • msg The message to write.

log_forced​

Log a message regardless of verbosity mode.

log_forced(msg)

Parameters

  • msg The message to write.

log_info​

Log an info message. Log will be generated in normal, verbose, and debug mode. Message will be prepended with "INFO: ".

log_info(msg, forced=True)

Parameters

  • msg The message to write.
  • forced If True, always force the logging regardless of verbosity.

log_testing_note​

Log a note that will be printed at the end of the test run in the results section. Message will be prepended with "NOTE: ". In debug mode, the message will also be logged to the console immediately.

log_testing_note(msg)

Parameters

  • msg The message to write.

log_warning​

Log a warning message. Log is generated regardless of verbosity. Message will be prepended with "WARNING: ".

log_warning(msg)

Parameters

  • msg The message to write.

testing_check_is_in_debug_mode​

Determine if the test framework is running in debug mode. This corresponds to the --debug argument to sst-test-elements and sst-test-core.

result = testing_check_is_in_debug_mode()

testing_check_is_in_log_failures_mode​

Determine if the test framework is running in "log failure" mode. This corresponds to the --debug argument to sst-test-elements and sst-test-core. In this mode, if a test writes the log using the log_failure function and the test fails, that output will be written to the log. Log failure mode is used to selectively increase error verbosity.

result = testing_check_is_in_log_failures_mode()

OS command equivalents​

These functions execute various basic OS commands either by invoking the command or by mirroring it in Python. Shell commands are run as a subprocess in a separate thread and are monitored with a timeout function. Functions that accept kwargs pass them to OSCommand().run() when running the command. A typical use of this is to pass timeout_sec=<time> if needed to modify the timeout from its default 60s.

os_awk_print​

Perform an awk/print equivalent command which returns specific fields of an input string as a string. The fields_index_list specifies which indices (words) from the input to return.

result = os_awk_print(in_str, fields_index_list)

Parameters

  • in_str (type: string) Input string to parse.
  • fields_index_list (type: list[int]) A list of ints describing which fields and their order to extract
  • returns (type: string) Space-separated list of extracted fields

os_cat​

Performs a $ cat shell command and returns the output.

result = os_cat(filepath, echo_out=True, **kwargs)

Parameters

  • filepath (type: string) Path to file to cat
  • echo_out (type: bool) Whether to also echo the output to console.
  • kwargs (type: Any) Arguments to pass through to underlying OSCommand().run() such as timeout_sec.
  • returns (type: string) The output (stdout) from running the command.

os_extract_tar​

Extracts a tar file.

result = os_extract_tar(tarfilepath, targetdir=".")

Parameters

  • tarfilepath (type: string) The filepath to the tar file.
  • targetdir (type: string) Where to extract the tar file to.
  • returns (type: bool) True if tar extraction succeeded.

os_ls​

Performs an ls -lia and returns the output.

result = os_ls(directory=".", echo_out=True, **kwargs)

Parameters

  • directory (type: string) Directory to run in. Defaults to current directory.
  • echo_out (type: bool) Whether to also echo the output to console.
  • kwargs (type: Any) Arguments to pass through to underlying OSCommand().run() such as timeout_sec.
  • returns (type: string) The output (stdout) from running the command.

os_pwd​

Performs a $ pwd shell command and returns the output.

result = os_pwd(echo_out=True, **kwargs) Whether to also echo the output to console.

Parameters

  • echo_out (type: bool) Whether to also echo the output to console.
  • kwargs (type: Any) Arguments to pass through to underlying OSCommand().run() such as timeout_sec.
  • returns (type: string) The output (stdout) from running the command.

os_simple_command​

Run a simple OS command (no pipes or redirects). The command is run as a subprocess in a separate thread. By default the subprocess terminates after 60s, this can be changed by passing timeout_sec=<time> through kwargs.

result = os_simple_command(os_cmd, run_dir=None, **kwargs)

Parameters

  • os_cmd (type: string) Command to run.
  • run_dir (type: string) Directory to run command in. If None (default), run in current working directory.
  • kwargs (type: Any) Additional arguments to pass to the underlying OSCommand().run() function, such as timeout_sec.
  • returns (type: tuple(int, string)) A tuple of (return_code, stdout) from running the command.

Creates a directory symlink from srcdir/ to destdir/.

os_symlink_dir(srcdir, destdir)

Parameters

  • srcdir (type: string) Source file path.
  • destdir (type: string) Destination file path.
  • returns None

Creates a file symlink from srcdir/filename to destdir/filename.

os_symlink_file(srcdir, destdir, filename)

Parameters

  • srcdir (type: string) Source file path.
  • destdir (type: string) Destination file path.
  • filename (type: string) File to symlink.
  • returns None

os_test_file​

Performs a $ test shell command and returns the result as True (passed) or False (failed).

result = os_test_file(file_path, expression="-e", **kwargs)

Parameters

  • file_path (type: string) Path to the file to be tested.
  • expression (type: string) Expression to evaluate.
  • kwargs (type: Any) Additional arguments to pass to the underlying OSCommand().run() function, such as timeout_sec.
  • returns (type: bool) Whether the test passed (True) or not (False).

os_wc​

Perform a word count ($ wc) on a file. Returns a space-separated list of output fields from running $wc where the fields to return are specified in field_index_list.

result = os_wc(in_file, fields_index_list=[], **kwargs)

Parameters

  • in_file (type: string) File to parse.
  • fields_index_list (type: List[int]) Output from $ wc will be interpreted as a space-separated list. This is the list of indices to return.
  • kwargs (type: Any) Additional arguments to pass to the underlying OSCommand().run() function, such as timeout_sec.
  • returns (type: string) A string containing the spaced-separated items from the result that were indicated by the fields_index_list argument.

Example

result0 = os_wc(in_file, [0])    # Return the line count of the file as a string "line_count"
result1 = os_wc(in_file, [0, 1]) # Return the line and word count of the file as a string "line_count word_count"
result2 = os_wc(in_file, [1, 2]) # Return the word and character count of the file as a string "word_count char_count"

os_wget​

Performs a $ wget command to download a file from a URL. This function will retry a wget until it succeeds or it has tried num_tries times.

result = os_wget(fileurl, targetdir, num_tries=3, secsbetweentries=10, wgetparams="")

Parameters

  • fileurl (type: string) URL to the file to be downloaded.
  • targetdir (type: string) Where to download the file to.
  • num_tries (type: int) Max number of attempts to download the file.
  • secsbetweentries (type: int) How many seconds to wait between each download attempt.
  • wgetparams (type: string) Parameters to pass to wget.
  • returns (type: bool) Whether the file was downloaded (True) or not (False).