Writing and Running Tests

🧪 This guide explains how to write and run tests using pytest, following the structure used in the template-project.

Writing good tests helps you avoid bugs, refactor safely, and ensure your code does what you expect — even weeks or months later.

📁 Where Tests Go

All test code lives in the tests/ directory at the root of the project.

Each Python file in this folder starts with test_
Each test function inside starts with test_
You can organize tests by topic or module: test_utils.py, test_readers.py, etc.

✍️ Writing Your First Test

Tests are written as plain Python functions and typically use assertions to check behavior:

# tests/test_math.py

def test_addition():
    assert 1 + 1 == 2

To test your own project modules, just import them like normal:

# tests/test_tools.py
from template_project.tools import convert_units

def test_convert_units_basic():
    result = convert_units(10, "m", "km")
    assert result == 0.01

💡 All test functions must start with test_ so pytest can discover them.

▶️ Running Tests Locally

Make sure you’ve installed the dev dependencies:

pip install -r requirements-dev.txt

Then run:

pytest

This will automatically find and run any test_*.py files under the tests/ folder.

To run a specific test file:

pytest tests/test_tools.py

To run a specific test function:

pytest tests/test_tools.py::test_convert_units_basic

🛠 Recommended Conventions

Group related tests by file (e.g. test_utilities.py, test_standardise.py)
Name test functions to reflect what they check (e.g. test_raises_on_invalid_units)
Use fixtures or test classes to share setup code when needed
Keep each test focused on one thing

📊 Checking Test Coverage

You can use pytest-cov to measure how much of your code is covered by tests.

1. Install the extra dev dependency:

Make sure this line is in your requirements-dev.txt:

pytest-cov

Then install:

pip install -r requirements-dev.txt

2. Run tests with coverage:

pytest --cov=template_project

This will show a summary of test coverage by file.

To generate an HTML report:

pytest --cov=template_project --cov-report=html

Then open the htmlcov/index.html file in your browser to view a coverage dashboard.

📉 Files with low coverage help you find missing tests.

If you’re using pre-commit hooks, you can configure them to run pytest before each commit. This helps you catch test failures early.

Summary Cheatsheet

Task	Command
Run all tests	`pytest`
Run specific test file	`pytest tests/test_xyz.py`
Run specific test	`pytest tests/test_xyz.py::test_name`
Install test tools	`pip install -r requirements-dev.txt`

✅ Tests help you make confident changes. Use them early, and use them often!