Function assert_node

sphinx/testing/util.py:30–74

(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any)

def assert_node(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any) -> None:
    if cls:
        if isinstance(cls, list):
            assert_node(node, cls[0], xpath=xpath, **kwargs)
            if cls[1:]:
                if isinstance(cls[1], tuple):
                    assert_node(node, cls[1], xpath=xpath, **kwargs)
                else:
                    assert (
                        isinstance(node, nodes.Element)
                    ), f'The node{xpath} does not have any children'  # fmt: skip
                    assert len(node) == 1, (
                        f'The node{xpath} has {len(node)} child nodes, not one'
                    )
                    assert_node(node[0], cls[1:], xpath=xpath + '[0]', **kwargs)
        elif isinstance(cls, tuple):
            assert (
                isinstance(node, (list, nodes.Element))
            ), f'The node{xpath} does not have any items'  # fmt: skip
            assert (
                len(node) == len(cls)
            ), f'The node{xpath} has {len(node)} child nodes, not {len(cls)!r}'  # fmt: skip
            for i, nodecls in enumerate(cls):
                path = xpath + f'[{i}]'
                assert_node(node[i], nodecls, xpath=path, **kwargs)
        elif isinstance(cls, str):
            assert node == cls, f'The node {xpath!r} is not {cls!r}: {node!r}'
        else:
            assert (
                isinstance(node, cls)
            ), f'The node{xpath} is not subclass of {cls!r}: {node!r}'  # fmt: skip

    if kwargs:
        assert (
            isinstance(node, nodes.Element)
        ), f'The node{xpath} does not have any attributes'  # fmt: skip

        for key, value in kwargs.items():
            if key not in node:
                if (key := key.replace('_', '-')) not in node:
                    msg = f'The node{xpath} does not have {key!r} attribute: {node!r}'
                    raise AssertionError(msg)
            assert node[key] == value, (
                f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
            )


# keep this to restrict the API usage and to have a correct return type