test_compat.py

Overview

`test_compat.py` is a test suite designed to validate utility functions and compatibility helpers primarily related to function unwrapping, safe attribute access, class type checks, cached properties, and exhaustive type checking assertions. The file contains multiple test cases that ensure the correctness and robustness of these utilities, many of which are imported from the `_pytest.compat` module. The tests cover scenarios such as handling decorator wrappers, partial functions, exception safety in attribute access, verifying `cached_property` behavior, and asserting unreachable code paths with `assert_never`.

This file plays a critical role in verifying foundational helper functions that are leveraged across the pytest codebase to maintain compatibility and correctness in complex runtime scenarios, such as decorator chains and safe introspection.

Detailed Explanation of Components

Functions

test_real_func_loop_limit() -> None

• Purpose:
  Tests that get_real_func detects and raises an error on infinite wrapper loops when unwrapping a heavily self-referential object.

• How it works:
  Defines a local class Evil that returns itself repeatedly via __getattr__, simulating an infinite recursive wrapper chain. The test verifies that get_real_func(evil) raises a ValueError indicating a wrapper loop.

• Usage Example:

  test_real_func_loop_limit()
  

• Important details:
  This test ensures that get_real_func contains a loop detection mechanism to prevent infinite recursion when unwrapping decorators or proxies.

test_get_real_func() -> None

• Purpose:
  Validates that get_real_func correctly unwraps multiple layers of decorators to retrieve the original undecorated function.

• How it works:
  Defines a simple decorator using wraps, wraps a function multiple times, then asserts that get_real_func returns the original function. It also tests compatibility with a pytest fixture wrapper.

• Usage Example:

  test_get_real_func()
  

• Important details:
  This test confirms get_real_func works with both standard decorator chains and pytest's internal fixture wrappers.

test_get_real_func_partial() -> None

• Purpose:
  Tests that get_real_func handles functools.partial objects by unwrapping them correctly to their base function.

• How it works:
  Defines a function foo, wraps it with partial, and verifies that get_real_func returns the original foo function.

• Usage Example:

  test_get_real_func_partial()
  

test_helper_failures() -> None

• Purpose:
  Verifies that exceptions raised by properties in the ErrorsHelper class behave as expected, specifically which exceptions are caught and which propagate.

• How it works:
  Instantiates ErrorsHelper and asserts that:

  • Accessing raise_exception raises an Exception.

  • Accessing raise_fail_outcome raises OutcomeException (pytest's failure exception).

  • Accessing raise_baseexception is not tested here because it raises BaseException which should propagate.

• Usage Example:

  test_helper_failures()
  

test_safe_getattr() -> None

• Purpose:
  Tests the safe_getattr utility which safely gets an attribute but returns a default if certain exceptions are raised.

• How it works:
  Uses ErrorsHelper properties that raise exceptions. Verifies that safe_getattr returns the default value for Exception and OutcomeException but propagates BaseException.

• Usage Example:

  test_safe_getattr()
  

test_safe_isclass() -> None

• Purpose:
  Tests the safe_isclass function which determines if an object is a class, handling cases where __class__ is overridden unsafely.

• How it works:
  Checks that safe_isclass(type) returns True. Defines a class with a __class__ property that raises an assertion failure if accessed, and confirms safe_isclass returns False for its instance without triggering the assertion.

• Usage Example:

  test_safe_isclass()
  

test_cached_property() -> None

• Purpose:
  Tests the behavior of Python's functools.cached_property decorator.

• How it works:
  Defines a class with a cached_property that increments a counter each time it is computed. Verifies that the property is computed once per instance and cached thereafter.

• Usage Example:

  test_cached_property()
  

test_assert_never_union() -> None

• Purpose:
  Tests the assert_never function to ensure it raises AssertionError for unexpected union type values.

• How it works:
  Defines a variable with type int | str. Checks that when the value is an int or str, no assertion is raised, but if a branch is missing, assert_never triggers an error.

• Usage Example:

  test_assert_never_union()
  

test_assert_never_enum() -> None

• Purpose:
  Validates assert_never behavior with enum types.

• How it works:
  Defines an enum E with two members a and b. Tests that assert_never raises when an enum value is not handled explicitly.

• Usage Example:

  test_assert_never_enum()
  

test_assert_never_literal() -> None

• Purpose:
  Tests assert_never on Literal types.

• How it works:
  Uses a variable typed as Literal["a", "b"]. Verifies that missing branches raise AssertionError via assert_never.

• Usage Example:

  test_assert_never_literal()
  

Class

ErrorsHelper

• Description:
  A utility class used to raise different types of exceptions from properties to test exception handling in safe attribute access and failure scenarios.

• Properties:

  • raise_baseexception: property
    Raises a BaseException when accessed. Represents critical exceptions that should not be caught by safe attribute access.

  • raise_exception: property
    Raises a general Exception when accessed. Simulates typical exceptions that should be caught.

  • raise_fail_outcome: property
    Calls pytest.fail(), raising an OutcomeException to simulate pytest test failure exceptions.

• Usage Example:

  helper = ErrorsHelper()
  try:
      helper.raise_exception
  except Exception:
      print("Exception caught")
  
  try:
      helper.raise_fail_outcome
  except OutcomeException:
      print("Test failure caught")
  
  # Accessing raise_baseexception will propagate BaseException
  

Important Implementation Details and Algorithms

• Function Unwrapping (get_real_func):
  The tests emphasize the importance of correctly unwrapping wrapped functions, including chained decorators and partial objects, without causing infinite recursion. The test_real_func_loop_limit highlights a safeguard against infinite loops by raising a ValueError.

• Safe Attribute Access (safe_getattr):
  Designed to safely access object attributes while catching non-critical exceptions (Exception and OutcomeException) but allowing critical exceptions (BaseException) to propagate.

• Safe Class Detection (safe_isclass):
  Avoids unsafe __class__ attribute access that could raise errors; useful in dynamically typed or proxy-heavy environments.

• Exhaustive Type Checking (assert_never):
  Used to assert that all possible cases of a union, enum, or literal type are handled. If an unexpected value is encountered, it raises an AssertionError. This provides a runtime safety net for exhaustive type checks that static type checkers enforce at type-checking time.

Interaction with Other Parts of the System

• Imports multiple compatibility utilities from _pytest.compat, such as assert_never, get_real_func, safe_getattr, and safe_isclass. These are core helpers used throughout the pytest framework for safe introspection and compatibility.

• Uses pytest and pytest.fail to verify behavior related to test outcomes and exceptions.

• OutcomeException from _pytest.outcomes is used to distinguish pytest test failure exceptions from other exceptions.

• This file itself is a test module and thus interacts indirectly with the rest of the pytest test suite, ensuring the reliability of helper functions used elsewhere.

Visual Diagram: Function Relationships Flowchart

flowchart TD
    A[get_real_func] -->|unwraps| B[decorator chain]
    A -->|unwraps| C[functools.partial]
    D[test_real_func_loop_limit] --> A
    E[test_get_real_func] --> A
    F[test_get_real_func_partial] --> A

    G[safe_getattr] --> H[ErrorsHelper properties]
    I[test_safe_getattr] --> G
    I --> H

    J[safe_isclass] --> K[Class or Instance]
    L[test_safe_isclass] --> J
    L --> K

    M[assert_never] --> N[Union, Enum, Literal]
    O[test_assert_never_union] --> M
    P[test_assert_never_enum] --> M
    Q[test_assert_never_literal] --> M

    R[cached_property] --> S[Class property caching]
    T[test_cached_property] --> R

    U[ErrorsHelper] --> H
    V[test_helper_failures] --> H

Summary

`test_compat.py` is a comprehensive test module validating critical compatibility utilities in the pytest framework. It covers safe function unwrapping, handling of partial functions, safe attribute access amidst exceptions, proper class detection, cached property behavior, and exhaustive type checking assertions. The file ensures these utilities perform reliably under edge cases such as infinite decorator loops, unusual class implementations, and various exception types. This testing is vital for the robustness of pytest's internal compatibility layer, influencing many areas of the testing framework.