Skip to content

livery.extensions.pytest._steps

livery.extensions.pytest._steps

pytest's two steps: each python package's suite, and its documentation examples.

The extension's extension.toml declares both and names the bodies here. Each step asks the python extension, through livery.workshop.answer, for the function that runs what it judges: the answer to python.test.runner runs several packages' suites in one call, and the answer to python.examples.runner one package's examples. The python extension answers both while a package holds it. With no answer the test step runs nothing and the examples step skips each package, and each says why.

test.pytest narrows by packages: the workshop names the members a run reaches (livery.workshop.scoped_packages), and their suites run in one call, with the workspace's own tests beside them while the root's set holds python (livery.workshop.scoped_suite), measured while this extension contributes its [for.coverage] table (livery.workshop.contributions_for). A member whose suite is not worker-safe sets the step's parallel option to false and runs in a call of its own, under -n 0. examples.pytest runs each member's documentation examples. Each step hands pytest the words after -- on its own verb (fm test.pytest -- -k name).

On a sharded check leg test.pytest runs on every shard, each over its share of the test files (livery.extensions.pytest._slice): the files of every suite the run reaches, packed into the shard's slices by the platform leg's durations, handed to the runner as the selection it already takes, and recorded for the gate job's proof. A run that is one shard of one hands the runner the suites whole.

Functions:

Name Description
judge_test

Run the suites of the packages the run reaches, and the workspace's own tests.

judge_examples

Run the documentation examples of each package the run reaches.

Attributes:

Name Type Description
NAME
MEASURED_FOR
TEST
EXAMPLES
SUITE_RUNNER Query[Callable[..., None] | None]
EXAMPLES_RUNNER Query[Callable[[Package, Path, tuple[str, ...], tuple[str, ...]], None] | None]

NAME module-attribute

NAME = 'pytest'

MEASURED_FOR module-attribute

MEASURED_FOR = 'coverage'

TEST module-attribute

TEST = 'test.pytest'

EXAMPLES module-attribute

EXAMPLES = 'examples.pytest'

SUITE_RUNNER module-attribute

SUITE_RUNNER: Query[Callable[..., None] | None] = Query('python.test.runner')

EXAMPLES_RUNNER module-attribute

EXAMPLES_RUNNER: Query[Callable[[Package, Path, tuple[str, ...], tuple[str, ...]], None] | None] = Query('python.examples.runner')

judge_test

judge_test(ctx: PhaseContext) -> None

Run the suites of the packages the run reaches, and the workspace's own tests.

The workspace's own tests run while the root's set holds python, and a line says why when it does not. The suites run measured while coverage is listed and this extension's listing contributes its [for.coverage] table, and with no meter otherwise. While nothing answers python.test.runner, nothing runs, and the step says why. On a shard of a sharded check leg each suite runs its share of its test files (livery.extensions.pytest._slice.share); a suite with no file in the share is left out of the call, and a call with no suite does not start.

Source code in packages/extensions/pytest/src/livery/extensions/pytest/_steps.py
def judge_test(ctx: PhaseContext) -> None:
    """Run the suites of the packages the run reaches, and the workspace's own tests.

    The workspace's own tests run while the root's set holds python,
    and a line says why when it does not. The suites run measured
    while coverage is listed and this extension's listing contributes
    its ``[for.coverage]`` table, and with no meter otherwise. While
    nothing answers ``python.test.runner``, nothing runs, and the step
    says why. On a shard of a sharded check leg each suite runs its
    share of its test files ([livery.extensions.pytest._slice.share][]);
    a suite with no file in the share is left out of the call, and a
    call with no suite does not start.
    """
    # A package whose examples alone changed runs them, not its suite.
    members = tuple(
        package
        for package in scoped_packages(ctx, TEST)
        if package.path not in ctx.examples
    )
    # The workspace's own tests reach any package, so every run that
    # judges them runs them.
    unit = scoped_suite(ctx, TEST)
    suites = (*members, unit) if unit is not None else members
    if not suites:
        print(f"  {TEST}: no python package and no workspace tests to run")
        return
    run = answer(ctx.root, SUITE_RUNNER)
    if run is None:
        print(
            f"  {TEST}: runs nothing; nothing answers {SUITE_RUNNER.name}, which"
            " the python extension answers while the root's set or a package's"
            " holds python"
        )
        return
    # A suite that is not worker-safe runs in a call of its own under
    # -n 0, after the words from the verb, so they cannot undo it. Each
    # call collects the packages it is handed and no other.
    serial = tuple(p for p in members if not step_option(TEST, p, "parallel"))
    parallel = tuple(p for p in suites if p not in serial)
    measured = NAME in contributions_for(MEASURED_FOR, ctx.root)
    # One shard of one runs the suites whole, as the run selects them;
    # a shard of several runs its share, and a suite whose share is
    # empty is left out of the call, since a package handed over with
    # no selection collects its whole directory.
    chosen = share(ctx, suites, step=TEST) if ctx.shard.count > 1 else None
    for group, extra in ((parallel, ()), (serial, ("-n", "0"))):
        packages, selection = group, ctx.tests
        if chosen is not None:
            packages = tuple(p for p in group if chosen[p.path])
            selection = {p.path: chosen[p.path] for p in packages}
        if packages:
            run(
                *ctx.arguments,
                *extra,
                packages=packages,
                root=ctx.root,
                selection=selection,
                point=ctx.point,
                measured=measured,
            )

judge_examples

judge_examples(ctx: PhaseContext) -> None

Run the documentation examples of each package the run reaches.

While nothing answers python.examples.runner, each package skips, named.

Source code in packages/extensions/pytest/src/livery/extensions/pytest/_steps.py
def judge_examples(ctx: PhaseContext) -> None:
    """Run the documentation examples of each package the run reaches.

    While nothing answers ``python.examples.runner``, each package
    skips, named.
    """
    packages = tuple(
        package
        for package in scoped_packages(ctx, EXAMPLES)
        # Its tests alone changed: the examples did not move.
        if not (
            ctx.scoped
            and package.path in ctx.tests
            and package.path not in ctx.examples
        )
    )
    if not packages:
        return
    run = answer(ctx.root, EXAMPLES_RUNNER)
    for package in packages:
        if run is None:
            print(
                f"  examples: {package.path} skips (nothing answers"
                f" {EXAMPLES_RUNNER.name})"
            )
            continue
        # Only a run over named files narrows the examples; a whole walk
        # runs the package's directory.
        named = (
            tuple(str(path) for path in scoped_files(ctx, EXAMPLES, package))
            if ctx.files
            else ()
        )
        run(package, ctx.root, named, ctx.arguments)