After this lesson you can write automated checks for your functions, run them in one command, and understand what a failing test tells you.
Why test at all?
Running your program and eyeballing the output works for ten lines. It does not work for a hundred, because every change might break something you are no longer watching. A test is code that calls your code with known input and checks the answer. Once written, it takes a second to run, and it tells you straight away when a change broke something.
Python ships with a testing module called unittest, so there is nothing to install. Other tools exist, but the ideas here carry over to all of them.
Some code worth testing
Here is a small function for a shop, and one that has a rule about bad input:
def apply_discount(price, percent):
if not 0 <= percent <= 100:
raise ValueError("percent must be between 0 and 100")
return price - price * percent / 100
def cart_total(prices):
return sum(prices)
print(apply_discount(80, 25))
print(cart_total([2.5, 4.0, 6.0]))60.0
12.5Your first test case
A test case is a class that inherits from unittest.TestCase. Every method whose name starts with test is a test. Inside, you call your code and use an assertion to say what you expect:
import sys
import unittest
class DiscountTests(unittest.TestCase):
def test_quarter_off(self):
self.assertEqual(apply_discount(80, 25), 60)
def test_no_discount(self):
self.assertEqual(apply_discount(80, 0), 80)
def run_tests(*cases):
suite = unittest.TestSuite()
for case in cases:
suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(case))
return unittest.TextTestRunner(stream=sys.stdout, verbosity=2).run(suite)
run_tests(DiscountTests)test_no_discount (__main__.DiscountTests) ... ok
test_quarter_off (__main__.DiscountTests) ... ok
----------------------------------------------------------------------
Ran 2 tests in 0.000s
OKThe run_tests helper only exists so that the examples in this lesson can run one after another. In a real file you finish with these two lines instead, and run the file normally:
if __name__ == "__main__":
unittest.main()Each ok is a passing test. The time on the last line will differ on your machine.
Reading a failure
A test that finds a wrong answer fails, and the report says what it expected. Here is a deliberately wrong expectation. The runner writes into a buffer so that we can show just the key line:
import io
class WrongTests(unittest.TestCase):
def test_wrong_on_purpose(self):
self.assertEqual(cart_total([2, 3]), 6)
buffer = io.StringIO()
suite = unittest.defaultTestLoader.loadTestsFromTestCase(WrongTests)
result = unittest.TextTestRunner(stream=buffer).run(suite)
print(len(result.failures), "failure")
print(result.failures[0][1].splitlines()[-1])
print(buffer.getvalue().splitlines()[-1])1 failure
AssertionError: 5 != 6
FAILED (failures=1)5 != 6 is the whole story: the function returned 5, and the test expected 6. A full report also shows the file and line of the failing assertion. In real life, the fix might be in the function or in the test, and the failure tells you which one to look at.
Other assertions
assertEqual is the workhorse, but there are better tools for particular jobs. For floats, use assertAlmostEqual. For errors, use assertRaises as a context manager:
class MoreTests(unittest.TestCase):
def test_true_and_false(self):
self.assertTrue(cart_total([1]) > 0)
self.assertFalse(cart_total([]) > 0)
def test_floats(self):
self.assertAlmostEqual(cart_total([0.1, 0.2]), 0.3)
def test_bad_percent(self):
with self.assertRaises(ValueError):
apply_discount(50, 150)
def test_message(self):
with self.assertRaises(ValueError) as context:
apply_discount(50, -5)
self.assertIn("between 0 and 100", str(context.exception))
run_tests(MoreTests)test_bad_percent (__main__.MoreTests) ... ok
test_floats (__main__.MoreTests) ... ok
test_message (__main__.MoreTests) ... ok
test_true_and_false (__main__.MoreTests) ... ok
----------------------------------------------------------------------
Ran 4 tests in 0.000s
OKTesting that the error is raised matters as much as testing the happy path. Other handy ones are assertIn, assertIsNone and assertNotEqual.
Fresh data with setUp
If several tests need the same starting data, create it in setUp. It runs before every single test, so tests cannot affect each other:
class BasketTests(unittest.TestCase):
def setUp(self):
self.prices = [2.5, 4.0, 6.0]
def test_total(self):
self.assertEqual(cart_total(self.prices), 12.5)
def test_after_adding(self):
self.prices.append(7.5)
self.assertEqual(cart_total(self.prices), 20.0)
def test_untouched(self):
self.assertEqual(len(self.prices), 3)
run_tests(BasketTests)test_after_adding (__main__.BasketTests) ... ok
test_total (__main__.BasketTests) ... ok
test_untouched (__main__.BasketTests) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OKEven though test_after_adding changes the list, test_untouched still sees three prices.
Running tests from the command line
Put your code in shop.py and your tests in test_shop.py, with import unittest and from shop import apply_discount, cart_total at the top. Then, from the same folder:
python3 -m unittest
python3 -m unittest -v
python3 -m unittest test_shop.DiscountTests.test_quarter_offThe first command finds files named test*.py and runs everything. -v lists each test, and the last form runs a single one.
What makes a good test
- Each test checks one idea and has a name that says which.
- Cover normal input, edge cases (zero, empty, the maximum) and bad input.
- Tests must not depend on each other, the clock or the network.
- When you find a bug, write a test that reproduces it first, then fix it. The bug can never come back unnoticed.
A video version of this topic is in the video course at /learn/python/.
Common mistakes
- Method names that do not start with
test. They are silently skipped, so a test that never runs looks green. - Using
printinstead of assertions. A print never fails. Assertions do. - Testing floats with
assertEqual. UseassertAlmostEqualfor results of float arithmetic. - Tests that depend on order or shared state. Use
setUpto build what each test needs. - Testing only the happy path. Check the errors and the edges too.
Exercise
Write a function is_even(n) that returns whether n is even. Write a TestCase with three tests: 4 is even, 7 is not, and 0 is even. Run it with run_tests from above.
Show one possible answer
def is_even(n):
return n % 2 == 0
class EvenTests(unittest.TestCase):
def test_four(self):
self.assertTrue(is_even(4))
def test_seven(self):
self.assertFalse(is_even(7))
def test_zero(self):
self.assertTrue(is_even(0))
run_tests(EvenTests)test_four (__main__.EvenTests) ... ok
test_seven (__main__.EvenTests) ... ok
test_zero (__main__.EvenTests) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OKKey points
- A test is a small piece of code that calls your code and checks the result, so you find bugs before your users do.
- With unittest you write a class that inherits from unittest.TestCase and name each test method so that it starts with test.
- Use assertEqual, assertTrue, assertAlmostEqual and others instead of plain print, so that a wrong answer is reported as a failure.
- assertRaises checks that the right exception is raised, and setUp builds fresh data before each test.
- Run tests with python3 -m unittest. The tests in this lesson use only the standard library.