how to test that an Exception is raised

When an Exception is raised, it stops the program from running. I can use the assertRaises method from the unittest.TestCase class to test that some code raises an Exception.

assertRaises checks that the code in its context, raises the Exception it is given in parentheses

preview

These are the tests I have by the end of the chapter

import src.exceptions
import unittest


class TestExceptions(unittest.TestCase):

    def test_catching_module_not_found_error_in_tests(self):
        with self.assertRaises(ModuleNotFoundError):
            import does_not_exist

    def test_catching_name_error_in_tests(self):
        with self.assertRaises(NameError):
            does_not_exist

    def test_catching_attribute_error_in_tests(self):
        with self.assertRaises(AttributeError):
            src.exceptions.does_not_exist

    def test_catching_type_error_in_tests(self):
        with self.assertRaises(TypeError):
            src.exceptions.function_name('the input')

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        with self.assertRaises(IndexError):
            a_list[-5]

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(KeyError):
            {'key': 'value'}['does_not_exist']

    def test_catching_zero_division_error_in_tests(self):
        with self.assertRaises(ZeroDivisionError):
            1 / 0

    def test_catching_exceptions_in_tests(self):
        with self.assertRaises(Exception):
            raise Exception

questions about testing Exceptions

Here are questions you can answer after going through this chapter

How can I make sure an Exception is raised?
What causes ModuleNotFoundError?
What causes NameError?
What causes AttributeError?
What causes TypeError?
What causes IndexError?
What causes KeyError?
What causes ZeroDivisionError?
What Exception do all the other Exceptions come from

requirements

makePythonTdd.sh or makePythonTdd.ps1

start the project

I open a terminal
I type pwd to make sure I am in the pumping_python folder
```
pwd
```
the terminal goes back to the command line
```
.../pumping_python
```
Note

if you are not in the pumping_python folder, try cd ~/pumping_python
I name this project exceptions
I open makePythonTdd.sh or makePythonTdd.ps1 in the editor
Tip

Here is a quick way to open makePythonTdd.sh or makePythonTdd.ps1 if you are using Visual Studio Code
```
code makePythonTdd.sh
```
on Windows without Windows Subsystem for Linux use
```
code makePythonTdd.ps1
```

I change everywhere I have more_magic in makePythonTdd.sh or makePythonTdd.ps1 to the name of this project

#!/bin/bash
mkdir exceptions
cd exceptions
mkdir src
touch src/exceptions.py
mkdir tests
touch tests/__init__.py

echo "import unittest


class TestExceptions(unittest.TestCase):

    def test_failure(self):
        self.assertFalse(True)


# Exceptions seen
# AssertionError
" > tests/test_exceptions.py

I run the program in the terminal

./makePythonTdd.sh

Attention

on Windows without Windows Subsystem for Linux use makePythonTdd.ps1 NOT makePythonTdd.sh

./makePythonTdd.ps1

the terminal shows AssertionError

================================= FAILURES =================================
_____________________________ TestExceptions.test_failure ______________________________

self = <tests.test_exceptions.TestExceptions testMethod=test_failure>

    def test_failure(self):
>       self.assertFalse(True)
E       AssertionError: True is not false

tests/test_exceptions.py:7: AssertionError
================================ short test summary info =================================
FAILED tests/test_exceptions.py::TestExceptions::test_failure - AssertionError: True is not false
============================ 1 failed in X.YZs =============================

I hold ctrl (Windows/Linux) or option/command (MacOS) on the keyboard and use the mouse to click on tests/test_exceptions.py:7 to open it in the editor
then I change True to False in the assertion
```
7        self.assertFalse(False)
```
the test passes

test_catching_module_not_found_error_in_tests

ModuleNotFoundError is raised when I try to import a module that does NOT exist

RED: make it fail

I change test_failure to test_catching_module_not_found_error_in_tests with an import statement in test_exceptions.py

class TestExceptions(unittest.TestCase):

    def test_catching_module_not_found_error_in_tests(self):
        import does_not_exist

# Exceptions seen

the terminal shows ModuleNotFoundError

ModuleNotFoundError: No module named 'does_not_exist'

I cannot import a module that does not exist. A module is any file that ends in .py

GREEN: make it pass

I add ModuleNotFoundError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError

I can make does_not_exist.py in the src folder (directory) to solve the problem but I want to catch/handle it in the test. This way I can show that import does_not_exist raises ModuleNotFoundError when the file does NOT exist. I add the assertRaises method
```
6    def test_catching_module_not_found_error_in_tests(self):
7        with self.assertRaises(ModuleNotFoundError):
8            import does_not_exist
```
the test passes.

assertRaises checks that the code in its context, raises the Exception it is given in parentheses. ModuleNotFoundError is raised when I try to import a module that does NOT exist

test_catching_name_error_in_tests

NameError is raised when I use a name that is not defined in the file I am working in

RED: make it fail

I add another failing test

    def test_catching_module_not_found_error_in_tests(self):
        with self.assertRaises(ModuleNotFoundError):
            import does_not_exist

    def test_catching_name_error_in_tests(self):
        does_not_exist

the terminal shows NameError

NameError: name 'does_not_exist' is not defined

because there is no definition for does_not_exist in test_exceptions.py

I add NameError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError

GREEN: make it pass

I add assertRaises

      def test_catching_name_error_in_tests(self):
          with self.assertRaises(NameError):
              does_not_exist

the test passes, showing that NameError is raised when I use a name that is not defined in the file

test_catching_attribute_error_in_tests

AttributeError is raised when I try to call something that does NOT exist from something that does exist

RED: make it fail

I add another failing test, this time for AttributeError

    def test_catching_name_error_in_tests(self):
        with self.assertRaises(NameError):
            does_not_exist

    def test_catching_attribute_error_in_tests(self):
        src.exceptions.does_not_exist

the terminal shows NameError

NameError: name 'src' is not defined

I add an import statement at the top of the file for the module
```
1import src.exceptions
2import unittest
```
the terminal shows AttributeError
```
AttributeError: module 'src.exceptions' has no attribute 'does_not_exist'
```
src.exceptions.does_not_exist is like an address
- src is the src folder
- exceptions is exceptions.py in the src folder
- src.exceptions.does_not_exist is pointing to something named does_not_exist in exceptions.py in the src folder
the failure happened because Python cannot find does_not_exist in exceptions.py in the src folder. tried to get something that does NOT exist from something that exists

I add the AttributeError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError
# AttributeError

GREEN: make it pass

I add the assertRaises method

    def test_catching_attribute_error_in_tests(self):
        with self.assertRaises(AttributeError):
            src.exceptions.does_not_exist

the test passes. AttributeError is raised when I try to call something that does NOT exist from something that does exist

test_catching_type_error_in_tests

TypeError is raised when I call something in a way that it should NOT be called

RED: make it fail

I add a failing test for TypeError

    def test_catching_attribute_error_in_tests(self):
        with self.assertRaises(AttributeError):
            src.exceptions.does_not_exist

    def test_catching_type_error_in_tests(self):
        src.exceptions.function_name('the input')

the terminal shows AttributeError

AttributeError: module 'src.exceptions' has no attribute 'function_name'

I open exceptions.py from the src folder in the editor, then add the name
```
1function_name
```
the terminal shows NameError
```
NameError: name 'function_name' is not defined
```
I point it to None to define it
```
1function_name = None
```
the terminal shows TypeError
```
TypeError: 'NoneType' object is not callable
```
a reminder that I cannot call None like a function

I add TypeError to the list of Exceptions seen in test_exceptions.py

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError
# AttributeError
# TypeError

GREEN: make it pass

I use assertRaises to take care of the Exception

    def test_catching_type_error_in_tests(self):
        with self.assertRaises(TypeError):
            src.exceptions.function_name('the input')

the test passes

REFACTOR: make it better

when I make function_name a function in exceptions.py
```
1def function_name():
2    return None
```
the terminal still shows green because TypeError is raised since the call from the test - src.exceptions.function_name('the input') sends 'the input' as input and the function does not take input
when I add a parameter to the definition
```
1def function_name(parameter_name):
2    return None
```
the terminal shows AssertionError
```
AssertionError: TypeError not raised
```
because TypeError is NOT raised since the function call matches the definition. I undo the change
```
1def function_name():
2    return None
```
the terminal shows green again

TypeError is raised when I call something in a way that it should NOT be called

test_catching_index_error_in_tests

IndexError is raised when I try to index a list with a number that is

bigger than or the same as the number of items in the lists
smaller than the negative of the number of items in the list

RED: make it fail

I want to test catching IndexError, I add a new test with a list

    def test_catching_type_error_in_tests(self):
        with self.assertRaises(TypeError):
            src.exceptions.function_name('the input')

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']

the first item in a list has 0 as its index

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        a_list[0]

the terminal shows green

The index for the last item is the total number of items minus 1, which is 3 in this case

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        a_list[3]

still green

When I use a number that is bigger than the index for the last item
```
23    def test_catching_index_error_in_tests(self):
24        a_list = [1, 2, 3, 'n']
25        a_list[4]
```
the terminal shows IndexError
```
IndexError: list index out of range
```
I cannot use a number that is bigger than the index of the last item in a list or that is greater than or equal to the length of the list

I add IndexError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError
# AttributeError
# TypeError
# IndexError

GREEN: make it pass

I add assertRaises

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]

the test passes

REFACTOR: make it better

I can also index with negative numbers, the one for the last item in the list is -1, like reading from right to left

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        a_list[-1]

the terminal still shows passing tests

The index for the first item is negative the total number of items, -4 in this case

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        a_list[-4]

still green

When I use a negative number that is outside the range

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        a_list[-5]

the terminal shows IndexError

IndexError: list index out of range

I add assertRaises

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        with self.assertRaises(IndexError):
            a_list[-5]

the terminal shows green again. I cannot use a number that is smaller than the negative of the total number of items in the list to index the list

It looks like this is a duplication of the assertRaises but it is not, even though the test is green when I remove the second one

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
            a_list[-5]
        # with self.assertRaises(IndexError):

I show why this is not a repetition at the end of the chapter

I undo the change for now

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        with self.assertRaises(IndexError):
            a_list[-5]

IndexError is raised when I try to index a list with a number that is

bigger than or the same as the number of items in the lists
smaller than the negative of the number of items in the list

test_catching_key_error_in_tests

KeyError is raised when I try to use a key that is NOT in a dictionary

RED: make it fail

I add a dictionary to a new test for KeyError

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        with self.assertRaises(IndexError):
            a_list[-5]

    def test_catching_key_error_in_tests(self):
        {'key': 'value'}

when I try to get the value of a key that is in the dictionary

    def test_catching_key_error_in_tests(self):
        {'key': 'value'}['key']

the terminal shows green

when I use a key that is NOT in the dictionary

    def test_catching_key_error_in_tests(self):
        {'key': 'value'}['not_in_dictionary']

the terminal shows KeyError

KeyError: 'not_in_dictionary'

I add KeyError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError
# AttributeError
# TypeError
# IndexError
# KeyError

GREEN: make it pass

I add assertRaises to the test

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(KeyError):
            {'key': 'value'}['not_in_dictionary']

the test passes. KeyError is raised when I try to use a key that is NOT in a dictionary

test_catching_zero_division_error_in_tests

RED: make it fail

I add another failing test

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(KeyError):
            {'key': 'value'}['not_in_dictionary']

    def test_catching_zero_division_error_in_tests(self):
        1 / 0

the terminal shows ZeroDivisionError

ZeroDivisionError: division by zero

I cannot divide a number by 0

I add ZeroDivisionError to the list of Exceptions seen

# Exceptions seen
# AssertionError
# ModuleNotFoundError
# NameError
# AttributeError
# TypeError
# IndexError
# KeyError
# ZeroDivisionError

GREEN: make it pass

I add assertRaises

    def test_catching_zero_division_error_in_tests(self):
        with self.assertRaises(ZeroDivisionError):
            1 / 0

the test passes. ZeroDivisionError is raised when I try to divide any number by 0, same as I get undefined when I try it with a calculator, because dividing by 0 is underfined in Mathematics, I can use this with test_division in the calculator project

test_catching_exceptions_in_tests

RED: make it fail

I add a failing test with the raise statement

    def test_catching_zero_division_error_in_tests(self):
        with self.assertRaises(ZeroDivisionError):
            1 / 0

    def test_catching_exceptions_in_tests(self):
        raise Exception

the terminal shows Exception

Exception

Exception is the mother of all the Exceptions covered so far, they inherit from it

I can use the raise statement to cause any Exception I want

    def test_catching_exceptions_in_tests(self):
        raise AssertionError

and the terminal shows the Exception I give the raise statement

AssertionError

I change the Exception back

    def test_catching_exceptions_in_tests(self):
        raise Exception

the terminal shows Exception

Exception

GREEN: make it pass

I add the assertRaises method to catch it

    def test_catching_exceptions_in_tests(self):
        with self.assertRaises(Exception):
            raise Exception


# Exceptions seen

the terminal shows all tests are passing. The assertRaises method checks that the code under it raises the Exception it is given in parentheses

REFACTOR: make it better

I can use Exception to catch any of the Exceptions that inherit from it, its children

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(Exception):
            {'key': 'value'}['not_in_dictionary']

    def test_catching_zero_division_error_in_tests(self):
        with self.assertRaises(Exception):
            1 / 0

all the tests are still green.

The problem with using Exception to catch its children, is it does not tell anyone that reads the code what the actual error is or which line caused it, especially when there is more than one line of code in the context.

It is better to be specific, from the Zen of Python: Explicit is better than implicit

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(KeyError):
            {'key': 'value'}['not_in_dictionary']

    def test_catching_zero_division_error_in_tests(self):
        with self.assertRaises(ZeroDivisionError):
            1 / 0

I cannot use sibling or cousin Exceptions to catch other Exceptions

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(ModuleNotFoundError):
            {'key': 'value'}['not_in_dictionary']

the terminal shows KeyError

KeyError: 'not_in_dictionary'

because it is not ModuleNotFoundError even though they are both Exceptions. I undo the change

    def test_catching_key_error_in_tests(self):
        with self.assertRaises(KeyError):
            {'key': 'value'}['not_in_dictionary']

the test passes

I cannot use children Exceptions to catch parent Exceptions

    def test_catching_exceptions_in_tests(self):
        with self.assertRaises(ZeroDivisionError):
            raise Exception

the terminal shows Exception

Exception

because it is not ZeroDivisionError even though it is an Exception. I undo the change

    def test_catching_exceptions_in_tests(self):
        with self.assertRaises(Exception):
            raise Exception

the test passes

one exception one exception handler

As promised here is why the second AssertRaises in test_catching_index_error_in_tests is not a repetition, even though the test still passes when I remove it

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
            a_list[-5]
        # with self.assertRaises(IndexError):

If I add a raise statement between the 2 lines

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
            raise Exception
            a_list[-5]
        # with self.assertRaises(IndexError):

the terminal still shows green, which is NOT the expected behavior. Exception is not IndexError and still does NOT get raised. The assertRaises exits after the first line that causes IndexError and does NOT run the other lines.

When I move the raise statement above the first IndexError

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            raise Exception
            a_list[4]
            a_list[-5]
        # with self.assertRaises(IndexError):

the terminal shows Exception

Exception

because it is NOT IndexError, this is the expected behavior

I remove the failing line and put the assertRaises back in the right place

    def test_catching_index_error_in_tests(self):
        a_list = [1, 2, 3, 'n']
        with self.assertRaises(IndexError):
            a_list[4]
        with self.assertRaises(IndexError):
            a_list[-5]

all tests are passing!

I know how to test that an Exception is raised. As a rule of thumb I write one line of code for one Exception, this way I always know which line caused which Exception

close the exceptions project

I close test_exceptions.py in the editor
I click in the terminal and exit the tests with ctrl+c on the keyboard, the terminal shows

…/pumping_python

I am back in the pumping_python directory

Note

on Windows without Windows Subsystem for Linux

the terminal shows
```
(.venv) ...\pumping_python\type_error
```
I deactivate the virtual environment
```
deactivate
```
the terminal goes back to the command line, (.venv) is no longer on the left side
```
...\pumping_python\exceptions
```
I change directory to the parent of exceptions
```
cd ..
```
the terminal shows
```
...\pumping_python
```
I am back in the pumping_python directory

review

I can use assertRaises to catch Exceptions in tests and tested the following

How many questions can you answer after going through this chapter?

code from the chapter

Do you want to see all the CODE I typed in this chapter?

what is next?

you know

Would you like to test handling Exceptions in programs?

rate pumping python

If this has been a 7 star experience for you, please leave a 5 star review. It helps other people get into the book too

how to handle Exceptions (Errors)

how to make a calculator 2