raises.py

Overview

The [raises.py](/projects/286/67357) file contains a comprehensive suite of test cases primarily focused on validating the behavior of `pytest.raises`, a utility provided by the pytest testing framework. The `pytest.raises` function is a context manager and function wrapper used to assert that a block of code or a function call raises a specified exception. This file tests various aspects of `pytest.raises`, including its handling of callable inputs, exception matching via regex, context management, error messages, edge cases, and integration with pytest's internal components.

The primary purpose of this file is to ensure the correctness, robustness, and user-friendly error reporting of the `pytest.raises` mechanism. It also verifies that `pytest.raises` behaves properly under unusual or erroneous conditions, such as invalid regex patterns or incorrect arguments.

Detailed Documentation

Function: wrap_escape(s: str) -> str

**Purpose:** Wraps a string with `^` and `$` anchors and escapes special regex characters within the string. This is used to create exact-match regular expressions for error message matching.

**Parameters:**

• s (str): The input string to escape and wrap.

**Returns:**

• str: A regex pattern string that matches exactly the input string.

**Example Usage:**

pattern = wrap_escape("Exact error message")
# pattern == "^Exact\\ error\\ message$"

Class: TestRaises

This class contains multiple test methods that validate different functionalities and edge cases of the `pytest.raises` utility.

Methods in TestRaises

test_check_callable(self) -> None

**Description:** Verifies that `pytest.raises` raises a `TypeError` when passed a non-callable object as the function to execute.

**Example:**

with pytest.raises(TypeError, match=".* must be callable"):
    pytest.raises(RuntimeError, "int('qwe')")

test_raises(self)

**Description:** Tests that `pytest.raises` correctly catches a `ValueError` raised by calling `int("qwe")`.

test_raises_function(self)

**Description:** Similar to `test_raises`; ensures `pytest.raises` works correctly when given a function and its arguments.

test_raises_does_not_allow_none(self)

**Description:** Validates that passing `None` as the `expected_exception` parameter to `pytest.raises` raises a `ValueError` with an appropriate message.

test_raises_false_and_arg(self)

**Description:** Tests that passing `False` as the expected exception to `pytest.raises` raises a `ValueError` with a detailed explanation about why `False` is invalid.

test_raises_does_not_allow_empty_tuple(self)

**Description:** Ensures that passing an empty tuple as the expected exception raises a `ValueError`.

test_raises_callable_no_exception(self) -> None

**Description:** Checks behavior when a callable that does not raise an exception is passed to `pytest.raises`.

test_raises_falsey_type_error(self) -> None

**Description:** Validates that incorrect usage of `pytest.raises` with falsey patterns triggers a `TypeError`.

test_raises_repr_inflight(self)

**Description:** Tests the string representation (`repr`) of the exception info object while it is inside a `pytest.raises` context manager.

test_raises_as_contextmanager(self, pytester: Pytester) -> None

**Description:** Uses the pytest `Pytester` utility to create and run tests that verify `pytest.raises` as a context manager behaves correctly, including nested usage and exception passing.

test_does_not_raise(self, pytester: Pytester) -> None

**Description:** Tests the usage of `pytest.raises` alongside `contextlib.nullcontext` (aliased as `does_not_raise`) to parametrize test cases that either expect exceptions or no exceptions.

test_does_not_raise_does_raise(self, pytester: Pytester) -> None

**Description:** Inverse of `test_does_not_raise`, ensuring that tests fail appropriately when exceptions do occur but are not expected.

test_raises_with_invalid_regex(self, pytester: Pytester) -> None

**Description:** Confirms that invalid regex patterns passed to the `match` argument produce a helpful error message without a traceback.

test_noclass(self) -> None

**Description:** Tests that passing a non-exception class (a string) to `pytest.raises` raises a `TypeError`.

test_invalid_arguments_to_raises(self) -> None

**Description:** Checks that passing unknown keyword arguments to `pytest.raises` raises a `TypeError`.

test_tuple(self)

**Description:** Tests that `pytest.raises` accepts a tuple of exception types and correctly catches any of them.

test_no_raise_message(self) -> None

**Description:** Verifies that when `pytest.raises` does not catch an expected exception, it raises a special `pytest.fail.Exception` with a descriptive message.

test_raises_cyclic_reference(self, method)

**Description:** Parametrized test ensuring that `pytest.raises` does not introduce reference cycles that would prevent garbage collection.

test_raises_match(self) -> None

**Description:** Extensively tests the regex matching functionality of `pytest.raises`, including string matching, failure messages, warnings on empty strings, and behavior when the wrong exception type is raised.

test_match_failure_string_quoting(self)

**Description:** Ensures that the failure messages when regex matching fails are properly quoted and readable.

test_match_failure_exact_string_message(self)

**Description:** Tests matching with exact string messages containing special characters and advises escaping in failure messages.

test_raises_match_wrong_type(self)

**Description:** Ensures that if a different exception than expected is raised, `pytest.raises` propagates it instead of attempting regex matching.

test_raises_exception_looks_iterable(self)

**Description:** Tests that exceptions with metaclasses that mimic iterable behavior do not cause confusing errors in `pytest.raises`.

test_raises_with_raising_dunder_class(self) -> None

**Description:** Checks behavior when the exception's `__class__` property raises an error, ensuring `pytest.raises` surfaces the issue correctly.

test_raises_context_manager_with_kwargs(self)

**Description:** Tests that passing unexpected keyword arguments to `pytest.raises` when used as a context manager raises a helpful error message.

test_expected_exception_is_not_a_baseexception(self) -> None

**Description:** Checks that the expected exception parameter must be a subclass of `BaseException`; otherwise, `pytest.raises` raises `TypeError` with a clear message.

test_issue_11872(self) -> None

**Description:** Regression test for a specific Python bug (#11872) where `urllib.error.HTTPError` raises `KeyError` on invalid attribute access instead of `AttributeError`.

Important Implementation Details and Algorithms

• Exception Matching:
  The tests heavily rely on regex pattern matching of exception messages (match parameter) to ensure precise control over expected error messages.

• Error Message Wrapping:
  The utility function wrap_escape is used to create exact-match regex patterns by escaping all regex special characters and anchoring the pattern.

• Context Manager Usage:
  Tests verify both functional call style (pytest.raises(Exception, func, *args)) and context manager usage (with pytest.raises(Exception): ...).

• Reference Cycle Checks:
  Some tests check that pytest.raises does not create object reference cycles that would prevent Python's garbage collector from reclaiming memory.

• Use of pytester Fixture:
  Several tests use the pytester fixture, which allows dynamic creation and execution of pytest test files inside the test suite, verifying pytest's behavior in realistic scenarios.

• Exception Info Representation:
  test_raises_repr_inflight ensures that the internal exception information object can be safely printed or logged while still capturing the exception.

Interaction with Other Parts of the System

• pytest Framework:
  This test file depends heavily on the pytest testing framework and its internal modules such as _pytest.outcomes, _pytest.pytester, and _pytest.warning_types.

• pytest.raises Utility:
  The file primarily tests the pytest.raises function and context manager, which is part of the core pytest API.

• Integration with Python's Exception System:
  The tests ensure compatibility with Python's native exception handling, including custom exception classes, metaclasses, and standard exceptions.

• Warnings and Failures:
  Tests check how pytest.raises integrates with pytest's warning system (pytest.warns) and failure system (pytest.fail.Exception).

Visual Diagram

classDiagram
    class TestRaises {
        +test_check_callable()
        +test_raises()
        +test_raises_function()
        +test_raises_does_not_allow_none()
        +test_raises_false_and_arg()
        +test_raises_does_not_allow_empty_tuple()
        +test_raises_callable_no_exception()
        +test_raises_falsey_type_error()
        +test_raises_repr_inflight()
        +test_raises_as_contextmanager(pytester)
        +test_does_not_raise(pytester)
        +test_does_not_raise_does_raise(pytester)
        +test_raises_with_invalid_regex(pytester)
        +test_noclass()
        +test_invalid_arguments_to_raises()
        +test_tuple()
        +test_no_raise_message()
        +test_raises_cyclic_reference(method)
        +test_raises_match()
        +test_match_failure_string_quoting()
        +test_match_failure_exact_string_message()
        +test_raises_match_wrong_type()
        +test_raises_exception_looks_iterable()
        +test_raises_with_raising_dunder_class()
        +test_raises_context_manager_with_kwargs()
        +test_expected_exception_is_not_a_baseexception()
        +test_issue_11872()
    }

    class wrap_escape {
        +wrap_escape(s: str) : str
    }

Summary

The [raises.py](/projects/286/67357) file is a critical component ensuring the reliability and usability of pytest's exception assertion utility, `pytest.raises`. It covers a wide range of test cases from basic usage to edge cases involving regex matching, incorrect parameters, and exception peculiarities. This thorough testing ensures that developers using pytest can confidently assert exceptions in their test suites with clear, helpful feedback when expectations are not met.