computer-playbook/docs/contributing/code/tests/unit.md

# Unit Tests

This page is the SPOT for unit testing requirements, framework, and structure.
Run unit tests with `make test-unit`.

## Framework

- You MUST use Python `unittest` as the test framework.
- Tests MUST live under `tests/unit/`.
- Mirror the source tree: a file at `plugins/lookup/service.py` gets its tests at `tests/unit/plugins/lookup/test_service.py`.

## Requirements

- You MUST add or update unit tests for every `*.py` file you touch.
- Each test MUST cover one isolated behavior. Do not test multiple concerns in a single test method.
- You MUST NOT write tests that only assert a file contains a string.
- You MUST NOT write tests for non-executable files such as `.yml` or `.j2`. Test the code that consumes them instead.
- You SHOULD name test methods after the behavior they verify, not the function name alone (e.g. `test_needed_false_when_disabled`).
- You SHOULD cover edge cases — empty inputs, missing keys, boundary values — not only the happy path.
- You MAY use `unittest.mock` to isolate the unit under test from Ansible internals or external state.

## How to Create

1. Identify the module under test (e.g. `plugins/lookup/service.py`).
2. Create the matching test file under `tests/unit/` if it does not exist.
3. Subclass `unittest.TestCase`.
4. Write one method per behavior. Build hypotheses before writing assertions.
5. Run `make test-unit` and verify all tests pass.

## Running Specific Tests

Use `TEST_PATTERN` to scope the test run to a single file or a glob:

```bash
# Run a single test file
TEST_PATTERN=test_my_module.py make test-unit

# Run all files matching a prefix
TEST_PATTERN=test_applications*.py make test-unit
```