release-2.7.0.rst

Overview

This file is the release notes for **pytest version 2.7.0**, a mature Python testing framework widely used for writing and running test cases. The document summarizes the key fixes, new features, improvements, and important changes introduced in this release compared to the previous version 2.6.4.

pytest is known for its simple syntax, powerful fixtures, and extensive plugin system. This release focuses on enhancing reliability (fixing bugs), improving performance (speeding up plugin hook invocation), and extending functionality (new command-line options, better test discovery, and plugin hook mechanisms).

These release notes serve as a changelog and upgrade guide for users and plugin developers who want to understand what has changed, what issues were fixed, and what new capabilities are now available.

Detailed Explanation of Contents

Since this file is a plain text changelog rather than code, it contains no classes, functions, or methods. Instead, it documents the changes made in the pytest codebase in version 2.7.0.

Below is a detailed breakdown of the main topics covered:

Fixes and Bug Resolutions

• Reloading with assert rewriting
  Reloading modules with reload() works correctly now even when pytest’s assertion rewriting is active (issue435).

• Conftest.py fixture visibility
  The visibility of fixtures defined in conftest.py files is now correctly handled regardless of the current working directory or test arguments (issue616). This introduces the concept of a rootdir that is shown in pytest’s header and documented in the customization guide.

• Diverted tests reporting
  Tests collected from one file but defined in another (e.g., inherited test classes) are now reported with their actual nodeid and a postfix indicating the source file.

• Doctest import errors
  New option --doctest-ignore-import-errors allows skipping doctests that raise import errors instead of failing them (issue650).

• Sys.exc_info leak fixes
  Addressed Python 2/3 differences causing leaks of sys.exc_info in fixtures/tests, which previously caused failures in third-party code (issue655).

• Assertion rewriting escape fix
  Properly escapes % signs in assertions mixing booleans and modulo operators, fixing formatting errors in assertion messages (issue615).

• Parameterize misspelling error
  Raised specific error messages when parameterize is misspelled, helping users catch common mistakes (issue463).

• Postmortem debugging
  On test failures, sys.last_value, sys.last_type, and sys.last_traceback are set to enable interactive postmortem debugging.

New Features and Improvements

• Environment variable for CLI options
  Added support for setting pytest command line options via the PYTEST_ADDOPTS environment variable.

• Parametrize ids as callable
  Parametrize decorator can now accept a callable to generate custom test IDs dynamically (issue351).

• Hookwrapper mechanism
  Introduced a new hookwrapper feature for plugins, allowing them to wrap hook execution. This replaces the older undocumented multicall protocol and improves plugin architecture. pytest 2.8 will drop support for the old protocol.

• Speed improvements
  Major speedup for plugin hook invocation.

• Built-in plugins use hookwrapper
  The built-in pytest plugins have been updated to use the new hookwrapper mechanism.

• Doctest ini option
  Added configuration option in ini files for doctest flags.

• Test discovery glob patterns
  python_classes and python_functions options now support glob-style patterns to filter test discovery (issue600).

• Parametrized fixture override
  It is now possible to override parametrized fixtures with non-parametrized ones and vice versa.

• Documentation updates
  Added docs on pytest-dev teams, clarifications on marking callable parameters, and contribution guidelines.

Usage Examples

Though this file does not contain executable code, here are examples of how some of the new features might be used in pytest test suites or configurations:

1. Using PYTEST_ADDOPTS to set CLI options:

export PYTEST_ADDOPTS="--maxfail=2 --strict"
pytest

This will apply the options as if passed on the command line.

2. Using callable for parametrize ids:

def id_func(param):
    return f"id_{param}"

@pytest.mark.parametrize("input", [1, 2, 3], ids=id_func)
def test_example(input):
    assert input > 0

This generates custom test IDs like `id_1`, `id_2`, etc.

3. Ignoring import errors in doctests:

Run pytest with:

pytest --doctest-ignore-import-errors

This makes doctests skip over import errors instead of failing.

Implementation Details and Algorithms

• Hookwrapper Protocol
  The new hookwrapper mechanism allows plugins to yield control within hook implementations, enabling pre- and post-processing around hook execution. Under the hood, this is implemented using Python generators inside hook functions to wrap other hooks seamlessly, improving plugin composition and maintainability.

• Conftest.py Fixture Visibility
  The introduction of a rootdir concept standardizes the test root directory determination logic, improving fixture resolution consistency across different invocation contexts.

• Speed Optimizations
  The release notes mention major speed improvements in plugin hook invocation, likely through internal caching or more efficient hook dispatch mechanisms, though specifics are not detailed here.

Interaction with Other Parts of the System

• pytest Core and Plugins
  This release directly affects the core pytest engine and its plugin infrastructure by introducing the hookwrapper protocol and improving plugin hook performance.

• User Test Suites
  Users benefit from better test discovery, clearer error messages, and new options for test execution control.

• Documentation and Community
  Updates to documentation and contributor information encourage community involvement and facilitate easier adoption of new features.

• Command Line and Environment
  The addition of environment variable configuration (PYTEST_ADDOPTS) affects how pytest is invoked in automated environments like CI pipelines.

Mermaid Diagram: Structure of release-2.7.0.rst

The file is a changelog document, so a **flowchart** representing the main topics of the release and their relationships is most appropriate.

flowchart TD
    A[pytest 2.7.0 Release Notes] --> B[Fixes and Bug Resolutions]
    A --> C[New Features and Improvements]
    A --> D[Usage Examples]
    A --> E[Implementation Details]
    A --> F[System Interaction]

    B --> B1[Reload fix with assert rewriting]
    B --> B2[Conftest.py fixture visibility]
    B --> B3[Diverted tests reporting]
    B --> B4[Doctest import errors skip]
    B --> B5[Sys.exc_info leak fix]
    B --> B6[Assertion rewriting escape fix]
    B --> B7[Parameterize misspelling error]
    B --> B8[Postmortem debugging]

    C --> C1[PYTEST_ADDOPTS env variable]
    C --> C2[Parametrize ids callable]
    C --> C3[Hookwrapper mechanism]
    C --> C4[Speed improvements]
    C --> C5[Doctest ini option]
    C --> C6[Test discovery glob patterns]
    C --> C7[Parametrized fixture overrides]
    C --> C8[Documentation updates]

Summary

This release notes file documents important fixes, enhancements, and new features introduced in pytest 2.7.0. It is an essential reference for users upgrading from 2.6.x, plugin developers adapting to new hook mechanisms, and contributors keeping track of project evolution. The file itself is a human-readable changelog without executable code but reflects substantial internal improvements and user-facing capabilities in the pytest testing tool.