Unit tests, corner cases

How can we be so sure that the code we wrote is doing what we want it to?

Does our code work 100% of the time?

These questions can be answered by using something called units tests.

In the last section, we learned about raising exceptions, which, in a lot of cases, helps the function user identify if they are using it correctly.

But there are still some questions remaining:

How can we be so sure that the code we wrote is doing what we want it to?

Does our code work 100% of the time?

These questions can be answered by using something called units tests.

We’ll be implementing unit tests in Python using assert statements.” assert statements are just one way of implementing unit tests.

Let’s first discuss the syntax of an assert statement and then how they can be applied to the bigger concept, which is unit tests.

Assert Statements

assert 1 == 2 , "1 is not equal to 2."

AssertionError: 1 is not equal to 2.

Detailed traceback: 
  File "<string>", line 1, in <module>

assert statements can be used as sanity checks for our program.

We implement them as a “debugging” tactic to make sure our code runs as we expect it to.

When Python reaches an assert statement, it evaluates the condition to a Boolean value.

If the statement is True, Python will continue to run. However, if the Boolean is False, the code stops running, and an error message is printed.

Let’s take a look at one.

Here we have the keyword assert that checks if 1==2. Since this is False, an error is thrown, and the message beside the condition "1 is not equal to 2." is outputted.

assert 1 == 1 , "1 is not equal to 1."
print('Will this line execute?')

Will this line execute?

assert 1 == 2 , "1 is not equal to 2."
print('Will this line execute?')

AssertionError: 1 is not equal to 2.

Detailed traceback: 
  File "<string>", line 1, in <module>

Let’s take a look at an example where the Boolean is True.

Here, since the assert statement results in a True values, Python continues to run, and the next line of code is executed.

When an assert is thrown due to a Boolean evaluating to False, the next line of code does not get an opportunity to be executed.

assert 1 == 2 

AssertionError: 

Detailed traceback: 
  File "<string>", line 1, in <module>

Not all assert statements need to have a message.

We can re-write the statement from before without one.

This time you’ll notice that the error doesn’t contain the particular message beside AssertionError like we had before.

Why?

Where do assert statements come in handy?

Up to this point, we have been creating functions, and only after we have written them, we’ve tested if they work.

Some programmers use a different approach: writing tests before the actual function. This is called Test-Driven Development.

This may seem a little counter-intuitive, but we’re creating the expectations of our function before the actual function code.

Often we have an idea of what our function should be able to do and what output is expected.

If we write our tests before the function, it helps understand exactly what code we need to write and it avoids encountering large time-consuming bugs down the line.

Once we have a serious of tests for the function, we can put them into assert statements as an easy way of checking that all the tests pass.

What to test?

def exponent_a_list(numerical_list, exponent=2):
    new_exponent_list = list()
    
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    
    return new_exponent_list

assert exponent_a_list([1, 2, 4, 7], 2) == [1, 4, 16, 49], "incorrect output for exponent = 2"

assert exponent_a_list([1, 2, 3], 3) == [1, 8, 27], "incorrect output for exponent = 3"

assert type(exponent_a_list([1,2,4], 2)) == list, "output type not a list"

So, what kind of tests do we want?

We want to keep these tests simple - things that we know are true or could be easily calculated by hand.

For example, let’s look at our exponent_a_list() function.

Easy cases for this function would be lists containing numbers that we can easily square or cube.

For example, we expect the square output of [1, 2, 4, 7] to be [1, 4, 16, 49].

The test for this would look like the one shown here.

It is recommended to write multiple tests.

Let’s write another test for a differently sized list as well as different values for both input arguments numerical_list and exponent.

Let’s make another test for exponent = 3. Again, we use numbers that we know the cube of.

We can also test that the type of the returned object is correct.

False Positives

def bad_function(numerical_list, exponent=2):
    new_exponent_list = [numerical_list[0] ** exponent] # seed list with first element
    for number in numerical_list[1:]:
        new_exponent_list.append(number ** exponent)
    return new_exponent_list

assert bad_function([1, 2, 4, 7], 2) == [1, 4, 16, 49], "incorrect output for exponent = 2"
assert bad_function([2, 1, 3], 3) == [8, 1, 27], "incorrect output for exponent = 3"

bad_function([], 2)

IndexError: list index out of range

Detailed traceback: 
  File "<string>", line 1, in <module>
  File "<string>", line 2, in bad_function

Just because all our tests pass, this does not mean our program is necessarily correct.

It’s common that our tests can pass, but our code contains errors.

Let’s take a look at the function bad_function(). It’s very similar to exponent_a_list except that it separately computes the first entry before doing the rest in the loop.

This function looks like it would work perfectly fine, but what happens if we get an input argument for numerical_list that cannot be sliced?

Let’s write some unit tests using assert statements and see what happens.

Here, it looks like our tests pass at first.

But what happens if we try our function with an empty list?

We get an unexpected error! How do we avoid this?

Write a lot of tests and don’t be overconfident, even after writing a lot of tests!

Checking an empty list in our bad_function() function is an example of checking a corner case.

A corner case is an input that is reasonable but a bit unusual and may trip up our code.

Testing Functions that Work with Data

def column_stats(df, column):
   stats_dict = {'max': df[column].max(),
                 'min': df[column].min(),
                 'mean': round(df[column].mean()),
                 'range': df[column].max() - df[column].min()}
   return stats_dict

Often, we will be making functions that work on data.

For example, perhaps we want to write a function called column_stats that returns some summary statistics in the form of a dictionary.

The function here is something we might have envisioned. (Note that if we’re using test-driven development, this function will just be an idea, not completed code.)

In these situations, we need to invent some sort of data so that we can easily calculate the max, min, range, and mean and write unit tests to check that our function does the correct operations.

The data can be made from scratch using functions such as pd.DataFrame() or pd.DataFrame.from_dict() which we learned about in module 4.

You can also upload a very small slice of an existing dataframe.

data = {'name': ['Cherry', 'Oak', 'Willow', 'Fir', 'Oak'], 
        'height': [15, 20, 10, 5, 10], 
        'diameter': [2, 5, 3, 10, 5], 
        'age': [0, 0, 0, 0, 0], 
        'flowering': [True, False, True, False, False]}
         
forest = pd.DataFrame.from_dict(data)
forest

	name	height	diameter	age	flowering
0	Cherry	15	2	0	True
1	Oak	20	5	0	False
2	Willow	10	3	0	True
3	Fir	5	10	0	False
4	Oak	10	5	0	False

assert column_stats(forest, 'height') == {'max': 20, 'min': 5, 'mean': 12.0, 'range': 15}
assert column_stats(forest, 'diameter') == {'max': 10, 'min': 2, 'mean': 5.0, 'range': 8}
assert column_stats(forest, 'age') == {'max': 0, 'min': 0, 'mean': 0, 'range': 0}

The values we chose in our columns should be simple enough to easily calculate the expected output of our function.

Just like how we made unit tests using calculations we know to be true, we do the same using a simple dataset we call helper data.

The dataframe must have a small dimension to keep the calculations simple.

The tests we write for the function column_stats() are now easy to calculate since the values we are using are few and simple.

We wrote tests that check different columns in our forest dataframe.

Systematic Approach

We use a systematic approach to design our function using a general set of steps to follow when writing programs.

1. Write the function stub: a function that does nothing but accepts all input parameters and returns the correct datatype.

def exponent_a_list(numerical_list, exponent=2):
    return list()

We use a systematic approach to design our function using a general set of steps to follow when writing programs.

The approach we recommend includes 5 steps:

1. Write the function stub: a function that does nothing but accepts all input parameters and returns the correct datatype.

This means we are writing the skeleton of a function.

We include the line that defines the function with the input arguments and the return statement returning the object with the desired data type.

Using our exponent_a_list() function as an example, we include the function’s first line and the return statement.

2. Write tests to satisfy the design specifications.

def exponent_a_list(numerical_list, exponent=2):
    return list()
   
assert type(exponent_a_list([1,2,4], 2)) == list, "output type not a list"
assert exponent_a_list([1, 2, 4, 7], 2) == [1, 4, 16, 49], "incorrect output for exponent = 2"
assert exponent_a_list([1, 2, 3], 3) == [1, 8, 27], "incorrect output for exponent = 3"

AssertionError: incorrect output for exponent = 2

Detailed traceback: 
  File "<string>", line 1, in <module>

2. Write tests to satisfy the design specifications.

This is where our assert statements come in.

We write tests that we want our function to pass.

In our exponent_a_list() example, we expect that our function will take in a list and an optional argument named exponent and then returns a list with the exponential value of each element of the input list.

Here we can see our code fails since we have no function code yet!

3. Outline the program with pseudo-code.

def exponent_a_list(numerical_list, exponent=2):

    # create a new empty list
    # loop through all the elements in numerical_list
    # for each element calculate element ** exponent
    # append it to the new list 
    
    return list()
    
assert type(exponent_a_list([1,2,4], 2)) == list, "output type not a list"
assert exponent_a_list([1, 2, 4, 7], 2) == [1, 4, 16, 49], "incorrect output for exponent = 2"
assert exponent_a_list([1, 2, 3], 3) == [1, 8, 27], "incorrect output for exponent = 3"

AssertionError: incorrect output for exponent = 2

Detailed traceback: 
  File "<string>", line 1, in <module>

3. Outline the program with pseudo-code.

Pseudo-code is an informal but high-level description of the code and operations that we wish to implement.

In this step, we are essentially writing the steps that we anticipate needing to complete our function as comments within the function.

So for our function pseudo-code includes:

# create a new empty list
# loop through all the elements in numerical_list
# for each element calculate element ** exponent
# append it to the new list

4. Write code and test frequently.

def exponent_a_list(numerical_list, exponent=2):
    new_exponent_list = list()
    
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    
    return new_exponent_list
    
assert type(exponent_a_list([1,2,4], 2)) == list, "output type not a list"
assert exponent_a_list([1, 2, 4, 7], 2) == [1, 4, 16, 49], "incorrect output for exponent = 2"
assert exponent_a_list([1, 2, 3], 3) == [1, 8, 27], "incorrect output for exponent = 3"

4. Write code and test frequently.

Here is where we fill in our function.

As you work on the code, more and more tests of the tests that you wrote will pass until finally, all your assert statements no longer produce any error messages.

5. Write documentation.

def exponent_a_list(numerical_list, exponent=2):
    """ Creates a new list containing specified exponential values of the input list. 
    
    Parameters
    ----------
    numerical_list : list
        The list from which to calculate exponential values from
    exponent : int or float, optional
        The exponent value (the default is 2, which implies the square).
    
    Returns
    -------
    new_exponent_list : list
        A new list containing the exponential value specified of each of
        the elements from the input list 
        
    Examples
    --------
    >>> exponent_a_list([1, 2, 3, 4])
    [1, 4, 9, 16]
    """
    new_exponent_list = list()
    for number in numerical_list:
        new_exponent_list.append(number ** exponent)
    return new_exponent_list

5. Write documentation.

Finally, we finish writing our function with a docstring.

Let’s apply what we learned!