pdb: Debugging Test Failures

The pdb module is the Python debugger in the standard library. You use --pdb to have pytest start a debugging session at the point of failure. Let’s look at pdb in action in the context of the Tasks project.

In ​Parametrizing Fixtures​, we left the Tasks project with a few failures:

Before we look at how pdb can help us debug this test, let’s take a look at the pytest options available to help speed up debugging test failures, which we first looked at in ​Using Options​:

• --tb=[auto/long/short/line/native/no]: Controls the traceback style.
• -v / --verbose: Displays all the test names, passing or failing.
• -l / --showlocals: Displays local variables alongside the stacktrace.
• -lf / --last-failed: Runs just the tests that failed last.
• -x / --exitfirst: Stops the tests session with the first failure.
• --pdb: Starts an interactive debugging session at the point of failure.

Installing MongoDB

As mentioned in Chapter 3, ​pytest Fixtures​, running the MongoDB tests requires installing MongoDB and pymongo. I’ve been testing with the Community Server edition found at https://www.mongodb.com/download-center. pymongo is installed with pip: pip install pymongo. However, this is the last example in the book that uses MongoDB. To try out the debugger without using MongoDB, you could run the pytest commands from code/ch2/, as this directory also contains a few failing tests.

We just ran the tests from code/ch3/c to see that some of them were failing. We didn’t see the tracebacks or the test names because --tb=no turns off tracebacks, and we didn’t have --verbose turned on. Let’s re-run the failures (at most three of them) with verbose:

Now we know which tests are failing. Let’s look at just one of them by using -x, including the traceback by not using --tb=no, and showing the local variables with -l:

Quite often this is enough to understand the test failure. In this particular case, it’s pretty clear that task_id is not an integer—it’s an instance of ObjectId. ObjectId is a type used by MongoDB for object identifiers within the database. My intention with the tasksdb_pymongo.py layer was to hide particular details of the MongoDB implementation from the rest of the system. Clearly, in this case, it didn’t work.

However, we want to see how to use pdb with pytest, so let’s pretend that it wasn’t obvious why this test failed. We can have pytest start a debugging session and start us right at the point of failure with --pdb:

Now that we are at the (Pdb) prompt, we have access to all of the interactive debugging features of pdb. When looking at failures, I regularly use these commands:

• p/print expr: Prints the value of exp.

• pp expr: Pretty prints the value of expr.

• l/list: Lists the point of failure and five lines of code above and below.

• l/list begin,end: Lists specific line numbers.

• a/args: Prints the arguments of the current function with their values. (This is helpful when in a test helper function.)

• u/up: Moves up one level in the stack trace.

• d/down: Moves down one level in the stack trace.

• q/quit: Quits the debugging session.

Other navigation commands like step and next aren’t that useful since we are sitting right at an assert statement. You can also just type variable names and get the values.

You can use p/print expr similar to the -l/--showlocals option to see values within the function:

Now you can quit the debugger and continue on with testing.

If we hadn’t used -x, pytest would have opened pdb again at the next failed test. More information about using the pdb module is available in the Python documentation.^[20]