Unit Test Functions

import introcs

These functions provides simple unit testing tools. They are a replacement for the built-in Python package unittest, which is much less user friendly and requires an understanding of object-oriented programming. If students are not writing test cases from the beginning, you are doing it wrong.

Type Checking

isfloat

introcs.isfloat(s)

Checks whether the string s represents a float.

Parameters

s (str) – the candidate string to test

Returns

True if s is the string representation of a number

Return type

bool

isint

introcs.isint(s)

Checks whether the string s represents an integer.

Parameters

s (str) – the candidate string to test

Returns

True if s is the string representation of an integer

Return type

bool

isbool

introcs.isbool(s)

Checks whether the string s represents a boolean.

The string requires Python capitalization (e.g. ‘True’, not ‘true’).

Parameters

s (str) – the candidate string to test

Returns

True if s is the string representation of a boolean

Return type

bool

Comparing Floats

isclose

introcs.isclose(a, b, [rtol, [atol, [equal_nan]]])

Returns a boolean or sequence comparing to 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]]
Parameters
  • a (number or sequence) – Input to compare

  • b (number or sequence) – Input sequence to compare

  • rtol (float) – The relative tolerance parameter (Optional).

  • atol (float) – The absolute tolerance parameter (Optional).

  • equal_nan (bool) – Whether to compare NaN’s as equal (Optional).

Returns

a boolean or sequence comparing to inputs element-wise

Return type

bool or sequence

allclose

introcs.allclose(a, b, [rtol, [atol, [equal_nan]]])

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 sequences 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
Parameters
  • a (sequence) – Input sequence to compare

  • b (sequence) – Input sequence to compare

  • rtol (float) – The relative tolerance parameter (Optional).

  • atol (float) – The absolute tolerance parameter (Optional).

  • equal_nan (bool) – Whether to compare NaN’s as equal (Optional).

Asserting Tests

assert_equals

introcs.assert_equals(expected, received, [message])

Quits if expected and received differ.

The meaning of “differ” for this function is !=. As a result, this assert function is not necessarily reliable when expected and received are of type float. You should use the function assert_floats_equal() for that application.

If there is no custom error message, this function will print some minimal debug information. The following is an example debug message:

assert_equals: expected 'yes' but instead got 'no'
Parameters
  • expected – The value you expect the test to have

  • received – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_not_equals

introcs.assert_not_equals(expected, received, [message])

Quits if expected and received differ.

The meaning of “differ” for this function is !=. As a result, this assert function is not necessarily reliable when expected and received are of type float. You should use the function assert_floats_not_equal() for that application.

If there is no custom error message, this function will print some minimal debug information. The following is an example debug message:

assert_not_equals: expected something different from 'n' 
Parameters
  • expected – The value you expect the test to have

  • received – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_true

introcs.assert_true(received, [message])

Quits if received is False.

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 instead got False
Parameters
  • received – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_false

introcs.assert_false(received, [message])

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 instead got True
Parameters
  • received – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_floats_equal

introcs.assert_floats_equal(expected, received, [message])

Quits if the floats expected and received differ.

This function takes two numbers and compares them using functions from the numerical package numpy. This is a scientific computing package that allows us to test if numbers are “close enough”. Hence, unlike assert_equal(), the meaning of “differ” for this function is defined by numpy.

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

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_equal: first argument 'alas' is not a number
Parameters
  • expected (float) – The value you expect the test to have

  • received (float) – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_floats_not_equal

introcs.assert_floats_not_equal(expected, received, [message])

Quits if floats expected and received are the same.

This function takes two numbers and compares them using functions from the numerical package numpy. This is a scientific computing package that allows us to test if numbers are “close enough”. Hence, unlike assert_not_equal(), the meaning of “same” for this function is defined by numpy.

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
Parameters
  • expected (float) – The value you expect the test to have

  • received (float) – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_float_lists_equal

introcs.assert_float_lists_equal(expected, received, [message])

Quits if the lists (or tuples) of floats expected and received differ

This function takes two numbers and compares them using functions from the numerical package numpy. This is a scientific computing package that allows us to test if numbers are “close enough”. Hence, unlike assert_equal(), the meaning of “differ” for this function is defined by numpy.

This function is similar to 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. Furthemore, 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
Parameters
  • expected (list or tuple) – The value you expect the test to have

  • received (list or tuple) – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_float_lists_not_equal

introcs.assert_float_lists_not_equal(expected, received, [message])

Quits if the lists (or tuples) of floats expected and received are the same

This function takes two numbers and compares them using functions from the numerical package numpy. This is a scientific computing package that allows us to test if numbers are “close enough”. Hence, unlike assert_not_equal(), the meaning of “same” for this function is defined by numpy.

This function is similar to 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.

Parameters
  • expected (list or tuple) – The value you expect the test to have

  • received (list or tuple) – The value the test actually had

  • message (str) – A custom error message (OPTIONAL)

assert_error

introcs.assert_error(func, *args, [error, [message]])

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.

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
Parameters
  • func (callable) – The function to test for enforcement

  • args (tuple) – The function arguments

  • error (class) – The expected error type (OPTIONAL)

  • message (str) – A custom error message (OPTIONAL)