Test helpers

Warning: These helpers are currently an internal concern and changes will not necessarily be reflected in semver.

_pytester_helpers

Helper classes and functions to support testing this plugin with pytester.

CollectionTree

CollectionTree(
    *_,
    node: Item | Collector | _DummyNode,
    children: list[CollectionTree] | None
)

A (top-down) tree of pytest collection Nodes.

Designed to enable testing the results of collection plugins via:

assert CollectionTree.from_items(pytester.genitems([...])) == CollectionTree.from_dict({...})

children instance-attribute

children = children

either:

• if node is pytest.Collector: a list[CollectionTree] of child nodes
• if node is pytest.Item: None

node instance-attribute

node = node

The actual collected node.

_DummyNode

A dummy node for a CollectionTree, used by CollectionTree.from_dict().

Compares equal to a genuine pytest.Node if: - isinstance(Node,_DummyNode.nodetype) - repr(Node) == _DummyNode.name.

parent class-attribute instance-attribute

parent: Self | None = None

Always None but required to avoid attribute errors if type checking Union[pytest.Node,_DummyNode]

__eq__

__eq__(other: Self) -> bool

CollectionTrees are equal if their children and node attributes are equal.

__repr__

__repr__() -> str

Indented, multiline representation of the tree to simplify interpreting test failures.

_walk_up_tree classmethod

_walk_up_tree(branches: list[Self]) -> Self

Walk up the collection tree from a list of branches/leaves until reaching the pytest.Session.

Returns: the Session CollectionTree.

from_dict classmethod

from_dict(
    tree: dict[tuple[str, type], dict | None],
) -> Self

Create a dummy CollectionTree from a dict of dicts with following format:

{(str: name, type: Nodetype):
    (str: name, type: Nodetype): {
        (str: name, type: Nodetype): None,
        (str: name, type: Nodetype): None
        }
    }
}

For example:

tree_dict = {
    ("<Session  exitstatus='<UNSET>' testsfailed=0 testscollected=0>", pytest.Session): {
        ("<Dir tests>", pytest.Dir): {
            ("<Module test_module.py>", pytest.Module): {
                ("<Function test_adder>", pytest.Function): None,
                ("<Function test_globals>", pytest.Function): None,
            },
        },
    },
}
tree = CollectionTree.from_dict(tree_dict)

from_items classmethod

from_items(items: list[Item]) -> Self

Create a single CollectionTree from a list of collected Items.

It is intended that this function is passed the result of pytester.genitems()

Returns: a CollectionTree with the Session as the root.

ExampleDir

ExampleDir(pytester: Pytester, args: list[str])

A directory containing example files and the associated pytester instance.

• pytester: pytest.Pytester
• path: pathlib.Path
• dir_node: pytest.Dir
• items: list[pytest.Item]

ExampleDirSpec

The various elements to set up a pytester instance.

add_ipytest_magic

add_ipytest_magic(source: str) -> str

Add %%ipytest magic to the source code.

example_dir

example_dir(
    request: ExampleDirRequest,
    pytester: Pytester,
    example_dir_cache: dict[ExampleDirSpec, ExampleDir],
) -> ExampleDir

Parameterised fixture. Requires a list of Paths to copy into a pytester instance.

pytest_collection_modifyitems

pytest_collection_modifyitems(
    items: list[Function],
) -> None

xfail on presence of a custom marker: xfail_for(tests:list[str], reasons:list[str]).

pytest_configure

pytest_configure(config: Config) -> None

Register autoskip & xfail_for marks.