Chapter 11: Testing Your Code

Python includes a tool called pip that’s used to install third-party packages. Because pip helps install packages from external resources, it’s updated often to address potential security issues. So, we’ll start by updating pip.

Open a new terminal window and issue the following command:

The first part of this command, python -m pip, tells Python to run the module pip. The second part, install --upgrade, tells pip to update a package that’s already been installed. The last part, pip, specifies which third-party package should be updated.

You can use this command to update any third-party package installed on your system:

Now that pip is up to date, we can install pytest:

We’re still using the core command pip install, without the --upgrade flag this time. Instead, we’re using the --user flag, which tells Python to install this package for the current user only. The output shows that the latest version of pytest was successfully installed, along with a number of other packages that pytest depends on.

You can use this command to install many third-party packages:

There is a wide variety of approaches to testing software. One of the simplest kinds of test is a unit test. A unit test verifies that one specific aspect of a function’s behavior is correct. A test case is a collection of unit tests that together prove that a function behaves as it’s supposed to, within the full range of situations you expect it to handle.

A good test case considers all the possible kinds of input a function could receive and includes tests to represent each of these situations. A test case with full coverage includes a full range of unit tests covering all the possible ways you can use a function. Achieving full coverage on a large project can be daunting. It’s often good enough to write tests for your code’s critical behaviors and then aim for full coverage only if the project starts to see widespread use.

With pytest, writing your first unit test is pretty straightforward. We’ll write a single test function. The test function will call the function we’re testing, and we’ll make an assertion about the value that’s returned. If our assertion is correct, the test will pass; if the assertion is incorrect, the test will fail.

Here’s the first test of the function get_formatted_name():

Test function names should be long enough that if you see the function name in a test report, you’ll have a good sense of what behavior was being tested.

If you run the file test_name_function.py directly, you won’t get any output because we never called the test function. Instead, we’ll have pytest run the test file for us.

To do this, open a terminal window and navigate to the folder that contains the test file. If you’re using VS Code, you can open the folder containing the test file and use the terminal that’s embedded in the editor window. In the terminal window, enter the command pytest. Here’s what you should see:

The last line tells us that one test passed, and it took less than 0.01 seconds to run the test.

This output indicates that the function get_formatted_name() will always work for names that have a first and last name, unless we modify the function. When we modify get_formatted_name(), we can run this test again. If the test passes, we know the function will still work for names like Janis Joplin.

What does a failing test look like? Let’s modify get_formatted_name() so it can handle middle names, but let’s do so in a way that breaks the function for names with just a first and last name, like Janis Joplin.

Here’s a new version of get_formatted_name() that requires a middle name argument:

This version should work for people with middle names, but when we test it, we see that we’ve broken the function for people with just a first and last name. This time, running pytest gives the following output:

The most important information is repeated in a shorter summary at the end, so when you’re running many tests, you can get a quick sense of which tests failed and why.

What do you do when a test fails? Assuming you’re checking the right conditions, a passing test means the function is behaving correctly and a failing test means there’s an error in the new code you wrote. So when a test fails, don’t change the test. If you do, your tests might pass, but any code that calls your function like the test does will suddenly stop working. Instead, fix the code that’s causing the test to fail. Examine the changes you just made to the function, and figure out how those changes broke the desired behavior.

In this case, get_formatted_name() used to require only two parameters: a first name and a last name. Now it requires a first name, middle name, and last name. The addition of that mandatory middle name parameter broke the original behavior of get_formatted_name(). The best option here is to make the middle name optional. Once we do, our test for names like Janis Joplin should pass again, and we should be able to accept middle names as well. Let’s modify get_formatted_name() so middle names are optional and then run the test case again:

In this new version of get_formatted_name(), the middle name is optional. If a middle name is passed to the function, the full name will contain a first, middle, and last name. Otherwise, the full name will consist of just a first and last name. Now the function should work for both kinds of names. To find out if the function still works for names like Janis Joplin, let’s run the test again:

The test passes now. This is ideal; it means the function works for names like Janis Joplin again, without us having to test the function manually. Fixing our function was easier because the failed test helped us identify how the new code broke existing behavior.

Now that we know get_formatted_name() works for simple names again, let’s write a second test for people who include a middle name. We do this by adding another test function to the file test_name_function.py:

We name this new function test_first_last_middle_name(). The function name must start with test_ so the function runs automatically when we run pytest. We name the function to make it clear which behavior of get_formatted_name() we’re testing. As a result, if the test fails, we’ll know right away what kinds of names are affected.

When we run pytest again, both tests pass:

We now know that the function still works for names like Janis Joplin, and we can be confident that it will work for names like Wolfgang Amadeus Mozart as well.

11-1. City, Country: Write a function that accepts two parameters: a city name and a country name. The function should return a single string of the form City, Country, such as Santiago, Chile. Store the function in a module called city_functions.py, and save this file in a new folder so pytest won’t try to run the tests we’ve already written. Create a file called test_cities.py that tests the function you just wrote. Write a function called test_city_country() to verify that calling your function with values such as 'santiago' and 'chile' results in the correct string. Run the test, and make sure test_city_country() passes.

11-2. Population: Modify your function so it requires a third parameter, population. It should now return a single string of the form City, Country - population xxx, such as Santiago, Chile - population 5000000. Run the test again, and make sure test_city_country() fails this time. Modify the function so the population parameter is optional. Run the test, and make sure test_city_country() passes again. Write a second test called test_city_country_population() that verifies you can call your function with the values 'santiago', 'chile', and 'population=5000000'. Run the tests one more time, and make sure this new test passes.

So far, you’ve seen just one kind of assertion: a claim that a string has a specific value. When writing a test, you can make any claim that can be expressed as a conditional statement. If the condition is True as expected, your assumption about how that part of your program behaves will be confirmed; you can be confident that no errors exist. If the condition you assume is True is actually False, the test will fail and you’ll know there’s an issue to resolve.

These are just a few examples; anything that can be expressed as a conditional statement can be included in a test.

Testing a class is similar to testing a function, because much of the work involves testing the behavior of the methods in the class. However, there are a few differences, so let’s write a class to test. Consider a class that helps administer anonymous surveys:

To show that the AnonymousSurvey class works, let’s write a program that uses the class:

This program defines a question and creates an AnonymousSurvey object with that question. The program calls show_question() to display the question and then prompts for responses. Each response is stored as it is received:

This class works for a simple anonymous survey, but say we want to improve AnonymousSurvey and the module it’s in. We could allow each user to enter more than one response, we could write a method to list only unique responses and to report how many times each response was given, or we could even write another class to manage non-anonymous surveys. Implementing such changes would risk affecting the current behavior of the class AnonymousSurvey. To ensure we don’t break existing behavior as we develop this module, we can write tests for the class.

Let’s write a test that verifies one aspect of the way AnonymousSurvey behaves. We’ll write a test to verify that a single response to the survey question is stored properly:

By default, running the command pytest with no arguments will run all the tests that pytest discovers in the current directory. To focus on the tests in one file, pass the name of the test file you want to run. Here we’ll run just the one test we wrote for AnonymousSurvey:

This is a good start, but a survey is useful only if it generates more than one response. Let’s verify that three responses can be stored correctly. To do this, we add another function to test_survey.py:

When we run the test file again, both tests (for a single response and for three responses) pass:

This works perfectly. However, these tests are a bit repetitive, so we’ll use another feature of pytest to make them more efficient.

In test_survey.py, we created a new instance of AnonymousSurvey in each test function. This is fine in the short example we’re working with, but in a real-world project with tens or hundreds of tests, this would be problematic.

In testing, a fixture helps set up a test environment. Often, this means creating a resource that’s used by more than one test. We create a fixture in pytest by writing a function with the decorator @pytest.fixture. A decorator is a directive placed just before a function definition; Python applies this directive to the function before it runs, to alter how the function code behaves. Don’t worry if this sounds complicated; you can start to use decorators from third-party packages before learning to write them yourself.

Let’s use a fixture to create a single survey instance that can be used in both test functions in test_survey.py:

We need to import pytest now, because we’re using a decorator that’s defined in pytest.

When we run the test file again, both tests still pass. These tests would be particularly useful when trying to expand AnonymousSurvey to handle multiple responses for each person. After modifying the code to accept multiple responses, you could run these tests and make sure you haven’t affected the ability to store a single response or a series of individual responses.

The structure above will almost certainly look complicated; it contains some of the most abstract code you’ve seen so far. You don’t need to use fixtures right away; it’s better to write tests that have a lot of repetitive code than to write no tests at all. Just know that when you’ve written enough tests that the repetition is getting in the way, there’s a well-established way to deal with the repetition. Also, fixtures in simple examples like this one don’t really make the code any shorter or simpler to follow. But in projects with many tests, or in situations where it takes many lines to build a resource that’s used in multiple tests, fixtures can drastically improve your test code.

When you want to write a fixture, write a function that generates the resource that’s used by multiple test functions. Add the @pytest.fixture decorator to the new function, and add the name of this function as a parameter for each test function that uses this resource. Your tests will be shorter and easier to write and maintain from that point forward.

11-3. Employee: Write a class called Employee. The init() method should take in a first name, a last name, and an annual salary, and store each of these as attributes. Write a method called give_raise() that adds $5,000 to the annual salary by default but also accepts a different raise amount. Write a test file for Employee with two test functions, test_give_default_raise() and test_give_custom_raise(). Write your tests once without using a fixture, and make sure they both pass. Then write a fixture so you don’t have to create a new employee instance in each test function. Run the tests again, and make sure both tests still pass.

D11-1. Node Formatter Function: Write a function called get_node_summary(hostname, role, ip) in a module called node_utils.py. The function should return a formatted string like kvm-01 (hypervisor) — 10.100.0.10. Write a test file test_node_utils.py with at least two test functions: one that tests the basic three-parameter call, and one that verifies the output contains the hostname.

D11-2. VLAN Lookup Function: Write a function called get_vlan_name(vlan_id) in a module called vlan_utils.py. The function should look up VLAN IDs from a dictionary and return the name, or 'Unknown VLAN' if the ID isn’t found. Write a test file test_vlan_utils.py that tests at least three VLAN IDs: one that exists in the dictionary, one that doesn’t, and one edge case.

D11-3. Service Status Class: Write a class called ServiceMonitor in service_monitor.py. The init() method should accept a name attribute. Add a method record_event(event) that appends the event to a self.events list. Write a test file test_service_monitor.py with two test functions — one that tests storing a single event, and one that tests storing three events — first without a fixture, then refactored to use a @pytest.fixture.

D11-4. BGP Peer Validator: Write a function called is_valid_peer(asn, tunnel_ip) in a module called bgp_utils.py. The function should return True if the ASN is a positive integer and the tunnel IP is a non-empty string, and False otherwise. Write a test file test_bgp_utils.py that tests at least four cases: a valid peer, an invalid ASN, an empty tunnel IP, and both invalid.

D11-5. Node Fixture Test: Write a class called Node in domus_nodes.py with attributes hostname, role, and a status defaulting to 'up'. Add methods mark_down() and mark_up() that change the status. Write a test file test_domus_nodes.py that uses a @pytest.fixture to create a shared Node instance. Write at least two test functions that verify mark_down() and mark_up() work correctly.

C11-1. Policy Formatter Function: Write a function called format_policy_entry(name, protocol, result='Allow') in a module called ise_utils.py. The function should return a formatted string like 802.1X Wired | EAP-TLS | Allow. Write a test file test_ise_utils.py with at least two test functions: one that tests the call with all three arguments, and one that tests the default result value.

C11-2. Syslog Severity Lookup: Write a function called get_severity_label(level) in syslog_utils.py. The function should return the severity label string for levels 0–7, or 'Invalid' for any other value. Write a test file test_syslog_utils.py that tests at least five severity levels: 0, 3, 6, 7, and an out-of-range value.

C11-3. Endpoint Registry Class: Write a class called EndpointRegistry in endpoint_registry.py. The init() method should initialize an empty self.endpoints list. Add a method register(mac_address) that appends the MAC address to the list. Write a test file test_endpoint_registry.py with two test functions — one for registering a single endpoint and one for registering three — first without a fixture, then refactored to use @pytest.fixture.

C11-4. Pipeline Stage Validator: Write a function called is_valid_stage(name, log_types) in pipeline_utils.py. The function should return True if name is a non-empty string and log_types is a non-empty list, and False otherwise. Write a test file test_pipeline_utils.py that tests at least four cases: a valid stage, an empty name, an empty log_types list, and both invalid.

C11-5. Survey Fixture Pattern Applied to ISE: Write a class called ISEAuditLog in ise_audit.py. The init() method should accept a node attribute and initialize an empty self.entries list. Add a method log_event(event) that appends the event string to entries. Write a test file test_ise_audit.py that uses a @pytest.fixture to create a shared ISEAuditLog instance. Write at least two test functions verifying that single and multiple events are logged correctly.

L11-1. Service Name Formatter: Write a function called format_service_status(name, state, host) in sysadmin_utils.py. The function should return a formatted string like wazuh-manager: active on kvm-01. Write a test file test_sysadmin_utils.py with at least two test functions.

L11-2. Package Version Checker: Write a function called is_version_current(installed, required) in pkg_utils.py. The function should return True if the installed version string matches the required version string, and False otherwise. Write a test file test_pkg_utils.py that tests at least three cases: matching versions, mismatched versions, and an empty installed version.

L11-3. Cron Job Registry Class: Write a class called CronRegistry in cron_registry.py. The init() method should initialize an empty self.jobs list. Add a method add_job(name, schedule) that appends a dictionary to self.jobs. Write a test file test_cron_registry.py with two test functions — one for adding a single job and one for adding three — first without a fixture, then refactored to use @pytest.fixture.

L11-4. Mount Point Validator: Write a function called is_valid_mount(path, device) in mount_utils.py. The function should return True if both path and device are non-empty strings and path starts with /, and False otherwise. Write a test file test_mount_utils.py that tests at least four cases.

L11-5. Server Fixture Test: Write a class called Server in server_classes.py with attributes hostname and status (defaulting to 'up'). Add methods shutdown() and start() that change the status. Write a test file test_server_classes.py that uses a @pytest.fixture to create a shared Server instance. Write at least two test functions verifying shutdown() and start() work correctly.

E11-1. Vocabulary Formatter Function: Write a function called format_vocab_entry(palabra, definicion, capitulo=None) in a module called vocab_utils.py. The function should return a formatted string like hacer: to do/make (Ch. 30) if a chapter is provided, or hacer: to do/make if not. Write a test file test_vocab_utils.py with at least two test functions: one that tests the call with and without the chapter argument.

E11-2. DELE Level Checker: Write a function called is_target_level(current, target) in dele_utils.py. The function should return True if current equals target and False otherwise. Write a test file test_dele_utils.py that tests at least three cases: matching levels, mismatched levels, and an empty current level.

E11-3. Chapter Notes Class: Write a class called ChapterNotes in donquijote_classes.py. The init() method should accept a chapter_number attribute and initialize an empty self.notas list. Add a method add_nota(nota) that appends the note to self.notas. Write a test file test_donquijote_classes.py with two test functions — one for adding a single note and one for adding three — first without a fixture, then refactored to use @pytest.fixture.

E11-4. Study Session Validator: Write a function called is_valid_session(topic, duration_minutes) in study_utils.py. The function should return True if topic is a non-empty string and duration_minutes is a positive integer, and False otherwise. Write a test file test_study_utils.py that tests at least four cases.

E11-5. Learner Fixture Test: Write a class called DELECandidate in dele_candidate.py with attributes name and nivel and a sessions list initialized to empty. Add a method log_session(topic) that appends the topic to sessions. Write a test file test_dele_candidate.py that uses a @pytest.fixture to create a shared DELECandidate instance. Write at least two test functions verifying that single and multiple sessions are logged correctly.