Format of return result of pytest_report_teststatus hook function

[Northxw]

  I implemented the pytest_report_teststatus hook method in the conftest.py file, but when I formulated the return value in combination with the official pytest documentation, I had a doubt.

1. Here is the return value example from the official documentation [https://docs.pytest.org/en/latest/reference/reference.html#_pytest.hookspec.pytest_report_teststatus]：

"rerun", "R", ("RERUN", {"yellow": True})

2. The following code is completed by me referring to the official documentation：

import pytest

@pytest.hookimpl
def pytest_report_teststatus(report, config):
    if report.when == 'call' and report.passed:
        return report.outcome, 'T', ("😀", {"yellow": True})
    if report.when == 'call' and report.failed:
        return report.outcome, 'E', "😔"

  So, my doubt is where can I know the format of the detailed words, for example, I can write it like this report.outcome, 'T', ("😀", {"yellow": True}), or I can write it like this report.outcome, 'T', "😀".

  Or, where can I learn about the resulting format of verbose word，Such as ("😀", {"yellow": True}) and "😀".

  This is a small and detailed question, but I'm looking forward to an answer, thanks a lot!

[portyu9]

Hi @Northxw

Both forms are valid.

The return value of pytest_report_teststatus is:

(category, shortletter, verbose)

and the third value can currently be either:

"PASSED"

or:

("PASSED", {"green": True})

The difference is styling.

A plain string lets pytest apply its normal/default styling:

@pytest.hookimpl
def pytest_report_teststatus(report, config):
    if report.when == "call" and report.passed:
        return "passed", "T", "😀"

If you want to explicitly control terminal markup, return:

@pytest.hookimpl
def pytest_report_teststatus(report, config):
    if report.when == "call" and report.passed:
        return "passed", "T", ("😀", {"green": True})

    if report.when == "call" and report.failed:
        return "failed", "E", ("😔", {"red": True, "bold": True})

So this:

("😀", {"yellow": True})

means:

• verbose text: 😀
• terminal styling: yellow

while:

"😀"

is simply the verbose text without an explicit markup override.

Current pytest defines the hook type as essentially:

tuple[
    str,
    str,
    str | tuple[str, Mapping[str, bool]]
]

The supported terminal markup includes options such as:

black, red, green, yellow, blue, purple, cyan, white,
bold, light, blink, invert

So your two examples are both correct; use the tuple form only when you need explicit styling.

Please mark this answer as accepted if it helped, thank you.