release-2.0.0.rst

Overview

This file is the release notes document for **pytest version 2.0.0**, a major release of the popular Python testing tool known previously as "py.test." It serves as a comprehensive summary of new features, improvements, bug fixes, removals, and important notes related to the pytest 2.0.0 release.

The document is intended for developers, QA engineers, and users of pytest who want to understand the enhancements and changes introduced in this version. It also guides upgrading from previous versions and highlights backward-incompatible removals and new usage patterns.

Detailed Content Breakdown

1. Purpose and Functionality

This file primarily functions as:

• Release announcement: Informing users about the availability of pytest 2.0.0.

• Feature summary: Listing new capabilities and enhancements.

• Bug fixes: Documenting resolved issues.

• Breaking changes: Highlighting removals and incompatible modifications.

• Usage hints: Providing pointers to official documentation and installation methods.

• Acknowledgments: Thanking contributors and community members.

It is not executable code but rather a structured text document (in reStructuredText format) designed for reading and inclusion in official documentation or project changelogs.

2. Sections and Their Details

New Features

• Python Interpreter Invocation:
  Pytest can now be run using python -m pytest on Python versions 2.5 and above. This supports running tests without installing pytest as a command line tool.

• Programmatic API:
  Users can run pytest programmatically via import pytest; pytest.main(args, plugins), enabling integration with other Python tools and scripts.

• Enhanced Assertion Reporting:
  Improved output when assertions fail, especially when comparing lists, sequences, or strings, making debugging easier.

• Configuration Files Support:
  Pytest now supports ini-style configuration files (setup.cfg, tox.ini) with [pytest] sections for setting default options and directory exclusions.

• Improved unittest Compatibility:
  Better support for running unittest-based test cases, including those from frameworks like Twisted Trial or Django.

• Quiet Mode (-q):
  Added a -q flag for quieter output, similar to nose or unittest's dot-style test progress display.

• General Improvements:
  Various smaller enhancements and performance improvements.

Fixes

• Interactive Debugging:
  Added py.test.set_trace() to invoke pdb tracing during test runs even with output capturing.

• Reporting Resilience:
  Fixes related to file descriptor usage and capturing output during test runs.

• Conftest.py Loading Behavior:
  Prevent loading sibling conftest.py files and clarify limitations on customizing directory collectors.

• Test Node Discovery Fixes:
  Corrected issues with finding custom test nodes and capturing stdout/stderr during conftest.py import.

• pytestmark Application:
  Fixed applying pytestmark decorators on unittest-collected functions at class/module levels.

Important Notes

• Legacy Usage:
  py.test.raises remains available but pytest.raises is now the recommended default.

• Collection Phase Change:
  Pytest now collects the entire test suite before executing any tests, which may affect plugin behavior.

• Codebase Size:
  The core codebase is roughly 400 lines with about 20 builtin plugins, highlighting a lean and modular design.

Incompatible Removals

• py.test.config access restricted to test run contexts.

• Removed deprecated features:

  • Module/Class collection node definitions in conftest.py.

  • Old collection APIs (run(), join()).

  • Option reading from conftest.py or environment variables.

  • disabled attribute for test classes (use skipping mechanisms instead).

  • py.test.collect.Directory class removed; custom directory collectors no longer supported.

• Backward compatibility maintained for certain hooks like pytest_collect_directory() but their return values are ignored.

3. Implementation Details and Algorithms

Since this is a release notes file, it does not contain executable code or algorithms. However, the document hints at architectural and implementation details relevant to pytest 2.0.0:

• The test collection mechanism now fully completes before any test execution, affecting plugin hook calls such as pytest_collectstart and pytest_collectreport.

• The core pytest package is small and modular, relying on external packages like "pylib" and "py" for filesystem and introspection utilities.

• The reporting improvements for assertions indicate enhanced introspection and formatting logic for test failures.

4. Interactions with Other System Components

• pytest Core and Plugins:
  This release notes document describes changes affecting core pytest components (core.py, builtin plugins) and plugin interfaces (hooks, collection).

• Configuration Files:
  Introduces support for ini-style config files (setup.cfg, tox.ini) that influence pytest's runtime behavior.

• Python Standard Library unittest:
  Improved interoperability with unittest, allowing pytest to run existing unittest test suites more seamlessly.

• User Scripts and CI Pipelines:
  Programmatic API (pytest.main) and python -m pytest invocations enable integration into custom scripts, continuous integration systems, and other automation.

• Third-party Plugins:
  Changes in collection and plugin hooks may require updates to third-party pytest plugins to maintain compatibility.

5. Usage Examples

**Running pytest from the command line:**

python -m pytest tests/

**Running pytest programmatically:**

import pytest

# Run pytest with custom arguments and plugins
pytest.main(['-v', 'tests/'], plugins=[])

**Using configuration file (setup.cfg or tox.ini):**

[pytest]
norecursedirs = .hg data*
addopts = -x --pyargs

6. Visual Diagram: pytest-2.0.0 Release Notes Structure

This flowchart represents the main sections of the release notes file and their relationships, illustrating the logical flow for readers.

flowchart TD
    A[Release Notes: pytest 2.0.0] --> B[New Features]
    A --> C[Fixes]
    A --> D[Important Notes]
    A --> E[Incompatible Removals]
    B --> B1[Python Interpreter Invocation]
    B --> B2[Programmatic API]
    B --> B3[Enhanced Assertion Reporting]
    B --> B4[Configuration Files Support]
    B --> B5[Improved unittest Support]
    C --> C1[Interactive Debugging]
    C --> C2[Reporting Resilience]
    C --> C3[Conftest.py Loading]
    C --> C4[Test Node Discovery]
    C --> C5[pytestmark Fixes]
    D --> D1[Legacy Usage]
    D --> D2[Collection Phase Change]
    D --> D3[Codebase Size]
    E --> E1[py.test.config Access]
    E --> E2[Deprecated Features Removed]
    E --> E3[Directory Collector Removal]

Summary

The [release-2.0.0.rst](/projects/286/66986) document is an authoritative, detailed release note for pytest 2.0.0, outlining its significant new features, bug fixes, and breaking changes. It is essential reading for users upgrading from earlier versions, plugin developers adapting to new APIs, and anyone interested in the evolution of the pytest testing framework.

By following the installation instructions and reviewing the documented changes, users can leverage improved testing capabilities, enhanced configurability, and better integration with Python’s ecosystem provided by this major release.