From qa-unit-tests-python
Configures and runs Python''''s stdlib doctest - embeds executable test cases in docstrings using `>>>` Python interactive prompt convention; supports `# doctest: +ELLIPSIS` / `+NORMALIZE_WHITESPACE` / `+SKIP` directives; integrates with pytest via `--doctest-modules` flag; runs as `python -m doctest module.py -v`. Use for self-documenting reference implementations + simple smoke-test coverage embedded in API docs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-unit-tests-python:doctest-testsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Per [docs.python.org/3/library/doctest.html][dt-docs]:
Per docs.python.org/3/library/doctest.html:
doctest is Python's stdlib facility for embedding executable
examples in docstrings. The interactive-prompt convention
(>>> ... for input; expected output on the next line) becomes a
test case automatically.
Distinguishing properties:
help()
and Sphinx HTML.For non-trivial test suites, prefer pytest-tests.
Use doctest as a complement (smoke + docs), not replacement.
def sum(a, b):
"""Add two numbers.
>>> sum(1, 2)
3
>>> sum(0, 0)
0
>>> sum(-1, 1)
0
"""
return a + b
Run:
python -m doctest module.py
python -m doctest module.py -v # verbose; show all examples
Pass if the doctest output matches; fail if mismatch.
def fibonacci(n):
"""Compute Fibonacci numbers iteratively.
>>> fibonacci(0)
0
>>> fibonacci(1)
1
>>> fibonacci(10)
55
>>> [fibonacci(n) for n in range(8)]
[0, 1, 1, 2, 3, 5, 8, 13]
"""
if n < 2: return n
a, b = 0, 1
for _ in range(n - 1):
a, b = b, a + b
return b
Per dt-docs:
| Directive | Use |
|---|---|
# doctest: +ELLIPSIS | ... matches arbitrary substrings |
# doctest: +NORMALIZE_WHITESPACE | Collapse whitespace before compare |
# doctest: +SKIP | Skip this example |
# doctest: +IGNORE_EXCEPTION_DETAIL | Ignore exception message detail (just match exception type) |
# doctest: +DONT_ACCEPT_TRUE_FOR_1 | Strict bool != int comparison |
# doctest: -ELLIPSIS | Disable a directive |
Examples:
def list_users():
"""Return user records.
>>> list_users() # doctest: +ELLIPSIS
[{'id': 1, 'name': 'Alice', 'created_at': ...}, ...]
>>> list_users() # doctest: +NORMALIZE_WHITESPACE
[{'id': 1, 'name': 'Alice'}]
"""
return [...]
def buggy_function():
"""Raise an error.
>>> buggy_function() # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
ValueError
"""
raise ValueError("specific message that may change")
def divide(a, b):
"""Divide a by b.
>>> divide(10, 2)
5.0
>>> divide(10, 0)
Traceback (most recent call last):
...
ZeroDivisionError: division by zero
"""
return a / b
The Traceback... + ... ellipsis + exception line pattern is
specific to doctest expected-error format.
pip install pytest
pytest --doctest-modules src/
Per pytest docs, --doctest-modules collects doctests from all
modules in the source tree. Combine with regular pytest:
pytest --doctest-modules tests/
Both regular tests + doctests run in one pass.
In pyproject.toml:
[tool.pytest.ini_options]
addopts = "--doctest-modules"
sphinx.ext.doctest runs doctests during Sphinx HTML build:
# docs/conf.py
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
doctest_global_setup = """
import mymodule
"""
sphinx-build -b doctest docs/ build/doctest/
This catches docs that drift from the implementation - examples in RST/MD docs are also doctest-runnable.
doctest is not for:
coverage run -m doctest but
rougher than pytest-cov)For those, use pytest-tests.
- run: pip install pytest
- run: pytest --doctest-modules src/
# Or stdlib-only:
- run: python -m doctest src/*.py -v
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Use doctest for complex logic | Docstrings become unreadable | Use pytest for non-trivial tests; doctest for examples |
| Show non-deterministic output (timestamps) without ELLIPSIS | Test fails on every run | Use +ELLIPSIS directive (Step 3) |
| Show dict output in older Python (pre-3.7) | Order varies; fails | Sort first or use Python 3.7+ insertion-order dict |
Forget Traceback (most recent call last): pattern | Exception expectation doesn't match | Follow exact format (Step 4) |
| Skip Sphinx integration for documented examples | Docs drift from impl | sphinx.ext.doctest (Step 6) |
>>>).pytest-tests,
unittest-tests,
nose2-tests - sister toolstest-code-conventions - test code hygienenpx claudepluginhub testland/qa --plugin qa-unit-tests-pythonProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.