Assertion functions for comparing arrays and testing numerical code.
Recommended Assertions
assert_allclose Compare with tolerance
assert_array_equal Test exact equality
assert_array_less Test array ordering
Specialized Assertions
assert_array_almost_equal_nulp ULP-based comparison
assert_array_max_ulp Maximum ULP difference
Exception Testing
assert_raises Test exceptions
assert_warns Test warnings
assert_allclose numpy.testing.assert_allclose(actual, desired, rtol = 1e-7 , atol = 0 , equal_nan = True , err_msg = '' , verbose = True , * , strict = False )
Raises an AssertionError if two objects are not equal up to desired tolerance.
Parameters Relative tolerance: rtol * abs(desired).
If True, NaNs will compare equal.
The error message to be printed in case of failure.
If True, the conflicting values are appended to the error message.
If True, raise AssertionError when shape or dtype mismatch. Disables scalar special handling.
Notes The comparison uses:
abs (actual - desired) <= atol + rtol * abs (desired)
Examples import numpy as np from numpy.testing import assert_allclose # Basic usage actual = np.array([ 1e10 , 1e-7 ]) desired = np.array([ 1.00001e10 , 1e-8 ]) assert_allclose(actual, desired, rtol = 1e-5 ) # With absolute tolerance actual = np.array([ 1e-7 , 1e-8 ]) desired = np.array([ 0 , 0 ]) assert_allclose(actual, desired, atol = 1e-7 ) # Handle NaN values actual = np.array([ 1.0 , 2.0 , np.nan]) desired = np.array([ 1.0 , 2.0 , np.nan]) assert_allclose(actual, desired, equal_nan = True ) # Passes # Different shapes with strict mode try : assert_allclose([ 1 , 2 ], [[ 1 , 2 ]], strict = True ) except AssertionError : print ( "Strict mode enforces shape matching" ) # Custom error message assert_allclose( actual, desired, rtol = 1e-5 , err_msg = "Computation result differs from expected" )
assert_array_equal numpy.testing.assert_array_equal(actual, desired, err_msg = '' , verbose = True , * , strict = False )
Raises an AssertionError if two array_like objects are not equal.
Parameters The actual object to check.
The desired, expected object.
The error message to be printed in case of failure.
If True, the conflicting values are appended to the error message.
If True, raise AssertionError when shape or dtype mismatch.
Examples import numpy as np from numpy.testing import assert_array_equal # Integer arrays actual = np.array([ 1 , 2 , 3 ]) desired = np.array([ 1 , 2 , 3 ]) assert_array_equal(actual, desired) # Multi-dimensional actual = np.array([[ 1 , 2 ], [ 3 , 4 ]]) desired = np.array([[ 1 , 2 ], [ 3 , 4 ]]) assert_array_equal(actual, desired) # Fails on difference try : actual = np.array([ 1 , 2 , 3 ]) desired = np.array([ 1 , 2 , 4 ]) assert_array_equal(actual, desired) except AssertionError as e: print ( f "Arrays differ: { e } " ) # String arrays actual = np.array([ 'a' , 'b' , 'c' ]) desired = np.array([ 'a' , 'b' , 'c' ]) assert_array_equal(actual, desired) # Structured arrays dt = np.dtype([( 'name' , 'U10' ), ( 'age' , 'i4' )]) actual = np.array([( 'Alice' , 25 ), ( 'Bob' , 30 )], dtype = dt) desired = np.array([( 'Alice' , 25 ), ( 'Bob' , 30 )], dtype = dt) assert_array_equal(actual, desired)
assert_array_less numpy.testing.assert_array_less(x, y, err_msg = '' , verbose = True , * , strict = False )
Raises an AssertionError if two array_like objects are not ordered by less than.
Parameters The smaller object to check.
The larger object to compare.
If True, raise AssertionError when shape or dtype mismatch.
Examples import numpy as np from numpy.testing import assert_array_less # Basic comparison smaller = np.array([ 1 , 2 , 3 ]) larger = np.array([ 2 , 3 , 4 ]) assert_array_less(smaller, larger) # Element-wise less than smaller = np.array([ 1.0 , 2.0 ]) larger = np.array([ 1.1 , 2.1 ]) assert_array_less(smaller, larger) # Fails if not strictly less try : x = np.array([ 1 , 2 , 3 ]) y = np.array([ 1 , 3 , 4 ]) # First elements equal assert_array_less(x, y) except AssertionError : print ( "Not all elements strictly less" ) # Multi-dimensional x = np.array([[ 1 , 2 ], [ 3 , 4 ]]) y = np.array([[ 2 , 3 ], [ 4 , 5 ]]) assert_array_less(x, y)
assert_array_almost_equal numpy.testing.assert_array_almost_equal(actual, desired, decimal = 6 , err_msg = '' , verbose = True )
Raises an AssertionError if two objects are not equal up to desired precision.
This function is legacy. Use assert_allclose instead for more consistent floating point comparisons.
Parameters Desired precision: abs(desired-actual) < 1.5 * 10**(-decimal).
Examples import numpy as np from numpy.testing import assert_array_almost_equal, assert_allclose # Legacy approach (not recommended) actual = np.array([ 1.0000001 , 2.0000001 ]) desired = np.array([ 1.0 , 2.0 ]) assert_array_almost_equal(actual, desired, decimal = 5 ) # Recommended approach assert_allclose(actual, desired, rtol = 1e-5 , atol = 1e-8 )
assert_array_almost_equal_nulp numpy.testing.assert_array_almost_equal_nulp(x, y, nulp = 1 )
Compare two arrays relatively to their spacing (ULP - Units in Last Place).
Parameters Maximum number of unit in the last place for tolerance.
Examples import numpy as np from numpy.testing import assert_array_almost_equal_nulp # Very precise comparison x = np.array([ 1.0 , 2.0 ]) y = x + np.spacing(x) assert_array_almost_equal_nulp(x, y, nulp = 1 ) # Allow up to 5 ULP difference x = np.linspace( 0 , 1 , 100 ) y = x + 3 * np.spacing(x) assert_array_almost_equal_nulp(x, y, nulp = 5 )
assert_array_max_ulp numpy.testing.assert_array_max_ulp(a, b, maxulp = 1 , dtype = None )
Check that all items of arrays differ in at most N Units in Last Place.
Parameters Input arrays to be compared.
Maximum number of units in the last place that elements of a and b can differ.
Data-type to convert a and b to if given.
Examples import numpy as np from numpy.testing import assert_array_max_ulp # Extremely precise comparison a = np.array([ 1.0 , 2.0 , 3.0 ]) b = a + np.spacing(a) * 0.5 assert_array_max_ulp(a, b, maxulp = 1 ) # Allow larger ULP difference a = np.linspace( 0 , 1 , 100 ) b = a + 3 * np.spacing(a) assert_array_max_ulp(a, b, maxulp = 5 ) # Specify dtype for comparison a = np.array([ 1.0 , 2.0 ], dtype = np.float32) b = np.array([ 1.0000001 , 2.0000001 ], dtype = np.float32) assert_array_max_ulp(a, b, maxulp = 1 , dtype = np.float32)
assert_raises numpy.testing.assert_raises(exception_class, callable = None , * args, ** kwargs)
Fail unless an exception of class exception_class is raised.
Parameters The exception class expected to be raised.
The callable to test. Can also be used as context manager.
Examples import numpy as np from numpy.testing import assert_raises # Function call form assert_raises( ValueError , np.array, [[ 1 , 2 ], [ 3 , 4 , 5 ]]) # With arguments assert_raises( TypeError , np.add, 1 , 'a' ) # Context manager form (recommended) with assert_raises( ValueError ): np.array([[ 1 , 2 ], [ 3 , 4 , 5 ]]) # Multiple operations with assert_raises( ZeroDivisionError ): x = 1 / 0 # Check exception is NOT raised (should fail the test) try : with assert_raises( ValueError ): x = np.array([ 1 , 2 , 3 ]) # Valid operation except AssertionError : print ( "Expected exception was not raised" )
assert_raises_regex numpy.testing.assert_raises_regex(exception_class, expected_regexp, callable = None , * args, ** kwargs)
Fail unless an exception is raised with a message matching the regex.
Parameters Regular expression pattern to match against exception message.
Examples import numpy as np from numpy.testing import assert_raises_regex # Match exception message with assert_raises_regex( ValueError , "could not broadcast" ): np.add(np.array([ 1 , 2 ]), np.array([ 1 , 2 , 3 ])) # With regex pattern with assert_raises_regex( ValueError , r "shape . * mismatch" ): np.dot(np.ones(( 2 , 3 )), np.ones(( 4 , 5 )))
assert_warns numpy.testing.assert_warns(warning_class, callable = None , * args, ** kwargs)
Fail unless the given callable raises a warning.
Parameters The warning class expected to be raised.
Examples import numpy as np import warnings from numpy.testing import assert_warns # Test for deprecation warning with assert_warns( DeprecationWarning ): warnings.warn( "deprecated" , DeprecationWarning ) # Test NumPy warnings with assert_warns( RuntimeWarning ): np.divide( 1.0 , 0.0 ) # Division by zero warning
assert_no_warnings numpy.testing.assert_no_warnings(func, * args, ** kwargs)
Fail if the given callable produces any warnings.
Examples import numpy as np from numpy.testing import assert_no_warnings # Test that operation produces no warnings def safe_operation (): return np.add( 1 , 2 ) assert_no_warnings(safe_operation) # With arguments assert_no_warnings(np.add, 1 , 2 ) # Will fail if warnings are produced try : assert_no_warnings(np.divide, 1.0 , 0.0 ) except AssertionError : print ( "Function produced warnings" )
assert_string_equal numpy.testing.assert_string_equal(actual, desired)
Test if two strings are equal, with diff output if not.
Examples from numpy.testing import assert_string_equal # Strings match assert_string_equal( "hello world" , "hello world" ) # Multiline strings with diff actual = """line 1 line 2 line 3""" desired = """line 1 line 2 modified line 3""" try : assert_string_equal(actual, desired) except AssertionError as e: print (e) # Shows diff output
assert_no_gc_cycles numpy.testing.assert_no_gc_cycles(func, * args, ** kwargs)
Fail if the given callable produces any reference cycles.
Examples import numpy as np from numpy.testing import assert_no_gc_cycles # Test for reference cycles def create_array (): return np.array([ 1 , 2 , 3 ]) assert_no_gc_cycles(create_array) # Detect cycles in complex objects def create_cycle (): a = [] a.append(a) # Creates reference cycle return a try : assert_no_gc_cycles(create_cycle) except AssertionError : print ( "Reference cycle detected" )
Tolerance Guidelines Choosing rtol and atol import numpy as np from numpy.testing import assert_allclose # Default: rtol=1e-7, atol=0 # Good for double precision (float64) assert_allclose(actual, expected) # Single precision (float32) assert_allclose(actual, expected, rtol = 1e-5 , atol = 1e-7 ) # Half precision (float16) assert_allclose(actual, expected, rtol = 1e-3 , atol = 1e-5 ) # Very strict (testing algorithms) assert_allclose(actual, expected, rtol = 1e-12 , atol = 1e-14 ) # Loose (testing approximations) assert_allclose(actual, expected, rtol = 1e-2 , atol = 1e-4 )
Understanding ULP ULP (Units in Last Place) represents the spacing between floating-point numbers:
import numpy as np from numpy.testing import assert_array_max_ulp # Get ULP for a number x = 1.0 ulp = np.spacing(x) print ( f "ULP at { x } : { ulp } " ) # ~2.22e-16 for float64 # Very precise comparison (within 1 ULP) assert_array_max_ulp(x, x + ulp * 0.5 , maxulp = 1 ) # Allow more ULP for accumulated errors result = sum ([ 0.1 ] * 10 ) # May have rounding errors expected = 1.0 assert_array_max_ulp([result], [expected], maxulp = 5 )
See Also 
