show_fixtures_per_test.py

Overview

This file contains a suite of **pytest tests** designed to validate the behavior of the `--fixtures-per-test` pytest command-line option. The `--fixtures-per-test` option, when used, displays which fixtures are used by each test function during a pytest run, including information about fixture origins and docstrings.

The tests in this file use the `Pytester` testing utility provided by pytest itself (`_pytest.pytester.Pytester`) to programmatically create test modules and conftest files, run pytest with the `--fixtures-per-test` option, and verify the expected output.

In essence, this file ensures that pytest’s fixtures-per-test reporting feature works correctly under various scenarios, such as:

• No fixtures used by tests

• Fixtures defined in test modules or in conftest.py files

• Fixtures with dependencies on other fixtures

• Private fixtures (names starting with underscore)

• Fixtures with multiline docstrings

• Integration with doctest items

• Verbose mode output including fixture source locations

Detailed Explanation of Functions

This file does not define any classes; it only defines standalone test functions. Each test function accepts a single parameter:

• pytester: Pytester — a pytest fixture that provides an isolated pytest environment for creating files, running pytest, and capturing results.

1. test_no_items_should_not_show_output(pytester: Pytester) -> None

• Purpose:
  Verifies that when no tests use fixtures, the --fixtures-per-test option does not output any fixture usage lines.

• Parameters:

  • pytester: a Pytester instance.

• Returns:

  • None.

• Behavior:
  Runs pytest with --fixtures-per-test in an empty test directory and asserts:

  • No line containing "fixtures used by" appears in the output.

  • The pytest process exits with code 0.

• Usage Example:

  def test_no_items_should_not_show_output(pytester: Pytester) -> None:
      result = pytester.runpytest("--fixtures-per-test")
      result.stdout.no_fnmatch_line("*fixtures used by*")
      assert result.ret == 0
  

2. test_fixtures_in_module(pytester: Pytester) -> None

• Purpose:
  Tests that fixtures declared inside a test module are correctly reported by --fixtures-per-test.

• Parameters:

  • pytester: a Pytester instance.

• Implementation Details:
  Creates a test module with two fixtures:

  • _arg0 (private, should be hidden)

  • arg1 (public, with a docstring)

  A test function `test_arg1` uses `arg1`.

• Assertions:

  • Output contains "fixtures used by test_arg1" and the location of the test.

  • arg1 fixture is listed with its docstring.

  • _arg0 fixture is not listed (private fixtures are hidden by default).

• Usage Example:
  See function code above.

3. test_fixtures_in_conftest(pytester: Pytester) -> None

• Purpose:
  Validates that fixtures defined in conftest.py files are correctly reported as used by tests.

• Implementation Details:

  • Creates a conftest.py with fixtures arg1, arg2, and arg3 (where arg3 depends on arg1 and arg2).

  • Creates a test module with two tests using arg2 and arg3 respectively.

  • Runs pytest with --fixtures-per-test and asserts that fixtures and their docstrings appear correctly with their source location (conftest.py lines).

4. test_should_show_fixtures_used_by_test(pytester: Pytester) -> None

• Purpose:
  Ensures that when fixtures with the same name are defined in both conftest.py and the test module, the test module’s fixture takes precedence in the output.

• Implementation Details:

  • conftest.py defines arg1 and arg2.

  • Test module defines its own arg1 fixture and a test using arg1 and arg2.

  • Verifies output shows arg1 from the test module and arg2 from conftest.py.

5. test_verbose_include_private_fixtures_and_loc(pytester: Pytester) -> None

• Purpose:
  Tests that in verbose mode (-v), private fixtures (with underscore prefix) and fixture source locations are included in the output.

• Implementation Details:

  • conftest.py defines _arg1 (private) and arg2 (which depends on _arg1).

  • Test module defines arg3.

  • Test function uses arg2 and arg3.

  • Runs pytest with --fixtures-per-test -v.

  • Verifies output includes _arg1, arg2, and arg3 with full docstrings and file locations.

6. test_doctest_items(pytester: Pytester) -> None

• Purpose:
  Verifies that doctest items (both in Python docstrings and text files) are collected and processed correctly with --fixtures-per-test.

• Implementation Details:

  • Creates a Python file with a function containing a doctest.

  • Creates a separate .txt file containing a doctest.

  • Runs pytest with --fixtures-per-test, --doctest-modules, and --doctest-glob=*.txt.

  • Asserts pytest collects 2 items with exit code 0.

7. test_multiline_docstring_in_module(pytester: Pytester) -> None

• Purpose:
  Checks that fixtures with multiline docstrings are partially displayed correctly (only the first paragraph) when --fixtures-per-test is used.

• Implementation Details:

  • Test module fixture has a multiline docstring with several paragraphs.

  • Test function uses the fixture.

  • Output is inspected to confirm the first paragraph of the docstring is displayed.

8. test_verbose_include_multiline_docstring(pytester: Pytester) -> None

• Purpose:
  Similar to the previous test but verifies that in verbose mode (-v), the full multiline docstring (all paragraphs) of a fixture is displayed.

• Implementation:

  • Same fixture as previous test.

  • Runs pytest with --fixtures-per-test -v.

  • Output assertions ensure entire multiline docstring is printed with spacing.

Important Implementation Details and Algorithms

• These tests rely heavily on the Pytester utility which provides an isolated environment to dynamically create files, run pytest, and check results.

• Fixtures are created both in test modules and conftest.py files to test fixture discovery and precedence.

• Output matching uses fnmatch_lines to allow for wildcard matching and partial string checks.

• Private fixture visibility is tested with and without verbose mode.

• Multiline docstring handling is tested differently depending on verbosity flags.

• Tests involving doctests ensure that doctest items integrate with the fixtures-per-test reporting without errors.

Interaction with Other System Components

• This file is part of pytest’s internal test suite, specifically testing the --fixtures-per-test feature.

• It interacts with:

  • pytest core test discovery and fixture management.

  • The Pytester testing utility (from _pytest.pytester).

  • The conftest.py mechanism in pytest for sharing fixtures.

  • The doctest plugin integration with pytest.

• The tests ensure that the reporting feature correctly reflects the fixtures used by each test case as managed by pytest’s fixture resolution system.

Visual Diagram

flowchart TD
    A[Start Test Function] --> B[Create test files (test modules, conftest.py)]
    B --> C[Run pytest with '--fixtures-per-test']
    C --> D[Capture stdout and return code]
    D --> E{Assertions}
    E -->|Check fixture usage output| F[Validate fixture names, docstrings, locations]
    E -->|Check no unwanted output| G[Ensure private fixtures hidden unless verbose]
    E -->|Check doctest integration| H[Validate doctest item collection]
    F --> I[Pass or Fail test]
    G --> I
    H --> I

Summary

This file is a comprehensive test suite ensuring that pytest’s `--fixtures-per-test` option accurately reports fixture usage across a variety of scenarios. It verifies correct inclusion/exclusion of fixtures, proper handling of fixture docstrings (including multiline), precedence of fixtures between `conftest.py` and test modules, private fixture visibility, and compatibility with doctest items. The tests simulate real-world use cases and check the CLI output for correctness, thereby helping maintain the reliability and correctness of pytest’s fixture reporting feature.