release-2.6.1.rst

Overview

This file contains the release notes and changelog for the pytest testing framework version 2.6.1. Pytest is a widely used Python testing tool that simplifies writing and running tests. The 2.6.1 release is a patch update focused on fixing regressions introduced in version 2.6.0 while maintaining compatibility with version 2.5.2. Additionally, it introduces an enhancement to the `xfail` marker, allowing specification of expected exceptions.

The document serves as a concise summary of fixes, improvements, and acknowledgments for contributors involved in this release.

Purpose and Functionality

Provides users and developers with a detailed list of bug fixes and new features in pytest 2.6.1.
Highlights compatibility and upgrade instructions.
Acknowledges contributors who helped improve this release.
Offers references to official documentation and installation commands.

Detailed Content Breakdown

Release Description

Pytest version 2.6.1 is compatible as a drop-in replacement for 2.5.2.
Fixes regressions introduced in 2.6.0.
Adds a feature to pytest.mark.xfail to specify expected exceptions (raises=EXC).

Upgrade Instructions

Users can upgrade to this version via the Python Package Index (PyPI) using the command:

pip install -U pytest

Notable Contributors

Floris Bruynooghe
Bruno Oliveira
Nicolas Delaby

Change Log Summary

Fix / Feature	Description	Contributor
Remove line numbers in verbose output	The `--verbose` output no longer shows line numbers, only node IDs; line numbers remain in failure reports.	Floris Bruynooghe
Assertion rewriting fix	Fixed issue #437 where pytest-xdist worker nodes collected different tests due to assertion rewriting.	Bruno Oliveira
Add `errors` attribute to capture streams	Added `errors` attribute to captured streams (`sys.stdout.errors`) to improve compatibility.	Bruno Oliveira
Fix output capturing with capsys/capfd	Ensured that `capsys` and `capfd` fixtures work even when output capturing (`-s`) is disabled.
`xfail` expected exceptions enhancement	Allowed `pytest.mark.xfail` to accept `raises=EXC` argument to specify expected exceptions.	David Mohr
Integration fix with `unittest.mock.patch`	Fixed interaction with `mock.patch` decorator when using the `new` argument.	Nicolas Delaby
Conftest detection fix	Fixed detection of `conftest.py` files when test node IDs contain `::` specifications.
Fix `@NUM` removal logic	Restricts removal of `@NUM` suffixes to only parts with `.py` extensions in node IDs.
Removed py.std import helper	Direct imports used instead of `py.std` import helper for better clarity and maintenance.	Bruno Oliveira

Important Implementation Details

pytest.mark.xfail raises argument: The new optional parameter raises=EXC allows users to mark tests as expected to fail only if specific exceptions occur. EXC can be a single exception class or a tuple of exception classes. This enhancement helps differentiate between expected and unexpected failures more precisely.
Assertion rewriting fix: The fix for issue #437 addresses a subtle problem where the assertion rewriting mechanism could cause distributed test workers (pytest-xdist) to collect inconsistent test sets. The solution ensures uniform test collection across workers.
Output capturing fixes: Adjustments were made to the capturing subsystem to ensure compatibility with disabled capturing (-s) and to add missing attributes (errors) to captured streams, improving integration with distutils and other libraries relying on these features.

Interaction with Other System Components

pytest core and plugins: This release directly affects pytest core functionality and its plugins such as pytest-xdist (distributed testing) and pytest-mock (mocking utilities).
Test discovery and execution: Fixes in conftest file detection and assertion rewriting influence how tests are discovered and executed, ensuring consistency and correctness.
Output capturing subsystem: Enhancements and fixes to output capturing impact how test output is intercepted, displayed, and logged, affecting user experience and integration with other tools.
Marking and reporting: The xfail marker enhancement affects test marking semantics and failure reporting, providing users finer control over expected test failures.

Usage Examples

Using the new `raises` argument with `xfail`

You can mark a test as an expected failure only if it raises a specific exception:

import pytest

@pytest.mark.xfail(raises=ValueError)
def test_divide():
    assert 1 / 0  # This raises ZeroDivisionError, so test will be reported as failure, not xfail

@pytest.mark.xfail(raises=(ZeroDivisionError, ValueError))
def test_divide_multiple():
    assert 1 / 0  # This raises ZeroDivisionError, considered expected, reported as xfail

This feature helps distinguish between failures caused by expected exceptions and other unexpected errors.

Visual Diagram

The following Mermaid class diagram summarizes the key conceptual entities and relationships implied in this release notes file, focusing on pytest testing constructs affected:

classDiagram
    class pytest {
        +install()
        +run_tests()
        +mark_xfail(raises=Exception or tuple)
    }

    class TestNode {
        +nodeid: str
        +collect()
        +execute()
    }

    class CaptureStreams {
        +stdout
        +stderr
        +errors
    }

    class pystd_import_helper {
        <<deprecated>>
    }

    pytest --> TestNode : manages
    pytest --> CaptureStreams : captures output
    pytest ..|> pystd_import_helper : replaced by direct imports

Explanation:

pytest is the main testing framework interface, managing test collection (TestNode) and output capturing (CaptureStreams).
The mark_xfail method is enhanced with the raises parameter in this release.
The deprecated pystd_import_helper was removed in favor of explicit imports.

Summary

This file is a release notes document for pytest 2.6.1, summarizing bug fixes, minor feature additions (notably the enhanced `xfail` marker), and credits to contributors. It provides users with upgrade instructions, compatibility assurances, and a detailed changelog describing improvements in test collection, output capturing, and test marking. The fixes ensure improved stability and usability of pytest, especially in distributed and complex testing scenarios.

For more information, users are referred to the official pytest documentation: http://pytest.org