testscenarios

What it is and what it does

testscenarios is a unittest extension that enables clean dependency injection and parameterization of tests through scenarios. A scenario is a named tuple pairing a string identifier with a dictionary of parameters; the package multiplies a single test method across all scenarios, cloning the test and injecting each scenario's parameters as attributes on the test instance.

The package addresses a key limitation of unittest: running the same test logic against multiple implementations or configurations without creating brittle mixin-based subclasses. It supports three integration patterns: subclassing TestWithScenarios (most robust, works with any unittest-compliant runner), manual generation via generate_scenarios(), or hooking into test loader conventions like load_tests. Scenarios can be static class attributes or dynamically generated at runtime, and can be composed across multiple dimensions to create cross-product test expansion.

Use it for:

• Testing multiple implementations of the same interface by defining scenarios for each backend or provider.
• Running the same test suite against different configurations (e.g., database engines, network transports) without code duplication.
• Plugin systems where a plugin needs to run standard interface tests against its own implementation.
• Dependency injection: providing tests with externally-configured objects or settings to test behavior in different contexts.
• Generating test variants dynamically based on available libraries or registry entries at test load time.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

testscenarios extends Python's unittest to run a single test method across multiple scenarios by injecting parameters as test attributes, enabling interface testing and dependency injection patterns.

Yes. testscenarios is a mature, actively maintained library with no security vulnerabilities, low install friction, and permissive dual licensing. It solves a genuine unittest limitation for interface and parameterized testing. Install if you need to run the same test logic across multiple scenarios or implementations without creating brittle subclass hierarchies.

Install

testscenarios on PyPI

pip install testscenarios

uv add testscenarios

poetry add testscenarios

Installing testscenarios

Before you install

Low install friction with a pure-Python wheel. Actively maintained as of 2026-05-22 with recent activity. Requires Python 3.10 or later and has no runtime dependencies.

License in practice

Dual-licensed under Apache-2.0 or BSD-3-Clause (permissive). You may choose either license when using or redistributing the package.

Quickstart

import unittest
from testscenarios import TestWithScenarios

class MyTest(TestWithScenarios):
    scenarios = [
        ('scenario1', {'param': 1}),
        ('scenario2', {'param': 2}),
    ]
    def test_example(self):
        self.assertEqual(self.param, self.param)

Requires Python 3.10 or later. If subclassing TestWithScenarios, it must be first in the MRO and you cannot override run() or __call__().

Verify before relying

• Whether the package works with test runners beyond unittest (e.g., pytest, nose) without additional configuration.
• Performance characteristics when generating large numbers of scenarios dynamically.

Package facts

Evidence: testscenarios-0.6.2-py3-none-any.whl

Tags

More Testing packages