zope.testrunner

8.2 verified Mon Apr 27 auth: no python maintenance

Zope test runner script for running Python unit tests with support for layers, test fixtures, and flexible reporting. Current version is 8.2, compatible with Python >=3.10. Released under the Zope Foundation, maintenance mode with occasional updates.

pip install zope.testrunner

Common errors

error ImportError: cannot import name 'Runner' from 'zope.testrunner' ↓

cause Incorrect import path; Runner moved to zope.testrunner.runner in version 5.0.

fix

Use from zope.testrunner.runner import Runner

error AttributeError: module 'zope.testrunner' has no attribute 'TestRunner' ↓

cause TestRunner was removed in version 5.0.

fix

Replace TestRunner with Runner from zope.testrunner.runner.

error zope.testrunner.runner.RunnerError: No tests found ↓

cause The test path or pattern did not match any test files.

fix

Check that test_path points to a directory with test files matching tests_pattern. Use --all to include all files.

error TypeError: 'NoneType' object is not callable (when using layers) ↓

cause A test layer's `setUp` or `tearDown` method is not defined or not found.

fix

Ensure all layer classes implement setUp(self) and tearDown(self) methods.

Warnings

breaking In version 5.0, the Runner class moved from `zope.testrunner` to `zope.testrunner.runner`. Code importing `TestRunner` or using old import path `from zope.testrunner import Runner` will break. ↓

fix Change imports to `from zope.testrunner.runner import Runner` and use the new API.

deprecated The command-line option `--test-path` is deprecated in favor of positional arguments. Usage like `zope-testrunner --test-path .` will produce a warning. ↓

fix Use positional arguments instead: `zope-testrunner .`

gotcha Test layers from `zope.testing` are not automatically discovered; they must be explicitly listed or imported. Many users assume layers are auto-detected. ↓

fix Ensure layers are imported in the test module or listed via `--layer` option.

gotcha When running tests programmatically, the `Options` class is not exported. Use a simple object or dict, not the undocumented `Options` class. ↓

fix Create a plain object with required attributes as shown in quickstart.

Imports

TestRunner

wrong

from zope.testrunner import TestRunner

correct

from zope.testrunner.runner import Runner

TestRunner was removed in version 5.0; use Runner instead.

Quickstart

Basic example to run tests programmatically.

import sys
from zope.testrunner.runner import Runner

class CustomOptions:
    verbose = 2
    tests_pattern = 'test*.py'
    test_path = ['.']
    at_level = None
    unit = True
    layer = None
    all = False
    repeat = 0
    test_filter = None
    report_modules = False
    module_path = []
    startup = None

runner = Runner(CustomOptions())
runner.run()

# To run tests from command line:
# $ python -m zope.testrunner --test-path .