unittest: first tests with standard Python tools¶
After this file, you will be able to create a test file, write a
unittest.TestCaseclass, run tests withpython -m unittest, and understand the basic assert methods.
1. Why you need this¶
unittest is Python's standard library for testing. You do not need to install it.
Why learn it if pytest exists?
- Django's
TestCaseis built on the ideas ofunittest. - Many older and larger projects use exactly this style.
unittestshows the structure of a test well: class, method, assertion.- Once you understand
unittest, Django tests become much clearer.
2. Mental model¶
A unittest.TestCase is a separate lab room for a group of similar checks.
The class TestMathFunctions means:
“Checks for math functions live here.”
The method test_add_two_numbers means:
“Here is a specific experiment: adding two numbers.”
3. A first example from scratch¶
Folder structure:
The file math_utils.py:
The file test_math_utils.py:
import unittest
from math_utils import add, divide
class TestMathFunctions(unittest.TestCase):
def test_add_two_numbers(self):
result = add(2, 3)
self.assertEqual(result, 5)
def test_divide_by_zero_raises_error(self):
with self.assertRaises(ZeroDivisionError):
divide(10, 0)
if __name__ == "__main__":
unittest.main()
Running all tests in the folder:
Running a specific file:
A possible result:
What the two dots mean:
| Symbol | Meaning |
|---|---|
. |
One test passed |
F |
Assertion failed |
E |
An error in the test code or in the code under test |
4. How unittest finds tests¶
unittest looks for:
| What | Rule | Example |
|---|---|---|
| File | Usually test_*.py |
test_math_utils.py |
| Class | Inherits from unittest.TestCase |
class TestMathFunctions(unittest.TestCase) |
| Method | Starts with test_ |
def test_add_two_numbers(self): |
If you name a method like this:
unittest will not run it.
This is a common mistake: the test code exists, but the test runner does not see it.
5. Arrange -> Act -> Assert in unittest¶
A poor version:
It is short, but a beginner cannot see the steps.
Better for learning:
| Step | Lines |
|---|---|
| Arrange | a = 2, b = 3 |
| Act | result = add(a, b) |
| Assert | self.assertEqual(result, 5) |
6. The main assert methods¶
| Method | What it checks | Example |
|---|---|---|
assertEqual(a, b) |
a == b |
self.assertEqual(result, 5) |
assertNotEqual(a, b) |
a != b |
self.assertNotEqual(status, "error") |
assertTrue(value) |
The value is truthy | self.assertTrue(user.is_active) |
assertFalse(value) |
The value is falsy | self.assertFalse(form.is_valid()) |
assertIn(a, b) |
a is inside b |
self.assertIn("title", form.errors) |
assertIsNone(value) |
The value is None |
self.assertIsNone(result) |
assertRaises(Error) |
The code must raise an error | with self.assertRaises(ValueError): ... |
An example with assertIn:
def test_error_message_contains_field_name(self):
errors = {"title": ["This field is required."]}
self.assertIn("title", errors)
An example with assertRaises:
def parse_age(value):
age = int(value)
if age < 0:
raise ValueError("age cannot be negative")
return age
class TestParseAge(unittest.TestCase):
def test_negative_age_raises_error(self):
with self.assertRaises(ValueError):
parse_age("-5")
7. setUp(): preparing data before each test¶
If several tests use the same data, you can add setUp().
class TestCart(unittest.TestCase):
def setUp(self):
self.cart = []
def test_cart_starts_empty(self):
self.assertEqual(self.cart, [])
def test_can_add_item_to_cart(self):
self.cart.append("Book")
self.assertIn("Book", self.cart)
setUp() runs before each test.
This matters: each test gets a clean state.
Bad:
cart = []
class TestCart(unittest.TestCase):
def test_add_book(self):
cart.append("Book")
def test_cart_is_empty(self):
self.assertEqual(cart, [])
The second test may fail because the first one left data behind.
8. What a failing test looks like¶
Suppose the test is:
And the function is:
Result:
How to read it:
| Part | Meaning |
|---|---|
-1 |
The actual result |
5 |
The expected result |
AssertionError |
The expectation did not match |
There is no need to panic after this. You need to answer:
- Is the code wrong?
- Is the test wrong?
- Did the expectation change because of a new requirement?
9. Mermaid diagram¶
flowchart TD
A["python -m unittest"] --> B["Find test_*.py"]
B --> C["Find TestCase classes"]
C --> D["Run test_* methods"]
D --> E["Execute assertions"]
E --> F{"Did all expectations match?"}
F -->|yes| G["OK"]
F -->|no| H["Show a failure or an error"]
classDef step fill:#eceff1,stroke:#546e7a,stroke-width:1px;
classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
classDef error fill:#ffebee,stroke:#c62828,stroke-width:3px;
class A,B,C,D,E step;
class F decision;
class G success;
class H error;
10. Common beginner mistakes¶
| Mistake | Why it happens | How to fix it |
|---|---|---|
The method is named without test_ |
The test runner does not see it | Start the name with test_ |
The class does not inherit from unittest.TestCase |
It is just a class, not a test case | Add (unittest.TestCase) |
| One test depends on another | Shared mutable state | Use setUp() |
Writing assert result == 5 in unittest style |
Mixing pytest and unittest | In unittest, prefer self.assertEqual(result, 5) |
| Checking a lot of logic in one method | You want to go faster | One test — one behavior |
11. Practice¶
- Create a file
string_utils.py. - Write the function:
- Create
test_string_utils.py. - Write tests:
- Add a test for an empty string. First decide what should happen: return
""or raise an error.
12. Self-check questions¶
- Why must a test method start with
test_? - What is
unittest.TestCasefor? - How does a
failurediffer from anerror? - When should you use
setUp()? - Why must tests not depend on the order in which they run?