pytest_robotframework.hooks

 1# ideally this would be in _internal.pytest so this would go without saying, but i can't figure out
 2# any other way to get this module to show up in pdoc
 3"""new hooks defined by the pytest_robotframework plugin. these are not to be imported. see
 4[the documentation for pytest hook functions](https://docs.pytest.org/en/7.1.x/how-to/writing_hook_functions.html)
 5for information on how to use them."""
 6
 7from __future__ import annotations
 8
 9from typing import TYPE_CHECKING
10
11from pytest import Item, hookspec
12
13if TYPE_CHECKING:
14    from pytest import Session
15
16    from pytest_robotframework._internal.robot.utils import RobotOptions
17
18# these are basically abstract methods, but hooks are defined in this wacky way which isn't
19# supported by linters/type checkers:
20
21# https://github.com/pytest-dev/pytest/issues/11300
22# pyright:reportReturnType=false
23# https://github.com/astral-sh/ruff/issues/7286
24# https://github.com/astral-sh/ruff/issues/9803
25# ruff: noqa: ARG001, FBT001, PLR0917
26
27
28@hookspec
29def pytest_robot_modify_options(options: RobotOptions, session: Session) -> None:
30    """modify the arguments passed to robot in-place
31
32    :param options: the arguments to be passed to robot in dict format. for example,
33    `{"listener": ["Foo", "Bar"]}`means `--listener Foo --listener Bar`). you can also specify
34    instances of classes to `listener` and `prerebotmodifier`
35    :param session: the pytest `Session` object
36
37    example:
38    -------
39    >>> def pytest_robot_modify_options(options: RobotOptions, session: Session) -> None:
40    ... if not session.config.option.collectonly:
41    ...     options["loglevel"] = "DEBUG:INFO"
42    ...     options["listener"].append(Foo())
43    """
44
45
46@hookspec
47def pytest_robot_assertion(
48    item: Item,
49    expression: str,
50    fail_message: object,
51    line_number: int,
52    assertion_error: AssertionError | None,
53    explanation: str,
54) -> None:
55    """gets called when an assertion runs. unlike `pytest_assertrepr_compare` and
56    `pytest_assertion_pass`, this hook is executed on both passing and failing assertions, and
57    allows you to see the second argument passed to `assert` statement
58
59    requires the `enable_assertion_pass_hook` pytest option to be enabled
60
61    :param item:
62        the currently running item
63    :param expression:
64        a string containing the the source code of the expression passed to the `assert` statement
65    :param fail_message:
66        the second argument to the `assert` statement, or `None` if there was none provided
67    :param line_number:
68        the line number containing the `assert` statement
69    :param assertion_error:
70        the exception raised if the `assert` statement failed. `None` if the assertion passed.
71        you must re-raise the assertion error for the assertion to fail (useful if you want to
72        conditionally ignore an assertion error)
73    :param explanation:
74        pytest's explanation of the result. the format will be different depending on whether the
75        assertion passed or failed
76
77    warning:
78    -------
79    this hook is experimental and relies heavily on patching the internals of pytest. it may break,
80    change or be removed at any time. you should only use this hook if you know what you're doing
81    """