testscenarios

library0.6.2pypypiunverified

Testscenarios is a Python library that extends `unittest` to provide clean dependency injection, enabling a single test method to be run with multiple scenarios. This is particularly useful for interface testing (testing many implementations via a single test suite) or for classic dependency injection, where test dependencies are provided externally. The library is currently at version 0.5.0, offering a stable approach to scenario-based testing.

testing

pip install testscenarios

github ↗package ↗

INSTALL

IMPORT

SIG · TESTSCENARIOS

testscenarios

testingpythonv0.6.2

Install

1.7s avg

Import

296ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.066s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.053s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TestWithScenarios

✓ from testscenarios import TestWithScenarios

✗ from testscenarios import TestWithScenarios

This quickstart demonstrates defining multiple scenarios directly within a `unittest.TestCase` by inheriting from `TestWithScenarios`. Each scenario is a tuple containing a descriptive name and a dictionary of parameters. These parameters are injected as instance attributes into the test method when executed, allowing the same test logic to run with different data sets. To run, save as a Python file and execute with `python -m unittest your_test_file.py`.

import unittest from testscenarios import TestWithScenarios class MyScenarioTest(TestWithScenarios, unittest.TestCase): # Define scenarios as a list of (name, dictionary_of_parameters) tuples scenarios = [ ('addition_scenario', dict(num1=5, num2=3, expected_sum=8)), ('subtraction_scenario', dict(num1=10, num2=4, expected_difference=6)), ('multiplication_scenario', dict(num1=2, num2=6, expected_product=12)) ] def test_addition(self): """Test addition operation using scenario parameters.""" # Parameters from the current scenario are automatically available as instance attributes actual_sum = self.num1 + self.num2 self.assertEqual(actual_sum, self.expected_sum) def test_subtraction(self): """Test subtraction operation using scenario parameters.""" actual_difference = self.num1 - self.num2 self.assertEqual(actual_difference, self.expected_difference) def test_multiplication(self): """Test multiplication operation using scenario parameters.""" actual_product = self.num1 * self.num2 self.assertEqual(actual_product, self.expected_product) if __name__ == '__main__': unittest.main()

Debug

Known issues

gotchaWhen using `TestWithScenarios` as a mixin, it must be the first class in the MRO (Method Resolution Order) of your `unittest.TestCase` subclass. Additionally, you must not override the `run()` or `__call__()` methods in your test class, as `TestWithScenarios` relies on these to generate and execute tests for each scenario.

fix

Ensure `TestWithScenarios` is the leftmost base class (e.g., `class MyTest(TestWithScenarios, unittest.TestCase):`). Avoid overriding `run()` or `__call__()` in your test classes.

affects: All versions

gotchaIf using `per_module_scenarios` for dependency injection, ensure all access to the module under test goes through the attribute set by the scenario on the test object (e.g., `self.my_module`). Directly importing the module within the test file will bypass the scenario's injected dependency, potentially leading to incorrect test results or unexpected behavior.

fix

Always access the scenario-provided module/dependency via `self.attribute_name` within your test methods, where `attribute_name` is defined in your scenario dictionary.

affects: All versions

gotchaModifying the `scenarios` attribute dynamically after a test has been loaded but before it runs can lead to unexpected behavior if not handled carefully. Multiple tests might share a single `scenarios` attribute, so altering it for one test could unintentionally affect others.

fix

If dynamic scenario generation is needed, ensure that scenarios are uniquely generated or cloned per test object if there's a risk of shared state, or use the `load_tests` hook (e.g., `load_tests_apply_scenarios`) which explicitly handles scenario generation before tests are added to the suite.

affects: All versions

gotchaThe GitHub repository indicates support for Python 3.10 and newer, while the PyPI `requires_python` metadata is `None`. Using `testscenarios` with Python versions older than 3.10 may lead to compatibility issues or unexpected behavior.

fix

Ensure your project runs on Python 3.10 or a newer compatible version.

affects: < 3.10

Upgrade

Version history

0.6.2latest on PyPI · released May 22, 2026

Audit

Dependencies

testtoolsrequiredUsed for additional testing utilities, though testscenarios can be used with standard unittest.TestCase.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/testing-cabal/testscenarios ↗

packagehttps://pypi.org/project/testscenarios/ ↗