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