coverwise

Combinatorial test coverage for Python. The coverwise package ships the native C++ CLI plus a Python API that generates, analyzes, and incrementally extends t-wise test suites — including a pytest decorator that replaces a hand-written cross-product with a covering suite.

Installation

pip install coverwise

Supported wheels: Linux x86_64, Linux aarch64, and macOS 14+ Apple Silicon. The package ships a prebuilt executable rather than portable Python code, so other platforms have to build the CLI from source. There are no Python runtime dependencies, and the coverwise command is installed directly.

Quick Start

import coverwise

result = coverwise.generate(
    parameters={
        "os": ["Linux", "macOS", "Windows"],
        "browser": ["Chrome", "Firefox", "Safari"],
    },
    constraints=["IF os = Windows THEN browser != Safari"],
    strength=2,
)

result["coverage"]  # 1
result["tests"]     # [{"os": "Linux", "browser": "Firefox"}, ...]

Every function takes and returns plain dictionaries — the same JSON the CLI reads and writes:

Invalid models and unparsable constraints raise coverwise.CoverwiseError, carrying code, exit_code, and the CLI's stderr.

pytest

coverwise.parametrize runs a test once per generated case, passing each parameter as a same-named argument:

import coverwise

@coverwise.parametrize(
    {
        "os": ["Windows", "macOS", "Linux"],
        "browser": ["Chrome", "Firefox", "Safari"],
        "locale": ["en", "ja"],
    },
    constraints=["IF os = Windows THEN browser != Safari"],
)
def test_login(os, browser, locale):
    assert login(os, browser, locale).ok

The full cross-product is 18 cases; the pairwise suite covers every pair in far fewer. pytest is not a dependency of this package — the decorator only needs it where tests run, and pip install coverwise[pytest] installs both together.

Command Line

coverwise generate input.json > tests.json
coverwise analyze --params input.json --tests tests.json
coverwise extend --existing tests.json input.json > updated.json
coverwise stats input.json

Any input path may be - to read that JSON from standard input. python -m coverwise is equivalent to the installed command, and coverwise --help lists every command with its exit-code contract.

See the Python API reference, the CLI reference, and the full project documentation.

For AI coding agents

coverwise-mcp exposes the same engine as an MCP server, so a coding agent writing tests for a function with several parameters builds a parameter model instead of picking combinations by eye. It installs as a Claude Code plugin and also runs under any MCP client, including Codex CLI, Cursor and Claude Desktop.

License

Apache-2.0