4.6.4. b2test_utils - Helper functions useful for test scripts

This module contains functions which are commonly needed for tests like changing log levels or switching to an empty working directory

b2test_utils.check_error_free(tool, toolname, package, filter=<function <lambda>>, toolopts=None)

Calls the tool with argument package and check that the output is error-free. Optionally filter the output in case of error messages that can be ignored.

In case there is some output left, then prints the error message and exits (failing the test).

The test is only executed for a full local checkout: If the BELLE2_RELEASE_DIR environment variable is set or if BELLE2_LOCAL_DIR is unset the test is skipped: The program exits with an appropriate message.

Warning

If the test is skipped or the test contains errors this function does not return but will directly end the program.

Parameters

• tool (str) – executable to call

• toolname (str) – human readable name of the tool

• package (str) – package to run over. Also the first argument to the tool

• filter – function which gets called for each line of output and if it returns True the line will be ignored.

• toolopts (list(str)) – extra options to pass to the tool.

b2test_utils.clean_working_directory()

Context manager to create a temporary directory and directly us it as current working directory. The directory will automatically be deleted after the with context is left.

>>> with clean_working_directory() as dirname:
>>>     # now we are in an empty directory, name is stored in dirname
>>>     assert(os.listdir() == [])
>>> # now we are back where we were before

b2test_utils.configure_logging_for_tests(user_replacements=None)

Change the log system to behave a bit more appropriately for testing scenarios:

1. Simplify log message to be just [LEVEL] message

2. Disable error summary, just additional noise

3. Intercept all log messages and replace

   • the current working directory in log messaged with ${cwd}

   • the current default globaltags with ${default_globaltag}

   • the contents of the following environment variables with their name (or the listed replacement string):

     • BELLE2_TOOLS

     • BELLE2_RELEASE_DIR with BELLE2_SOFTWARE_DIR

     • BELLE2_LOCAL_DIR with BELLE2_SOFTWARE_DIR

     • BELLE2_EXTERNALS_DIR

     • BELLE2_VALIDATION_DATA_DIR

     • BELLE2_EXAMPLES_DATA_DIR

     • BELLE2_BACKGROUND_DIR

Parameters

user_replacements (dict(str, str)) – Additional strings and their replacements to replace in the output

Warning

This function should be called after switching directory to replace the correct directory name

New in version release-04-00-00.

b2test_utils.get_object_with_name(object_name, root=None)

(Possibly) recursively get the object with the given name from the Belle2 namespace.

If the object name includes a “.”, the first part will be turned into an object (probably a module) and the function is continued with this object as the root and the rest of the name.

If not, the object is extracted via a getattr call.

b2test_utils.get_streamer_checksums(objects)

Extract the version and streamer checksum of the C++ objects in the given list by writing them all to a TMemFile and getting back the streamer info list automatically created by ROOT afterwards. Please note, that this list also includes the streamer infos of all base objects of the objects you gave.

Returns a dictionary object name -> (version, checksum).

b2test_utils.is_ci() → bool

Returns true if we are running a test on our CI system (currently bamboo). The ‘BELLE2_IS_CI’ environment variable is set on CI only when the unit tests are run.

b2test_utils.local_software_directory()

Context manager to make sure we are executed in the top software directory by switching to $BELLE2_LOCAL_DIR.

>>> with local_software_directory():
>>>    assert(os.listdir().contains("analysis"))

b2test_utils.print_belle2_environment()

Prints all the BELLE2 environment variables on the screen.

b2test_utils.require_file(filename, data_type='', py_case=None)

Check for the existence of a test input file before attempting to open it. Skips the test if not found.

Wraps basf2.find_file for use in test scripts run as :ref`b2test-scripts <b2test-scripts>`

Parameters

• filename (str) – relative filename to look for, either in a central place or in the current working directory

• data_type (str) – case insensitive data type to find. Either empty string or one of "examples" or "validation".

• py_case (unittest.TestCase) – if this is to be skipped within python’s native unittest then pass the TestCase instance

Returns

Full path to the test input file

b2test_utils.run_in_subprocess(*args, target, **kwargs)

Run the given target function in a child process using multiprocessing.Process

This avoids side effects: anything done in the target function will not affect the current process. This is mostly useful for test scripts as target can emit a FATAL error without killing script execution.

It will return the exitcode of the child process which should be 0 in case of no error

b2test_utils.safe_process(*args, **kwargs)

Run basf2.process with the given path in a child process using multiprocessing.Process

This avoids side effects (safe_process can be safely called multiple times) and doesn’t kill this script even if a segmentation violation or a FATAL error occurs during processing.

It will return the exitcode of the child process which should be 0 in case of no error

b2test_utils.set_loglevel(loglevel)

temporarily set the log level to the specified LogLevel. This returns a context manager so it should be used in a with statement:

>>> with set_log_level(LogLevel.ERROR):
>>>     # during this block the log level is set to ERROR

b2test_utils.show_only_errors()

temporarily set the log level to ERROR. This returns a context manager so it should be used in a with statement

>>> with show_only_errors():
>>>     B2INFO("this will not be shown")
>>> B2INFO("but this might")

b2test_utils.skip_test(reason, py_case=None)

Skip a test script with a given reason. This function will end the script and not return.

This is intended for scripts to be run in b2test-scripts and will flag the script as skipped with the given reason when tests are executed.

Useful if the test depends on some external condition like a web service and missing this dependency should not fail the test run.

Parameters

• reason (str) – the reason to skip the test.

• py_case (unittest.TestCase) – if this is to be skipped within python’s native unittest then pass the TestCase instance

b2test_utils.skip_test_if_light(py_case=None)

Skips the test if we are running in a light build (maybe this test tests some generation example or whatever)

Parameters

py_case (unittest.TestCase) – if this is to be skipped within python’s native unittest then pass the TestCase instance

b2test_utils.working_directory(path)

temporarily change the working directory to path

>>> with working_directory("testing"):
>>>     # now in subdirectory "./testing/"
>>> # back to parent directory

This function will not create the directory for you. If changing into the directory fails a FileNotFoundError will be raised.