---
id: testscenarios
version: "0.6.2"
license: Apache-2.0 OR BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# testscenarios — Testscenarios, a unittest extension for dependency injection

License: permissive · Maintenance: active · Downloads: 443.0K/mo

## 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 above — 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

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

- License: Apache-2.0 OR BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 443.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

unittest parameterization, test scenario injection, interface testing multiple implementations, dependency injection testing, dynamic test generation, unittest test multiplication, scenario-based testing, unittest-extension, parameterization, interface-testing

[View on SkillFed](https://skillfed.io/packages/testscenarios) · [View on PyPI](https://pypi.org/project/testscenarios/)