Plugin Provided API

Fixture

expected_out

expected_err

This fixture makes it easy to test captured STDOUT and STDERR. To match static output, simply use an assert:

def test_foo(capfd, expected_out, expected_err):
    ...
    stdout, stderr = capfd.readouterr()
    assert expected_out == stdout
    assert expected_stderr == stderr

expected_out.match(output: str) → bool

expected_err.match(output: str) → bool

If the output contains data that changes from run to run (such as timestamps or paths), edit the expectation file to use regular expressions and match it with this function. See Getting Started for more details.

def test_foo(capfd, expected_out, expected_err):
    ...
    stdout, _ = capfd.readouterr()
    assert expected_out.match(stdout) == True

Note

The plugin provides detailed output on assertion failure, but it only works if you explicitly check for True from expected_out.match(…).

expected_yaml: This fixture provides an easy way to verify that YAML output matches the expectations.

Todo

More docs on this!

Marker

expect_suffix(*args: str, suffix: str)

If output may contain system-specific content (e.g., different EOL styles), you can add an arbitrary system-specific suffix to the pattern file so that different variants are stored in separate files. Arguments to the marker are %XX-escaped, dash-concatenated and prefixed with a leading -. They are then used as the {suffix} placeholder of the pm-pattern-file-fmt option.

Usage example:

@pytest.mark.expect_suffix(suffix=platform.system())
def system_specific_test(capfd, expected_out):
    ...
    stdout, _ = capfd.readouterr()
    # Get content from `<base-dir>/.../system_specific_test-Linux.out`
    assert expected_out == stdout

@pytest.mark.expect_suffix(
    f'py{sys.version_info.major}{sys.version_info.minor}'
  , f'pytest{pytest.version_tuple[0]}
  )
def python_specific_test(capfd, expected_out):
    ...
    stdout, _ = capfd.readouterr()
    # Get content from `<base-dir>/.../python_specific_test-py312-pytest8.out`
    assert expected_out == stdout

on_store(*, drop_head: int = 0, drop_tail: int = 0, replace_matched_lines: list[str] = [])

Edit a pattern before save it when --pm-save-patterns option has given.

Parameters:

drop_head – Number of lines to remove from the beginning of the pattern. Removed lines are replaced with a .* placeholder to retain structural compatibility during pattern matching. The number must be a positive integer.
drop_tail – Number of lines to remove from the end of the pattern. The number must be a positive integer.
replace_matched_lines – A list of regular expression strings used to find and replace matching lines within the pattern.