release-2.2.0.rst

Overview

This file contains the release notes and changelog for **pytest version 2.2.0**, a popular Python testing tool also known as *py.test*. It documents the new features, improvements, bug fixes, and important compatibility notes introduced in this release. The file serves as an official communication to users and plugin developers, providing guidance on usage changes, new APIs, and upgrade considerations.

The release focuses on enhancing test parametrization, marker handling, and profiling test durations, along with improved teardown behavior for more accurate reporting.

Detailed Description

Purpose and Functionality

The document’s primary purpose is to:

• Summarize key new features in pytest 2.2.0.

• Highlight compatibility and upgrade notes for plugin developers.

• List important bug fixes and improvements since version 2.1.3.

• Provide pointers to further documentation and examples.

• Help users understand how to leverage new capabilities effectively.

This file is typically distributed with the pytest package and referenced by developers during upgrades or when exploring new functionalities.

Key Features Introduced

1. Test Parametrization Enhancements

   • @pytest.mark.parametrize Decorator
     Allows test functions to be run multiple times with different argument sets. This makes it easier to write data-driven tests.

   • metafunc.parametrize() API
     A more flexible, programmatic interface to parametrize tests from plugins or hooks, enabling independent parameter injection.

   Example usage of `@pytest.mark.parametrize`:

   import pytest
   
   @pytest.mark.parametrize("input,expected", [
       (1, 2),
       (3, 4),
       (5, 6),
   ])
   def test_increment(input, expected):
       assert input + 1 == expected
   

   More examples and detailed usage are available at: http://pytest.org/en/stable/example/how-to/parametrize.html

2. Improved Test Markers and Selection

   • New -m markexpr command-line option to select tests by their markers. This provides a stricter alternative to the -k option.

   • A markers ini configuration variable to register known markers for the project, helping avoid typos.

   • A --strict option that causes pytest to error out if unregistered markers are used, enforcing marker discipline.

   For usage examples, visit: http://pytest.org/en/stable/example/markers.html

3. Duration Profiling

   • The --duration=N command-line option reports the N slowest test calls, including setup and teardown phases, helping identify performance bottlenecks in tests.

4. Eager Teardown Execution

   • Teardown and finalizer functions are now called more eagerly, improving the accuracy of failure reporting related to cleanup code.

Compatibility and Upgrade Notes

• Plugins need to be checked and possibly upgraded, especially those relying on pytest_runtest_logreport hook because it is now called unconditionally for setup/teardown phases.

• The pytest-xdist plugin requires at least version 1.7 to be compatible.

• Plugins should handle setup/teardown failures gracefully by checking rep.when attribute in the reports.

Bug Fixes and Miscellaneous Improvements

• Fixed several issues (#50, #74, #83, #87, #89, #90) related to teardown timing, module naming, PDB integration, and others.

• Cleaned up pytest’s own test suite to avoid leaking file descriptors.

• Improved compatibility with twisted/trial 11.1.0.

Implementation Details

• Parametrization Implementation: The addition of @pytest.mark.parametrize and metafunc.parametrize() allows multiple sets of input arguments to be supplied to a single test function, enabling dynamic test generation. Internally, this uses pytest’s hook system and test collection mechanisms to create multiple test instances.

• Marker Registration and Strict Mode: Markers are declared in ini files or via plugin hooks. During test collection and execution, pytest verifies marker usage against the registered set to enforce correctness, raising errors if unknown markers are used when --strict is enabled.

• Duration Profiling: When --duration is specified, pytest tracks execution time of test function calls and their setup/teardown phases, storing timings and reporting the slowest ones at the end of the test run.

• Eager Teardowns: The teardown phase has been refactored to call finalizers earlier, allowing failures in cleanup code to be reported immediately and more reliably.

Interactions with Other System Components

• Plugins: This release affects plugin developers significantly, especially those implementing hooks like pytest_runtest_logreport. Plugins must handle additional report phases and may use new APIs for parametrization and marker registration.

• Test Suites: Test suites using parametrization or markers will benefit from the new features for cleaner and more expressive tests, but may require updates to marker registration to avoid strict mode errors.

• Command-line Interface: New options (-m, --strict, --duration) extend CLI capabilities, enabling more powerful test selection and profiling.

• Documentation and Examples: The release notes link to online documentation and example pages, which have been expanded with new usage patterns for the features introduced.

Mermaid Diagram: Structural Overview of release-2.2.0.rst

The file is a textual changelog and does not define classes or functions but documents several key features and CLI options. The diagram below illustrates the main features and their relationships as described in the release.

flowchart TD
    A[pytest 2.2.0 Release] --> B[Parametrization]
    A --> C[Test Markers]
    A --> D[Duration Profiling]
    A --> E[Eager Teardown]
    B --> B1[@pytest.mark.parametrize decorator]
    B --> B2[metafunc.parametrize() API]
    C --> C1[-m markexpr option]
    C --> C2[markers ini-variable]
    C --> C3[--strict option]
    D --> D1[--duration=N option]
    E --> E1[Earlier teardown/finalizer calls]
    B1 -->|Usage| F[Multiple test runs with varied inputs]
    C1 -->|Usage| G[Select tests by marker]
    C3 -->|Enforcement| H[Error on unregistered markers]

Summary

`release-2.2.0.rst` is a comprehensive release note file for pytest 2.2.0, detailing major new features—primarily around test parametrization, marker handling, and profiling—along with compatibility notes and bug fixes. It serves as an essential resource for users upgrading pytest or developing plugins, helping them understand new capabilities and required changes. The file directs users to extensive online examples and documentation, reinforcing best practices for test development and execution with the new release.

**End of documentation.**