conftest.py

Overview

The [conftest.py](/projects/286/67243) file is a configuration and extension point for the `pytest` testing framework. It customizes test collection behavior to support a non-standard project structure where test files are explicitly listed in a manifest (`manifest.json`) instead of being discovered by default file pattern matching.

Specifically, this file defines a custom `ManifestDirectory` collector class that reads a `manifest.json` file in a directory and collects test files listed inside it. It also implements the `pytest_collect_directory` hook to enable `pytest` to use the custom collector automatically when it finds a `manifest.json`.

This approach allows finer control over which test files are included in test runs, enabling scenarios like selective or dynamic test suite definitions.

Detailed Explanation

Class: ManifestDirectory

A subclass of [pytest.Directory](/projects/286/67393) which overrides the default directory collection behavior.

Purpose

• To parse a manifest.json file in the directory.

• To collect test files explicitly listed under the "files" key in the manifest.

• To yield pytest collection nodes for each file found, enabling pytest to run tests from those files.

Methods

collect(self)

• Description:
  Reads the manifest.json file from the directory path, parses the list of files, and yields pytest collection nodes by delegating to pytest’s internal hook (ihook.pytest_collect_file).

• Parameters:

  • self: instance of ManifestDirectory.

• Returns:
  An iterator yielding pytest collection nodes for each file specified in the manifest.

• Usage Example:

  # Suppose the manifest.json contains:
  # { "files": ["test_example.py", "test_utils.py"] }
  md = ManifestDirectory.from_parent(parent=None, path=Path("/path/to/tests"))
  collected = list(md.collect())
  # `collected` now contains pytest nodes for test_example.py and test_utils.py
  

• Implementation Details:

  1. Constructs the path to manifest.json inside the directory.

  2. Reads and parses the JSON contents.

  3. Iterates over each file listed in the "files" array.

  4. Uses pytest's ihook.pytest_collect_file to collect test nodes for each file.

Function: pytest_collect_directory(path, parent)

• Description:
  A pytest hook implementation that is called when pytest encounters a directory during collection. This function checks if the directory contains a manifest.json file. If it does, it returns an instance of ManifestDirectory to customize collection for that directory.

• Parameters:

  • path (py.path.local or pathlib.Path): The directory path being collected.

  • parent (pytest.Collector): The parent collector node.

• Returns:

  • An instance of ManifestDirectory if manifest.json exists in the directory, or

  • None to let pytest fall back to default collection behavior.

• Usage Example:

  This function is automatically called by pytest; users do not call it directly.

Important Implementation Details

• The file uses forward compatibility import: from __future__ import annotations to enable postponed evaluation of type annotations.

• It suppresses type checking warnings for untyped functions with # mypy: allow-untyped-defs.

• The manifest file must be named exactly manifest.json and located in the directory.

• The manifest file should have a JSON structure like:

  {
    "files": [
      "test_file1.py",
      "test_file2.py"
    ]
  }
  

• The design leverages pytest's internal hook system (ihook.pytest_collect_file) to convert file paths into pytest test nodes, ensuring compatibility with pytest’s collection mechanism.

• This enables integration with pytest features like fixtures, parametrization, and plugins without additional modifications.

Interaction with Other Parts of the System

• pytest Framework:

  • The file hooks directly into pytest’s collection phase via the pytest_collect_directory hook.

  • The ManifestDirectory subclass extends pytest’s built-in Directory collector.

  • The ihook.pytest_collect_file method is used to delegate file-level collection back to pytest.

• Test Suite Structure:

  • Instead of pytest’s default pattern-based discovery (test_*.py, *_test.py), tests are selected based on the manifest file contents.

  • This allows test suite maintainers to explicitly define which files are included in test runs.

• File System:

  • Relies on the presence of manifest.json files in test directories.

  • Uses file I/O (read_text) with UTF-8 encoding to read manifest contents.

Visual Diagram

flowchart TD
    A[pytest_collect_directory Hook]
    B[ManifestDirectory Class]
    C[manifest.json File]
    D[ihook.pytest_collect_file]
    E[Test Files Listed in manifest.json]

    A -->|detects manifest.json| B
    B -->|reads manifest.json| C
    B -->|for each file| D
    C -->|provides file list| B
    D -->|collect test nodes for| E

Summary

This [conftest.py](/projects/286/67243) customizes pytest’s collection logic to support a manifest-driven test discovery mechanism. It defines a new directory collector class that parses a `manifest.json` file to enumerate test files, and registers a hook to activate this collector automatically. This setup enables explicit control over test file inclusion, improving flexibility for complex or non-standard project layouts while fully integrating with pytest’s core features.