"""
Unit test functions for Python
This module provides function-level unit testing tools, as an alternative to
built-in Python package unittest, which is less user-friendly and requires an
understanding of object-oriented programming.
This module's "assert-style" functions differ from standard assert statements.
They stop execution of Python and report the location of the error.
:author: Walker M. White (wmw2), Lillian Lee (LJL2), Steve Marschner (SRM2)
:version: Feb 24, 2020
"""
import math
# removed "is" functions, as confusing about type of input. --LL, Feb 24, 2021
def allclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
"""
Returns True if two sequences are element-wise equal within a tolerance.
The values a and b are expected to be sequences, though they can be nested
sequences so long as the base elements are numbers (int or float). For
example, ((1,2), (3,4)) is an acceptable value but ((1,2),('a',3)) is not.
In addition, the inputs are expected to have the same 'shape' (same
length overall and for any nested elements).
The tolerance values are positive, and are typically very small numbers.
The relative difference (`rtol` * abs(`b`)) and the absolute difference
`atol` are added together to compare against the absolute difference
between `a` and `b`.
If either sequence contains one or more NaNs, False is returned (unless
equal_nan is True). Infs are treated as equal if they are in the same
place and of the same sign in both sequences.
This is a safe replacement for the numpy version.
Examples::
isclose([1],[1.000001]) is True
isclose([1,2.01],[1.000001,2]) is False
isclose([[1,2],[3,4]],[[1,2],[3,4]]) is True
:param a: Input sequence to compare
:type a: sequence
:param b: Input sequence to compare
:type b: sequence
:param rtol: The relative tolerance parameter (Optional).
:type rtol: ``float``
:param atol: The absolute tolerance parameter (Optional).
:type atol: ``float``
:param equal_nan: Whether to compare NaN's as equal (Optional).
:type equal_nan: ``bool``
"""
if type(a) in [float, int] and type(b) in [float, int]:
return abs(a - b) <= atol + rtol * abs(b)
error = None
messg = None
try:
return _close_descent(a, b, rtol, atol, equal_nan)
except TypeError as e:
error = TypeError
bad = b
if e.args[0] == 1:
bad = a
if type(bad) in [bool, str]:
messg = '%s has the wrong type' % repr(bad)
else:
messg = '%s has invalid contents' % repr(bad)
except ValueError as f:
error = ValueError
messg = '%s and %s do not have the same shape' % (repr(a), repr(b))
if error:
raise error(messg)
raise RuntimeError('An unknown error has occurred')
def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
"""
Returns a boolean or sequence comparing inputs element-wise within a tolerance.
The values a and b can either be numbers (``int`` or ``float``) or a
sequence. If they are numbers, this function returns a boolean.
If they are sequences, they can be nested, but their base elements must be
numbers (int or float). For example, ((1,2), (3,4))is an acceptable value
but ((1,2),('a',3)) is not. In addition, the inputs are expected to have
the same 'shape' (same length overall and for any nested elements). The
value returned will be a sequence of booleans of the same shape as the
inputs.
The tolerance values are positive, typically very small numbers. The
relative difference (`rtol` * abs(`b`)) and the absolute difference `atol`
are added together to compare against the absolute difference between `a`
and `b`.
This is a safe replacement for the numpy version.
Examples::
isclose(1,1.000001) is True
isclose([1,2.01],[1.000001,2]) is [True,False]
isclose([[1,2],[5,4]],[[1,2],[3,4]]) is [[True,True],[False,True]]
:param a: Input to compare
:type a: number or sequence
:param b: Input sequence to compare
:type b: number or sequence
:param rtol: The relative tolerance parameter (Optional).
:type rtol: ``float``
:param atol: The absolute tolerance parameter (Optional).
:type atol: ``float``
:param equal_nan: Whether to compare NaN's as equal (Optional).
:type equal_nan: ``bool``
:return: a boolean or sequence comparing to inputs element-wise
:rtype: ``bool`` or sequence
"""
if type(a) in [float, int] and type(b) in [float, int]:
return abs(a - b) <= atol + rtol * abs(b)
error = None
messg = None
try:
return _close_descent(a, b, rtol, atol, equal_nan, False)
except TypeError as e:
error = TypeError
bad = b
if e.args[0] == 1:
bad = a
if type(bad) in [bool, str]:
messg = '%s has the wrong type' % repr(bad)
else:
messg = '%s has invalid contents' % repr(bad)
except ValueError as f:
error = ValueError
messg = '%s and %s do not have the same shape' % (repr(a), repr(b))
if error:
raise error(messg)
raise RuntimeError('An unknown error has occurred')
def _close_descent(a, b, rtol, atol, equal_nan, flatten=True):
"""
Returns a boolean or sequence comparing inputs element-wise within a tolerance.
This is a recursive function intended to implement `allclose` and
`isclose` Which one it implements depends on the value of `flatten`. If
`flatten` is True, it returns a boolean. Otherwise it returns a value of
the same shape as the inputs.
This method uses coded exceptions to abort if the inputs are invalid.
:param a: Input to compare
:type a: number or sequence
:param b: Input sequence to compare
:type b: number or sequence
:param rtol: The relative tolerance parameter (Optional).
:type rtol: ``float```
:param atol: The absolute tolerance parameter (Optional).
:type atol: ``float```
:param equal_nan: Whether to compare NaN's as equal (Optional).
:type equal_nan: ``bool```
:param flatten: Whether to flatten the final answer (Optional)
:type flatten: ``bool``
:return: a boolean or sequence comparing to inputs element-wise
:rtype: ``bool`` or sequence
"""
if type(a) in [float, int]:
if not type(b) in [float, int]:
try:
test = b[0]
except:
raise ValueError() # Shape mismatch
raise TypeError(2) # Content mismatch
elif math.isinf(a) or math.isinf(b):
return math.isinf(a) and math.isinf(b)
elif not math.isnan(a) and not math.isnan(b):
return abs(a - b) <= atol + rtol * abs(b)
elif equal_nan:
return math.isnan(a) and math.isnan(b)
else:
return False
elif type(b) in [float, int]:
try:
test = a[0]
except:
raise ValueError() # Shape mismatch
raise TypeError(1) # Content mismatch
try:
test = a[0]
except:
raise TypeError(1) # Content mismatch
try:
test = b[0]
except:
raise TypeError(2) # Content mismatch
if len(a) != len(b):
raise ValueError(6)
if flatten:
result = True
for pos in range(len(a)):
result = result and _close_descent(
a[pos], b[pos], rtol, atol, equal_nan, flatten)
else:
result = []
for pos in range(len(a)):
result.append(_close_descent(
a[pos], b[pos], rtol, atol, equal_nan, flatten))
return result
def quit_with_error(msg):
"""Quit Python, after printing error message `msg` [str], location, and
termination message `Quitting with Error`.
Precondition: called within another function (technically, the call stack
must have depth at least 3.)
:param msg: The error message
:type msg: ``str``
"""
import traceback
stack = traceback.extract_stack()
frame = stack[-3]
print(msg)
if (frame[3] is None):
suffix = ''
else:
suffix = ": " + frame[3]
print('Line', repr(frame[1]), 'of', frame[0] + suffix)
print('Quitting with Error')
quit()
def assert_equals(expected, received, message=None):
"""
Quit if `expected` and `received` differ (!=), printing some info.
Does nothing otherwise.
Precondition: `expected` and `received` are not both floats. (For that
use case, use :func:`assert_floats_equal`.)
Example usage:
assert_equals(10, my_function(14))
If `my_function(14)` is "Aye, me", the printout is:
assert_equals: expected 10 but instead got 'Aye, me'
Line <corresponding line number> of <relevant file>
Quitting with Error
:param expected: The value you expect the test to have
:param received: The value the test actually had
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
if (expected != received):
if message is None:
message = 'assert_equals: expected %s but instead got %s' % (
repr(expected), repr(received))
quit_with_error(message)
def assert_not_equals(expected, received, message=None):
"""Quit if `expected` and `received` are the same (==), printing some info.
Does nothing otherwise.
`expected` should be an expected value for a test.
`received` should be (the value of) an expression representing a test.
Precondition: `expected` and `received` are not both floats. (For that
use case, use :func:`assert_floats_not_equal`)
Example usage:
assert_not_equals(10, my_function(14))
If `my_function(14)` is 10, the printout is:
assert_not_equals: expected something different from 10; got 10
Line <relevant line number> of <relevant file>:
Quitting with Error
:param expected: The value you expect the test to have
:param received: The value the test actually had
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
if (expected == received):
if message is None:
message = 'assert_not_equals: expected something different from %s' % repr(
expected)
quit_with_error(message)
def assert_true(received, message=None):
"""
Quits if ``received`` is False, printing an error message.
Does nothing otherwise.
If there is no custom error message, this function will print some minimal
debug information. The following is an example debug message::
assert_true: expected True but <something> evaluates to False
:param received: The value the test actually had
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
if (not received):
if message is None:
message = 'assert_true: expected True but %s evaluates to False' % repr(
received)
quit_with_error(message)
def assert_false(received, message=None):
"""
Quits if ``received`` is True.
If there is no custom error message, this function will print some minimal debug
information. The following is an example debug message::
assert_false: expected False but <something> evaluates to True
:param received: The value the test actually had
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
if (received):
if message is None:
message = 'assert_false: expected False but %s evaluates to True' % repr(
received)
quit_with_error(message)
def assert_floats_equal(expected, received, message=None):
"""
Quits if the floats ``expected`` and ``received`` differ, printing an
error message.
If one of the arguments is not a number, quits with another error message,
for example::
assert_floats_equal: first argument 'alas' is not a number
Does nothing otherwise.
"Differ" here means in the sense of the `allclose` function, which mimics the
implementation in package ``numpy``, which has a built-in (small) level
of tolerance in the relative difference between float numbers.
If there is no custom error message, this function will print some minimal debug
information. The following is an example debug message::
assert_floats_equal: expected 0.1 but instead got 0.2
:param expected: The value you expect the test to have
:type expected: ``float``
:param received: The value the test actually had
:type received: ``float``
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
number = [float, int] # list of number types
if type(expected) not in number:
if message is None:
message = (
'assert_floats_equal: first argument %s is not a number' % repr(expected))
elif type(received) not in number:
if message is None:
message = (
'assert_floats_equal: second argument %s is not a number' % repr(received))
elif (not isclose(expected, received)):
if message is None:
message = 'assert_floats_equal: expected %s but instead got %s' % (
repr(expected), repr(received))
else:
message = None
if not message is None:
quit_with_error(message)
def assert_floats_not_equal(expected, received, message=None):
"""
Quits if floats ``expected`` and ``received`` are the same.
This function takes two numbers and compares them using functionality like
that in the numerical
package ``numpy``, which is a scientific computing package that allows us to test if
numbers are "close enough".
If there is no custom error message, this function will print some minimal debug
information. The following is an example debug message::
assert_floats_not_equal: expected something different from 0.1
**IMPORTANT**:
The arguments expected and received should each numbers (either floats or ints). If
either argument is not a number, the function quits with a different error message.
For example::
assert_floats_not_equal: first argument 'alas' is not a number
:param expected: The value you expect the test to have
:type expected: ``float``
:param received: The value the test actually had
:type received: ``float``
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
number = [float, int] # list of number types
if type(expected) not in number:
if message is None:
message = (
'assert_floats_not_equal: first argument %s is not a number' % repr(expected))
elif type(received) not in number:
if message is None:
message = (
'assert_floats_not_equal: second argument %s is not a number' % repr(received))
elif (isclose(expected, received)):
if message is None:
message = (
'assert_floats_not_equal: expected something different from %s' % repr(expected))
else:
message = None
if not message is None:
quit_with_error(message)
def _check_nested_floats(thelist):
"""
Returns True if thelist is a (nested) list of floats
INTERNAL HELPER
If thelist recursively contains anything other than a list, tuple, int, or float,
this function returns false.
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
result = True
for item in thelist:
if type(item) in [list, tuple]:
result = result and _check_nested_floats(item)
else:
result = result and type(item) in [int, float]
return result
def assert_float_lists_equal(expected, received, message=None):
"""
Quits if the lists (or tuples) of floats ``expected`` and ``received`` differ
This function takes two numbers and compares them using functionality akin
to that of``numpy``, which is a scientific computing package that
allows us to test if numbers are "close enough".
This function is similar to :func:`assert_floats_equal`. The difference is
that it works on lists of floats. These lists can be multidimensional.
To illustrate this, the following is an example debug message::
assert_float_lists__equal: expected [[1,2],[3,4]] but instead got
[[1,2],[3,5]]
If there is a custom error message, that will be used instead.
**IMPORTANT**: The arguments expected and received should each lists of
numbers. Furtheemore, they must have EXACTLY the same dimension. If not this
function quits with a different error message. For example::
assert_float_lists_equal: first argument 'alas' is not a sequence
or also::
assert_float_lists_equal: sequences [1] and [2,3] have different sizes
:param expected: The value you expect the test to have
:type expected: ``list`` or ``tuple``
:param received: The value the test actually had
:type received: ``list`` or ``tuple``
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
error = True
if not type(expected) in [list, tuple]:
if message is None:
message = (
'assert_float_lists_equal: first argument %s is not a sequence' % repr(expected))
elif not type(received) in [list, tuple]:
if message is None:
message = (
'assert_float_lists_equal: second argument %s is not a sequence' % repr(received))
elif not _check_nested_floats(expected):
if message is None:
message = (
'assert_float_lists_equal: first argument %s has non-numeric values' % repr(expected))
elif not _check_nested_floats(received):
if message is None:
message = (
'assert_float_lists_equal: second argument %s has non-numeric values' % repr(received))
elif len(expected) != len(received):
if message is None:
message = ('assert_float_lists_equal: sequences %s and %s have different sizes' %
(repr(expected), repr(received)))
else:
error = False
if error:
quit_with_error(message)
try:
if not allclose(expected, received):
error = True
if message is None:
message = 'assert_float_lists_equal: expected %s but instead got %s' % (
repr(expected), repr(received))
except Exception as e:
error = True
if message is None:
message = 'assert_float_lists_equal: sequences %s and %s are not comparable' % (
repr(expected), repr(received))
if error:
quit_with_error(message)
def assert_float_lists_not_equal(expected, received, message=None):
"""
Quits if the lists (or tuples) of floats ``expected`` and ``received`` are the same
This function takes two numbers and compares them using functionality akin
to that of``numpy``, which is a scientific computing package that allows
us to test if numbers are "close enough".
This function is similar to :func:`assert_floats_not_equal`. The
difference is that it works on lists of floats. These lists can be
multidimensional. To illustrate this, the following is an example debug
message::
assert_float_lists_not_equal: expected something different from
[[1,2],[3,4]]
**IMPORTANT**: The arguments expected and received should each be
sequences of numbers. If not this function quits with a different error
message. For example::
assert_float_lists_not_equal: first argument 'alas' is not a list
or also::
assert_float_lists_not_equal: first argument (1, 'a') has non-numeric
values
It is not a problem if the sequences have different dimensions as long as
they are numeric. In that case, the function will not quit with an error.
If there is a custom error message, that will be used instead.
:param expected: The value you expect the test to have
:type expected: ``list`` or ``tuple``
:param received: The value the test actually had
:type received: ``list`` or ``tuple``
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
error = True
if not type(expected) in [list, tuple]:
if message is None:
message = (
'assert_float_lists_not_equal: first argument %s is not a sequence' % repr(expected))
elif not type(received) in [list, tuple]:
if message is None:
message = (
'assert_float_lists_not_equal: second argument %s is not a sequence' % repr(received))
elif not _check_nested_floats(expected):
if message is None:
message = (
'assert_float_lists_not_equal: first argument %s has non-numeric values' % repr(expected))
elif not _check_nested_floats(received):
if message is None:
message = (
'assert_float_lists_not_equal: second argument %s has non-numeric values' % repr(received))
elif len(expected) != len(received):
return
else:
error = False
if error:
quit_with_error(message)
try:
if allclose(expected, received):
error = True
if message is None:
message = 'assert_float_lists_not_equal: expected something different from %s' % repr(
expected)
except ValueError:
pass
except Exception as e:
error = True
if message is None:
message = 'assert_float_lists_not_equal: sequences %s and %s are not comparable' % (
repr(expected), repr(received))
if error:
quit_with_error(message)
def assert_error(func, *args, error=AssertionError, reason=None, message=None):
"""
Quits if call func(\*args) does not crash with the given error.
This function calls func(\*args) and checks whether it crashes with the given error
(AssertionError by default). If the call does not crash, or crashes with a different
error, this function will quit with an error message.
The optional argument reason checks against the ``args`` attribute of the error
(i.e. the error reason), provided that it is not None. If reason is a tuple, it
will compare the value to args using ==. Otherwise, if it is any type other than
None, it will compare against the first element of ``args``.
The optional argument message is for the error message to print should this
function fail (i.e. it is not the error "message" of the error being tested). If
there is no custom error message, this function will print some minimal debug
information. The following is an example debug message::
assert_error: call foo(1) did not crash but instead returned 42
or also::
assert_error: call foo(1) crashed with TypeError, not AssertionError
:param func: The function to test for enforcement
:type func: ``callable``
:param args: The function arguments
:type args: ``tuple``
:param error: The expected error type (OPTIONAL)
:type error: ``class``
:param reason: The expected error reason (OPTIONAL)
:type reason: any
:param message: A custom error message (OPTIONAL)
:type message: ``str``
"""
failed = True
if not callable(func):
if message is None:
message = ('assert_error: argument %s is not callable' % repr(func))
else:
try:
result = func(*args)
if message is None:
body = repr(args) if len(args) != 1 else '(%s)' % repr(args[0])
message = ('assert_error: call %s%s did not crash but instead returned %s' % (
func.__name__, body, repr(result)))
except BaseException as e:
if e.__class__ == error:
failed = False
if type(reason) == tuple:
if reason != e.args:
failed = True
if message is None:
name = e.__class__.__name__
message = ('assert_error: %s has reason %s, not %s' % (
name, repr(e.args), repr(reason)))
elif not reason is None:
if len(e.args) == 0 or reason != e.args[0]:
failed = True
if message is None:
name = e.__class__.__name__
if len(e.args) == 0:
message = ('assert_error: %s has no reason, but expected %s' % (
name, repr(reason)))
else:
payload = e.args[0] if len(
e.args) == 1 else e.args
message = ('assert_error: %s has reason %s, not %s' % (
name, repr(payload), repr(reason)))
elif message is None:
name1 = e.__class__.__name__
name2 = error.__name__
body = repr(args) if len(args) != 1 else '(%s)' % repr(args[0])
message = ('assert_error: call %s%s crashed with %s, not %s' % (
func.__name__, body, name1, name2))
if failed:
quit_with_error(message)