conftest.py

Overview

This file customizes **pytest's test collection behavior at the directory level** by implementing a manifest-driven collection strategy. Instead of pytest’s default approach of discovering test files by filename patterns (e.g., `test_*.py`), this file enables pytest to read a `manifest.json` file inside a test directory and **collect only the test files explicitly listed there**.

This approach offers precise and deterministic control over which test files are collected, helping manage large or complex test suites where not all files in a directory should be considered tests or where custom selection rules are necessary.

Detailed Explanation

Class: ManifestDirectory

**Inheritance:** `pytest.Directory`

This class is a **custom directory collector** that overrides the default directory collection behavior by reading a manifest file and collecting only the files listed in it.

Method: collect(self)

• Purpose:
  To yield test file collectors selectively based on the manifest contents instead of collecting all test files in the directory.

• Process:

  1. Reads the manifest.json file located in the directory (self.path).

  2. Parses it as JSON to obtain the list of files under the "files" key.

  3. For each listed file, it uses pytest’s internal hook pytest_collect_file (ihook.pytest_collect_file) to collect the test file, yielding the resulting collectors.

• Parameters:
  self — instance of ManifestDirectory.

• Returns:
  A generator yielding collected test file nodes (pytest collectors).

• Usage Example:

  # Assuming a ManifestDirectory instance for path "/tests/unit"
  for test_file_collector in manifest_directory.collect():
      # test_file_collector represents collected test module/item
      print(test_file_collector)
  

• Implementation Details:

  def collect(self):
      manifest_path = self.path / "manifest.json"
      manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
      ihook = self.ihook
      for file in manifest["files"]:
          yield from ihook.pytest_collect_file(
              file_path=self.path / file, parent=self
          )
  

  This method assumes the manifest JSON structure is:

  {
      "files": [
          "test_example1.py",
          "test_example2.py"
      ]
  }
  

Function: pytest_collect_directory(path, parent)

• Role:
  This is a pytest hook implementation that intercepts pytest’s directory collection process.

• Functionality:
  When pytest starts collecting tests in a directory, this function is called with:

  • path: py.path.local or pathlib.Path object representing the directory.

  • parent: The parent collector node.

  The function checks if the directory contains a `manifest.json` file. If so, it instantiates and returns a `ManifestDirectory` collector to handle collection for that directory, thus overriding the default collection behavior. If no manifest is found, it returns `None`, allowing pytest to fall back to its default directory collector.

• Parameters:

  Name	Type	Description
  path	`Path`-like object	The directory path to be collected
  parent	pytest Collector	Parent collector in pytest’s tree

• Returns:

  • ManifestDirectory instance for directories with manifest files.

  • None otherwise.

• Example Use:

  @pytest.hookimpl
  def pytest_collect_directory(path, parent):
      if path.joinpath("manifest.json").is_file():
          return ManifestDirectory.from_parent(parent=parent, path=path)
      return None
  

Important Implementation Details and Algorithms

• Selective Test Discovery:
  The core algorithm is simple yet powerful: it overrides directory collection by reading a manifest JSON file that explicitly enumerates test files. This detaches test discovery from file naming conventions or directory scanning, providing deterministic control.

• Integration with pytest's Internal Hooks:
  The custom collector delegates actual file collection to pytest’s internal hook pytest_collect_file, maintaining compatibility with pytest’s collection machinery and plugins.

• Fallback Logic:
  If no manifest.json exists, the system falls back to the default directory collection. This ensures that only directories opting into this behavior are affected.

• Encoding Awareness:
  The manifest file is read with UTF-8 encoding to avoid encoding issues.

Interaction with Other System Components

• pytest Core:
  The file hooks into pytest’s test collection subsystem, specifically:

  • pytest_collect_directory: a hook called by pytest when collecting tests in directories.

  • pytest_collect_file: used internally to collect individual test files.

• Test Suite Structure:
  This file expects each directory that wants manifest-driven collection to contain a manifest.json file defining which test files to collect.

• Test Files and Test Items:
  Once files are collected via pytest_collect_file, pytest proceeds with its standard processing—loading modules, collecting test functions/classes, and running tests.

• User Configuration:
  This file acts as a plugin-like extension in the root of a test suite or pytest configuration directory (conftest.py), automatically enabling manifest-based collection for any directory that includes a manifest.

Visual Diagram

flowchart TD
    A[pytest starts directory collection] --> B{Is manifest.json present?}
    B -- Yes --> C[Instantiate ManifestDirectory collector]
    C --> D[ManifestDirectory.collect() called]
    D --> E[Read manifest.json and parse file list]
    E --> F[For each file in manifest]
    F --> G[Call ihook.pytest_collect_file(file_path)]
    G --> H[Yield collected test file nodes]
    H --> I[pytest processes collected tests]
    B -- No --> J[Use default pytest Directory collector]
    J --> I

Summary

The `conftest.py` file provides a **custom pytest directory collector** that reads a `manifest.json` file to determine exactly which test files to collect. This approach overrides the default filename pattern-based collection behavior on a per-directory basis, offering fine-grained control over test discovery.

By implementing the `ManifestDirectory` collector and hooking into `pytest_collect_directory`, this file integrates seamlessly with pytest’s collection framework while enabling deterministic and manageable test collection in complex test suites.

References

• pytest hook functions — pytest documentation

• pytest.Directory class — pytest internals

• Custom Test Collection — pytest plugin development

*End of conftest.py Documentation*