Karva

Install the optional integration with pip install sybil-extras[karva]. The generate_karva_tests function converts a module-level Sybil configuration into Python modules that Karva can collect. Run generation from your project root and place the generated directory inside that project so its conftest.py fixtures apply.

Export your existing Sybil instance as sybil from an importable module, such as conftest.py. Keep pytest_collect_file = sybil.pytest() while validating the migration. Use explicit source paths to avoid including virtual environments or generated files in documentation discovery.

"""Generate native Karva modules for the README examples."""

from pathlib import Path
from tempfile import TemporaryDirectory

from sybil_extras.integrations.karva import generate_karva_tests

with TemporaryDirectory(dir=".", prefix="karva_sybil_") as directory:
    _ = generate_karva_tests(
        reference="conftest:sybil",
        paths=[Path("README.rst")],
        destination=Path(directory),
    )

While that directory exists, run karva test <directory> from the project root. A script can invoke Karva as a subprocess before leaving the context manager. Install Karva in the environment used by that script.

Each matching document becomes one native test module with dynamically parametrized examples. Karva runs those examples in source order in one worker, with a shared document namespace and one setup and teardown per document. Function fixtures are injected anew for each example, and module fixtures are scoped to the document. Karva alpha 13 handles Sybil’s standard-library SkipTest exceptions as native skips. Failures are reported individually, subsequent examples continue, and document teardown runs after failures.

reference accepts a Sybil or a SybilCollection. Collection members must select disjoint files. Overlapping configurations are rejected because separate generated modules would change the lifetime of module fixtures for the same source file. Fixture names must be Python identifiers and must not be _sybil_example or _sybil_document. The output directory must be empty, and generation never overwrites its files.

The example identifier includes its original path, line, and column. Karva’s primary diagnostic still points to the generated test function. Native source locations are tracked in Karva issue 1513. Temporary module paths prevent useful reuse of Karva’s test history across runs, while selecting only a later example omits the namespace established by earlier examples. Retries can also repeat namespace mutations. Use full document runs without retries during this pilot. A native Sybil.karva() integration is tracked in Sybil issue 173.