test_collect_imported_tests.py

Overview

This file contains automated tests for the `collect_imported_tests` configuration option in **pytest**. The `collect_imported_tests` setting controls whether pytest collects and runs test functions and test classes imported into test modules from other modules.

• When collect_imported_tests is disabled (false), pytest only collects tests defined directly in the test modules.

• When collect_imported_tests is enabled (true, the default), pytest also collects test classes and test functions imported into the test modules.

The test cases here verify that pytest behaves correctly based on these configuration settings by creating temporary source and test files, running pytest on them, and asserting the collected tests.

Detailed Explanation of Components

Functions

setup_files(pytester: Pytester) -> None

**Purpose:** Prepares a sample project structure with source and test files used in the tests.

**Parameters:**

• pytester (Pytester): A pytest fixture providing a test environment with utilities for creating files and running pytest in isolation.

**Behavior:**

• Creates two directories: src and tests.

• Writes a Python source file foo.py in src with:

  • A class Testament containing a test method test_collections.

  • A standalone test function test_testament.

• Writes a test file foo_test.py in tests that imports Testament and test_testament from foo.py and defines a test class TestDomain with one test method.

• Inserts src in the Python path so imports in tests succeed.

**Usage Example:**

def test_example(pytester: Pytester) -> None:
    setup_files(pytester)
    # After this, the test environment has 'src/foo.py' and 'tests/foo_test.py' created.

test_collect_imports_disabled(pytester: Pytester) -> None

**Purpose:** Tests that when `collect_imported_tests` is set to `false`, only test objects defined directly in test modules are collected.

**Parameters:**

• pytester (Pytester): Pytest testing environment fixture.

**Behavior:**

• Creates a pytest configuration file (pytest.ini) with collect_imported_tests = false.

• Calls setup_files to prepare the source and test files.

• Runs pytest on the tests directory.

• Asserts that only the test method inside the test module (tests/foo_test.py::TestDomain::test) is collected and run.

• Checks internal pytest hooks and reports to confirm only the relevant test was collected.

**Usage Example:**

pytest -v tests
# Expect only tests defined directly in test modules to run.

test_collect_imports_enabled(pytester: Pytester, configure_ini: bool) -> None

**Purpose:** Tests that when `collect_imported_tests` is enabled (default or explicitly set), pytest collects tests imported into test modules as well.

**Parameters:**

• pytester (Pytester): Pytest testing environment fixture.

• configure_ini (bool): Whether to explicitly set collect_imported_tests = true in pytest.ini or rely on the default value.

**Behavior:**

• Optionally creates pytest.ini with collect_imported_tests = true if configure_ini is True.

• Calls setup_files to prepare source and test files.

• Runs pytest on the tests directory.

• Asserts that all tests are collected and run, including:

  • Testament.test_collections (imported class method)

  • test_testament (imported standalone function)

  • TestDomain.test (defined in the test module)

**Usage Example:**

pytest -v tests
# Expect tests from imported classes/functions and test module to run.

Important Implementation Details

• Uses pytester fixture from pytest to create temporary test environments with isolated files and run commands.

• Uses textwrap.dedent to write clean multi-line source code strings.

• Uses Python's pathlib-style path operations to create and write files.

• Checks pytest internal hooks (pytest_collectreport, pytest_collection_modifyitems, pytest_itemcollected) to validate collection behavior.

• Uses pytest.mark.parametrize to test both explicit and implicit enabling of the config option.

Interaction with Other Parts of the System

• This test file is part of pytest's internal test suite or plugin test suite.

• It ensures correctness of pytest's test collection logic when the collect_imported_tests setting is toggled.

• Interacts with pytest core collection mechanism and configuration system.

• Uses pytest's Pytester testing utility to simulate test runs and inspect results.

• Depends on the existence and behavior of the collect_imported_tests configuration option in pytest's collection plugins.

Visual Diagram: Class and Functions Structure

flowchart TD
    A[setup_files(pytester: Pytester) : None]
    B[test_collect_imports_disabled(pytester: Pytester) : None]
    C[test_collect_imports_enabled(pytester: Pytester, configure_ini: bool) : None]

    B --> A
    C --> A

**Diagram Explanation:**

• setup_files is a utility function called by both test functions.

• The two test functions represent different test scenarios depending on the configuration setting.

• The flowchart shows dependencies and call relationships.

Summary

This file contains functional tests that validate the behavior of pytest's `collect_imported_tests` configuration. It programmatically generates source and test files, runs pytest with different configuration states, and asserts that test collection aligns with expectations. This ensures that users can control whether pytest collects imported test functions and classes, enhancing flexibility in how test suites are organized.

End of Documentation for test_collect_imported_tests.py