absl.testing.absltest module

Base functionality for Abseil Python tests.

This module contains base classes and high-level functions for Abseil-style tests.

class absl.testing.absltest.TempFileCleanup(value)

Bases: Enum

An enumeration.

ALWAYS = 'always'

OFF = 'never'

SUCCESS = 'success'

class absl.testing.absltest.TestCase(*args, **kwargs)

Bases: TestCase

Extension of unittest.TestCase providing more power.

assertBetween(value, minv, maxv, msg=None)

Asserts that value is between minv and maxv (inclusive).

assertCommandFails(command, regexes, env=None, close_fds=True, msg=None)

Asserts a shell command fails and the error matches a regex in a list.

Parameters:

• command – List or string representing the command to run.

• regexes – the list of regular expression strings.

• env – Dictionary of environment variable settings. If None, no environment variables will be set for the child process. This is to make tests more hermetic. NOTE: this behavior is different than the standard subprocess module.

• close_fds – Whether or not to close all open fd’s in the child after forking.

• msg – Optional message to report on failure.

assertCommandSucceeds(command, regexes=(b'',), env=None, close_fds=True, msg=None)

Asserts that a shell command succeeds (i.e. exits with code 0).

Parameters:

• command – List or string representing the command to run.

• regexes – List of regular expression byte strings that match success.

• env – Dictionary of environment variable settings. If None, no environment variables will be set for the child process. This is to make tests more hermetic. NOTE: this behavior is different than the standard subprocess module.

• close_fds – Whether or not to close all open fd’s in the child after forking.

• msg – Optional message to report on failure.

assertContainsExactSubsequence(container, subsequence, msg=None)

Asserts that “container” contains “subsequence” as an exact subsequence.

Asserts that “container” contains all the elements of “subsequence”, in order, and without other elements interspersed. For example, [1, 2, 3] is an exact subsequence of [0, 0, 1, 2, 3, 0] but not of [0, 0, 1, 2, 0, 3, 0].

Parameters:

• container – the list we’re testing for subsequence inclusion.

• subsequence – the list we hope will be an exact subsequence of container.

• msg – Optional message to report on failure.

assertContainsInOrder(strings, target, msg=None)

Asserts that the strings provided are found in the target in order.

This may be useful for checking HTML output.

Parameters:

• strings – A list of strings, such as [ ‘fox’, ‘dog’ ]

• target – A target string in which to look for the strings, such as ‘The quick brown fox jumped over the lazy dog’.

• msg – Optional message to report on failure.

assertContainsSubsequence(container, subsequence, msg=None)

Asserts that “container” contains “subsequence” as a subsequence.

Asserts that “container” contains all the elements of “subsequence”, in order, but possibly with other elements interspersed. For example, [1, 2, 3] is a subsequence of [0, 0, 1, 2, 0, 3, 0] but not of [0, 0, 1, 3, 0, 2, 0].

Parameters:

• container – the list we’re testing for subsequence inclusion.

• subsequence – the list we hope will be a subsequence of container.

• msg – Optional message to report on failure.

assertContainsSubset(expected_subset, actual_set, msg=None)

Checks whether actual iterable is a superset of expected iterable.

assertDictEqual(a, b, msg=None)

Raises AssertionError if a and b are not equal dictionaries.

Parameters:

• a – A dict, the expected value.

• b – A dict, the actual value.

• msg – An optional str, the associated message.

Raises:

AssertionError – if the dictionaries are not equal.

assertEmpty(container, msg=None)

Asserts that an object has zero length.

Parameters:

• container – Anything that implements the collections.abc.Sized interface.

• msg – Optional message to report on failure.

assertEndsWith(actual, expected_end, msg=None)

Asserts that actual.endswith(expected_end) is True.

Parameters:

• actual – str

• expected_end – str

• msg – Optional message to report on failure.

assertItemsEqual(expected_seq, actual_seq, msg=None)

Deprecated, please use assertCountEqual instead.

This is equivalent to assertCountEqual.

Parameters:

• expected_seq – A sequence containing elements we are expecting.

• actual_seq – The sequence that we are testing.

• msg – The message to be printed if the test fails.

assertJsonEqual(first, second, msg=None)

Asserts that the JSON objects defined in two strings are equal.

A summary of the differences will be included in the failure message using assertSameStructure.

Parameters:

• first – A string containing JSON to decode and compare to second.

• second – A string containing JSON to decode and compare to first.

• msg – Additional text to include in the failure message.

assertLen(container, expected_len, msg=None)

Asserts that an object has the expected length.

Parameters:

• container – Anything that implements the collections.abc.Sized interface.

• expected_len – The expected length of the container.

• msg – Optional message to report on failure.

assertMultiLineEqual(first, second, msg=None, **kwargs)

Asserts that two multi-line strings are equal.

assertNoCommonElements(expected_seq, actual_seq, msg=None)

Checks whether actual iterable and expected iterable are disjoint.

assertNotEmpty(container, msg=None)

Asserts that an object has non-zero length.

Parameters:

• container – Anything that implements the collections.abc.Sized interface.

• msg – Optional message to report on failure.

assertNotEndsWith(actual, unexpected_end, msg=None)

Asserts that actual.endswith(unexpected_end) is False.

Parameters:

• actual – str

• unexpected_end – str

• msg – Optional message to report on failure.

assertNotStartsWith(actual, unexpected_start, msg=None)

Asserts that actual.startswith(unexpected_start) is False.

Parameters:

• actual – str

• unexpected_start – str

• msg – Optional message to report on failure.

assertRaisesWithLiteralMatch(expected_exception, expected_exception_message) → _AssertRaisesContext

assertRaisesWithLiteralMatch(expected_exception, expected_exception_message, callable_obj: Callable[[...], Any], *args, **kwargs) → None

Asserts that the message in a raised exception equals the given string.

Unlike assertRaisesRegex, this method takes a literal string, not a regular expression.

with self.assertRaisesWithLiteralMatch(ExType, ‘message’):

DoSomething()

Parameters:

• expected_exception – Exception class expected to be raised.

• expected_exception_message – String message expected in the raised exception. For a raise exception e, expected_exception_message must equal str(e).

• callable_obj – Function to be called, or None to return a context.

• *args – Extra args.

• **kwargs – Extra kwargs.

Returns:

A context manager if callable_obj is None. Otherwise, None.

Raises:

self.failureException if callable_obj does not raise a matching exception. –

assertRaisesWithPredicateMatch(expected_exception, predicate) → _AssertRaisesContext

assertRaisesWithPredicateMatch(expected_exception, predicate, callable_obj: Callable[[...], Any], *args, **kwargs) → None

Asserts that exception is thrown and predicate(exception) is true.

Parameters:

• expected_exception – Exception class expected to be raised.

• predicate – Function of one argument that inspects the passed-in exception and returns True (success) or False (please fail the test).

• callable_obj – Function to be called.

• *args – Extra args.

• **kwargs – Extra keyword args.

Returns:

A context manager if callable_obj is None. Otherwise, None.

Raises:

self.failureException if callable_obj does not raise a matching exception. –

assertRegexMatch(actual_str, regexes, message=None)

Asserts that at least one regex in regexes matches str.

If possible you should use assertRegex, which is a simpler version of this method. assertRegex takes a single regular expression (a string or re compiled object) instead of a list.

Notes:

1. This function uses substring matching, i.e. the matching succeeds if any substring of the error message matches any regex in the list. This is more convenient for the user than full-string matching.

2. If regexes is the empty list, the matching will always fail.

3. Use regexes=[‘’] for a regex that will always pass.

4. ‘.’ matches any single character except the newline. To match any character, use ‘(.|n)’.

5. ‘^’ matches the beginning of each line, not just the beginning of the string. Similarly, ‘$’ matches the end of each line.

6. An exception will be thrown if regexes contains an invalid regex.

Parameters:

• actual_str – The string we try to match with the items in regexes.

• regexes – The regular expressions we want to match against str. See “Notes” above for detailed notes on how this is interpreted.

• message – The message to be printed if the test fails.

assertSameElements(expected_seq, actual_seq, msg=None)

Asserts that two sequences have the same elements (in any order).

This method, unlike assertCountEqual, doesn’t care about any duplicates in the expected and actual sequences:

# Doesn't raise an AssertionError
assertSameElements([1, 1, 1, 0, 0, 0], [0, 1])

If possible, you should use assertCountEqual instead of assertSameElements.

Parameters:

• expected_seq – A sequence containing elements we are expecting.

• actual_seq – The sequence that we are testing.

• msg – The message to be printed if the test fails.

assertSameStructure(a, b, aname='a', bname='b', msg=None)

Asserts that two values contain the same structural content.

The two arguments should be data trees consisting of trees of dicts and lists. They will be deeply compared by walking into the contents of dicts and lists; other items will be compared using the == operator. If the two structures differ in content, the failure message will indicate the location within the structures where the first difference is found. This may be helpful when comparing large structures.

Mixed Sequence and Set types are supported. Mixed Mapping types are supported, but the order of the keys will not be considered in the comparison.

Parameters:

• a – The first structure to compare.

• b – The second structure to compare.

• aname – Variable name to use for the first structure in assertion messages.

• bname – Variable name to use for the second structure.

• msg – Additional text to include in the failure message.

assertSequenceAlmostEqual(expected_seq, actual_seq, places=None, msg=None, delta=None)

An approximate equality assertion for ordered sequences.

Fail if the two sequences are unequal as determined by their value differences rounded to the given number of decimal places (default 7) and comparing to zero, or by comparing that the difference between each value in the two sequences is more than the given delta.

Note that decimal places (from zero) are usually not the same as significant digits (measured from the most significant digit).

If the two sequences compare equal then they will automatically compare almost equal.

Parameters:

• expected_seq – A sequence containing elements we are expecting.

• actual_seq – The sequence that we are testing.

• places – The number of decimal places to compare.

• msg – The message to be printed if the test fails.

• delta – The OK difference between compared values.

assertSequenceStartsWith(prefix, whole, msg=None)

An equality assertion for the beginning of ordered sequences.

If prefix is an empty sequence, it will raise an error unless whole is also an empty sequence.

If prefix is not a sequence, it will raise an error if the first element of whole does not match.

Parameters:

• prefix – A sequence expected at the beginning of the whole parameter.

• whole – The sequence in which to look for prefix.

• msg – Optional message to report on failure.

assertStartsWith(actual, expected_start, msg=None)

Asserts that actual.startswith(expected_start) is True.

Parameters:

• actual – str

• expected_start – str

• msg – Optional message to report on failure.

assertTotallyOrdered(*groups, **kwargs)

Asserts that total ordering has been implemented correctly.

For example, say you have a class A that compares only on its attribute x. Comparators other than __lt__ are omitted for brevity:

class A(object):
  def __init__(self, x, y):
    self.x = x
    self.y = y

  def __hash__(self):
    return hash(self.x)

  def __lt__(self, other):
    try:
      return self.x < other.x
    except AttributeError:
      return NotImplemented

assertTotallyOrdered will check that instances can be ordered correctly. For example:

self.assertTotallyOrdered(
    [None],  # None should come before everything else.
    [1],  # Integers sort earlier.
    [A(1, 'a')],
    [A(2, 'b')],  # 2 is after 1.
    [A(3, 'c'), A(3, 'd')],  # The second argument is irrelevant.
    [A(4, 'z')],
    ['foo'])  # Strings sort last.

Parameters:

• *groups – A list of groups of elements. Each group of elements is a list of objects that are equal. The elements in each group must be less than the elements in the group after it. For example, these groups are totally ordered: [None], [1], [2, 2], [3].

• **kwargs – optional msg keyword argument can be passed.

assertUrlEqual(a, b, msg=None)

Asserts that urls are equal, ignoring ordering of query params.

create_tempdir(name: str | None = None, cleanup: TempFileCleanup | None = None) → _TempDir

Create a temporary directory specific to the test.

NOTE: The directory and its contents will be recursively cleared before creation. This ensures that there is no pre-existing state.

This creates a named directory on disk that is isolated to this test, and will be properly cleaned up by the test. This avoids several pitfalls of creating temporary directories for test purposes, as well as makes it easier to setup directories and verify their contents. For example:

def test_foo(self):
  out_dir = self.create_tempdir()
  out_log = out_dir.create_file('output.log')
  expected_outputs = [
      os.path.join(out_dir, 'data-0.txt'),
      os.path.join(out_dir, 'data-1.txt'),
  ]
  code_under_test(out_dir)
  self.assertTrue(os.path.exists(expected_paths[0]))
  self.assertTrue(os.path.exists(expected_paths[1]))
  self.assertEqual('foo', out_log.read_text())

See also: create_tempfile() for creating temporary files.

Parameters:

• name – Optional name of the directory. If not given, a unique name will be generated and used.

• cleanup – Optional cleanup policy on when/if to remove the directory (and all its contents) at the end of the test. If None, then uses tempfile_cleanup.

Returns:

A _TempDir representing the created directory; see _TempDir class docs for usage.

create_tempfile(file_path: str | None = None, content: AnyStr | None = None, mode: str = 'w', encoding: str = 'utf8', errors: str = 'strict', cleanup: TempFileCleanup | None = None) → _TempFile

Create a temporary file specific to the test.

This creates a named file on disk that is isolated to this test, and will be properly cleaned up by the test. This avoids several pitfalls of creating temporary files for test purposes, as well as makes it easier to setup files, their data, read them back, and inspect them when a test fails. For example:

def test_foo(self):
  output = self.create_tempfile()
  code_under_test(output)
  self.assertGreater(os.path.getsize(output), 0)
  self.assertEqual('foo', output.read_text())

NOTE: This will zero-out the file. This ensures there is no pre-existing state. NOTE: If the file already exists, it will be made writable and overwritten.

See also: create_tempdir() for creating temporary directories, and _TempDir.create_file for creating files within a temporary directory.

Parameters:

• file_path – Optional file path for the temp file. If not given, a unique file name will be generated and used. Slashes are allowed in the name; any missing intermediate directories will be created. NOTE: This path is the path that will be cleaned up, including any directories in the path, e.g., 'foo/bar/baz.txt' will rm -r foo.

• content – Optional string or bytes to initially write to the file. If not specified, then an empty file is created.

• mode – Mode string to use when writing content. Only used if content is non-empty.

• encoding – Encoding to use when writing string content. Only used if content is text.

• errors – How to handle text to bytes encoding errors. Only used if content is text.

• cleanup – Optional cleanup policy on when/if to remove the directory (and all its contents) at the end of the test. If None, then uses tempfile_cleanup.

Returns:

A _TempFile representing the created file; see _TempFile class docs for usage.

enter_context(manager: ContextManager[_T]) → _T

fail(msg=None, prefix=None)

Fail immediately with the given message, optionally prefixed.

longMessage = True

maxDiff = 1600

setUp()

Hook method for setting up the test fixture before exercising it.

classmethod setUpClass()

Hook method for setting up class fixture before running tests in the class.

shortDescription() → str

Formats both the test method name and the first line of its docstring.

If no docstring is given, only returns the method name.

This method overrides unittest.TestCase.shortDescription(), which only returns the first line of the docstring, obscuring the name of the test upon failure.

Returns:

A short description of a test method.

Return type:

desc

tempfile_cleanup: TempFileCleanup = 'always'

class absl.testing.absltest.TestLoader(*args, **kwds)

Bases: TestLoader

A test loader which supports common test features.

Supported features include:

• Banning untested methods with test-like names: methods attached to this testCase with names starting with Test are ignored by the test runner, and often represent mistakenly-omitted test cases. This loader will raise a TypeError when attempting to load a TestCase with such methods.

• Randomization of test case execution order (optional).

getTestCaseNames(testCaseClass)

Validates and returns a (possibly randomized) list of test case names.

absl.testing.absltest.expectedFailureIf(condition, reason)

Expects the test to fail if the run condition is True.

Example usage:

@expectedFailureIf(sys.version.major == 2, "Not yet working in py2")
def test_foo(self):
  ...

Parameters:

• condition – bool, whether to expect failure or not.

• reason – Text, the reason to expect failure.

Returns:

Decorator function

absl.testing.absltest.get_command_stderr(command, env=None, close_fds=True)

Runs the given shell command and returns a tuple.

Parameters:

• command – List or string representing the command to run.

• env – Dictionary of environment variable settings. If None, no environment variables will be set for the child process. This is to make tests more hermetic. NOTE: this behavior is different than the standard subprocess module.

• close_fds – Whether or not to close all open fd’s in the child after forking. On Windows, this is ignored and close_fds is always False.

Returns:

Tuple of (exit status, text printed to stdout and stderr by the command).

absl.testing.absltest.get_command_string(command)

Returns an escaped string that can be used as a shell command.

Parameters:

command – List or string representing the command to run.

Returns:

A string suitable for use as a shell command.

absl.testing.absltest.get_default_test_srcdir() → str

Returns default test source dir.

absl.testing.absltest.get_default_test_tmpdir() → str

Returns default test temp dir.

absl.testing.absltest.get_default_xml_output_filename() → str | None

absl.testing.absltest.main(*args: str, **kwargs: Any) → None

Executes a set of Python unit tests.

Usually this function is called without arguments, so the unittest.TestProgram instance will get created with the default settings, so it will run all test methods of all TestCase classes in the __main__ module.

Parameters:

• *args – Positional arguments passed through to unittest.TestProgram.__init__.

• **kwargs – Keyword arguments passed through to unittest.TestProgram.__init__.

absl.testing.absltest.print_python_version() → None

absl.testing.absltest.run_tests(argv: MutableSequence[str], args: Sequence[Any], kwargs: MutableMapping[str, Any]) → None

Executes a set of Python unit tests.

Most users should call absltest.main() instead of run_tests.

Please note that run_tests should be called from app.run. Calling absltest.main() would ensure that.

Please note that run_tests is allowed to make changes to kwargs.

Parameters:

• argv – sys.argv with the command-line flags removed from the front, i.e. the argv with which app.run() has called __main__.main. It is passed to unittest.TestProgram.__init__(argv=), which does its own flag parsing. It is ignored if kwargs contains an argv entry.

• args – Positional arguments passed through to unittest.TestProgram.__init__.

• kwargs – Keyword arguments passed through to unittest.TestProgram.__init__.

absl.testing.absltest.skipThisClass(reason: Text) → Callable[[_T], _T]

Skip tests in the decorated TestCase, but not any of its subclasses.

This decorator indicates that this class should skip all its tests, but not any of its subclasses. Useful for if you want to share testMethod or setUp implementations between a number of concrete testcase classes.

Example usage, showing how you can share some common test methods between subclasses. In this example, only BaseTest will be marked as skipped, and not RealTest or SecondRealTest:

@absltest.skipThisClass("Shared functionality")
class BaseTest(absltest.TestCase):
  def test_simple_functionality(self):
    self.assertEqual(self.system_under_test.method(), 1)

class RealTest(BaseTest):
  def setUp(self):
    super().setUp()
    self.system_under_test = MakeSystem(argument)

  def test_specific_behavior(self):
    ...

class SecondRealTest(BaseTest):
  def setUp(self):
    super().setUp()
    self.system_under_test = MakeSystem(other_arguments)

  def test_other_behavior(self):
    ...

Parameters:

reason – The reason we have a skip in place. For instance: ‘shared test methods’ or ‘shared assertion methods’.

Returns:

Decorator function that will cause a class to be skipped.