release-2.3.4.rst

Overview

The [release-2.3.4.rst](/projects/286/66986) file is a release note document for the `pytest` testing framework, specifically detailing changes introduced in version 2.3.4. This file serves as an informational summary for users and developers, highlighting new features, bug fixes, and important usage notes that accompany the release.

Rather than containing executable code, this file is intended as a human-readable changelog to communicate enhancements and fixes that improve stability and usability of the `pytest` tool.

Key functionalities and improvements described include:

Enhancement of the -k test selection option to accept logical expressions.
Dynamic marker definitions for test selection.
Improvements in fixture behavior, especially regarding yielded test functions and autouse fixtures.
Fixes addressing ordering of fixture teardowns, argument length limitations, and autouse fixture discovery.
Examples and documentation enhancements.

This file is part of the documentation suite that assists users in upgrading and utilizing the new features and fixes in pytest 2.3.4.

Detailed Explanation

Content Type

This file is a **release note / changelog**, formatted using reStructuredText (`.rst`), a common markup language in Python projects for documentation.

Purpose and Usage

Audience: Test developers and users of pytest looking to understand what has changed in version 2.3.4.
Usage: Read to learn about new capabilities, bug fixes, and any backward-incompatible changes that may affect test suite behavior.

Main Sections and Highlights

Release Title and Version
- pytest-2.3.4: stabilization, more flexible selection via "-k expr"
Release Description
- Describes pytest as a tool offering simple assertions, fixture scalability, and customization.
- Emphasizes that 2.3.4 is a stabilization release with incremental improvements.
New Features and Fixes
- -k option enhancement:
  - Now accepts logical expressions similar to -m.
  - Usage example: -k "name1 or name2".
  - Backward compatibility note: To match specific methods in classes, use -k "TestClass and test_method".
- Dynamic Marker Definition:
  - Users can define markers dynamically via item.keywords[...] = assignment.
  - This integrates with the -m selection option.
- Yielded Tests and Fixtures:
  - Yielded tests now activate autouse fixtures.
  - Yielded tests cannot accept fixtures as function arguments (funcargs).
  - Recommended to use parameterize features instead of yield, with documentation link provided.
- Autouse Fixture Fixes:
  - Fixes issues where autouse fixtures in conftest.py were not discovered in some test directories.
- Fixture Teardown Ordering:
  - Ensures fixture teardown follows Last-In-First-Out (LIFO) order.
- Argument Length Fix:
  - Fixes command invocations with arguments longer than 256 characters.
- Package/Directory Setup Examples:
  - Adds or discusses examples for package/directory-level setup.
- Additional Autouse Discovery Fixes
Acknowledgements
- Thanks contributors, notably Thomas Waldmann, for reporting issues.
References and Installation Instructions
- Points users to the official pytest website: http://pytest.org/.
- Installation and upgrade commands via pip or easy_install.

Implementation Details and Algorithms

As this is a release note document and not source code, it does not contain implementation code or algorithms. However, it references improvements in pytest’s internal behavior and mechanisms, such as:

Parsing enhancements for the -k expression option allowing logical operators.
Dynamic marker assignment affecting test selection.
Fixture lifecycle management improvements, particularly autouse fixture discovery and teardown ordering (LIFO).

These reflect underlying changes to the pytest core but are not detailed here.

Interactions with Other System Components

pytest Core: The release notes describe changes directly affecting pytest’s core test selection and fixture mechanisms.
Test Suites: Users’ test suites may be impacted by changes in how the -k option parses expressions and how autouse fixtures are discovered and executed.
Documentation: This file serves as part of the official documentation, guiding users in upgrading and adapting their tests.
Package Installation Tools: References to pip and easy_install for installation/upgrade show interaction with Python package management.

Usage Example of Key Feature (`-k` option)

# Select tests whose names contain 'login' or 'signup'
pytest -k "login or signup"

# Select tests defined in TestUser class and the method test_create
pytest -k "TestUser and test_create"

Visual Diagram

Since this file is documentation describing a release, a **flowchart** illustrating the main features and how they relate to test selection and fixture management in pytest 2.3.4 is most relevant.

flowchart TD
    A[pytest-2.3.4 Release] --> B[-k option enhanced]
    A --> C[Dynamic marker definition]
    A --> D[Yielded tests with autouse fixtures]
    A --> E[Fixture teardown LIFO ordering]
    A --> F[Autouse fixture discovery fixes]
    A --> G[Argument length fix (>256 chars)]
    B --> B1["-k" accepts expressions]
    B1 --> B2["Usage: -k \"name1 or name2\""]
    D --> D1[Yielded tests activate autouse fixtures]
    D --> D2[Yielded tests cannot accept funcargs]
    F --> F1[Fix discovery in conftest.py vs tests]

Summary

The [release-2.3.4.rst](/projects/286/66986) file is a concise, user-facing changelog documenting improvements and fixes in pytest 2.3.4. It primarily focuses on enhanced test selection flexibility, fixture management stability, and bug fixes to improve testing workflows. This documentation is essential for users upgrading pytest to adapt to new behaviors and leverage improved features efficiently.