frozen_dataclass(test): Enhance test suite with NamedTuple parametrized tests

why: Improve test coverage and documentation of security considerations

what: - Add NamedTuple-based parametrized tests for dimensions, frozen flag, and inheritance - Discover and document security vulnerability with _frozen flag reassignment - Add test cases for edge dimensions (zero, negative, large values) - Improve type annotations for better static analysis

All tests pass: 14 pytest tests and 22 doctests confirm functionality

Author: tony

src/libtmux/_internal/frozen_dataclass.py

@@ -86,6 +86,23 @@ def frozen_dataclass(cls: type[_T]) -> type[_T]:
     ... except AttributeError as e:
     ...     print(f"Error: {e}")
     Error: ImmutableSub is immutable: cannot modify field 'value'
+    
+    Security consideration - modifying the _frozen flag:
+    
+    >>> @frozen_dataclass
+    ... class SecureData:
+    ...     secret: str
+    >>> data = SecureData(secret="password123")
+    >>> try:
+    ...     data.secret = "hacked"
+    ... except AttributeError as e:
+    ...     print(f"Protected: {e}")
+    Protected: SecureData is immutable: cannot modify field 'secret'
+    >>> # However, the _frozen flag can be modified to bypass protection:
+    >>> data._frozen = False
+    >>> data.secret = "hacked"
+    >>> data.secret
+    'hacked'
     """
     # A. Convert to a dataclass with frozen=False
     cls = dataclasses.dataclass(cls)

tests/_internal/test_frozen_dataclass.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import dataclasses
+import typing as t
 from datetime import datetime
 
 import pytest
@@ -181,3 +182,231 @@ def test_bidirectional_references() -> None:
     # This is a "leaky abstraction" in Python's immutability model
     # In real code, consider using immutable collections (tuple, frozenset)
     # or deep freezing containers
+
+
+# NamedTuple-based parametrized tests
+# ----------------------------------
+
+
+class DimensionTestCase(t.NamedTuple):
+    """Test fixture for validating dimensions in PaneSnapshot."""
+
+    test_id: str
+    width: int
+    height: int
+    expected_error: bool
+    error_match: str | None = None
+
+
+DIMENSION_TEST_CASES: list[DimensionTestCase] = [
+    DimensionTestCase(
+        test_id="standard_dimensions",
+        width=80,
+        height=24,
+        expected_error=False,
+    ),
+    DimensionTestCase(
+        test_id="zero_dimensions",
+        width=0,
+        height=0,
+        expected_error=False,
+    ),
+    DimensionTestCase(
+        test_id="negative_dimensions",
+        width=-10,
+        height=-5,
+        expected_error=False,
+    ),
+    DimensionTestCase(
+        test_id="extreme_dimensions",
+        width=9999,
+        height=9999,
+        expected_error=False,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(DimensionTestCase._fields),
+    DIMENSION_TEST_CASES,
+    ids=[test.test_id for test in DIMENSION_TEST_CASES],
+)
+def test_snapshot_dimensions(
+    test_id: str, width: int, height: int, expected_error: bool, error_match: str | None
+) -> None:
+    """Test PaneSnapshot initialization with various dimensions."""
+    # Initialize the PaneSnapshot
+    pane = PaneSnapshot(pane_id="test", width=width, height=height)
+
+    # Verify dimensions were set correctly
+    assert pane.width == width
+    assert pane.height == height
+
+    # Verify immutability
+    with pytest.raises(AttributeError, match="immutable"):
+        pane.width = 100  # type: ignore
+
+
+class FrozenFlagTestCase(t.NamedTuple):
+    """Test fixture for testing _frozen flag behavior."""
+
+    test_id: str
+    unfreeze_attempt: bool
+    expect_mutation_error: bool
+    error_match: str | None = None
+
+
+FROZEN_FLAG_TEST_CASES: list[FrozenFlagTestCase] = [
+    FrozenFlagTestCase(
+        test_id="attempt_unfreeze",
+        unfreeze_attempt=True,
+        expect_mutation_error=False,
+        error_match=None,
+    ),
+    FrozenFlagTestCase(
+        test_id="no_unfreeze_attempt",
+        unfreeze_attempt=False,
+        expect_mutation_error=True,
+        error_match="immutable.*cannot modify field",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(FrozenFlagTestCase._fields),
+    FROZEN_FLAG_TEST_CASES,
+    ids=[test.test_id for test in FROZEN_FLAG_TEST_CASES],
+)
+def test_frozen_flag(
+    test_id: str,
+    unfreeze_attempt: bool,
+    expect_mutation_error: bool,
+    error_match: str | None,
+) -> None:
+    """Test behavior when attempting to manipulate the _frozen flag.
+
+    Note: We discovered that setting _frozen=False actually allows mutation,
+    which could be a potential security issue if users know about this behavior.
+    In a more secure implementation, the _frozen attribute might need additional
+    protection to prevent this bypass mechanism.
+    """
+    # Create a frozen dataclass
+    pane = PaneSnapshot(pane_id="test_frozen", width=80, height=24)
+
+    # Attempt to unfreeze if requested
+    if unfreeze_attempt:
+        pane._frozen = False  # type: ignore
+
+    # Attempt mutation and check if it fails as expected
+    if expect_mutation_error:
+        with pytest.raises(AttributeError, match=error_match):
+            pane.width = 200  # type: ignore
+    else:
+        pane.width = 200  # type: ignore
+        assert pane.width == 200
+
+
+class MutationMethodTestCase(t.NamedTuple):
+    """Test fixture for testing mutation methods."""
+
+    test_id: str
+    method_name: str
+    args: tuple[t.Any, ...]
+    error_type: type[Exception]
+    error_match: str
+
+
+MUTATION_METHOD_TEST_CASES: list[MutationMethodTestCase] = [
+    MutationMethodTestCase(
+        test_id="resize_method",
+        method_name="resize",
+        args=(100, 50),
+        error_type=NotImplementedError,
+        error_match="immutable.*resize.*not allowed",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(MutationMethodTestCase._fields),
+    MUTATION_METHOD_TEST_CASES,
+    ids=[test.test_id for test in MUTATION_METHOD_TEST_CASES],
+)
+def test_mutation_methods(
+    test_id: str,
+    method_name: str,
+    args: tuple[t.Any, ...],
+    error_type: type[Exception],
+    error_match: str,
+) -> None:
+    """Test that methods attempting to modify state raise appropriate exceptions."""
+    # Create a frozen dataclass
+    pane = PaneSnapshot(pane_id="test_methods", width=80, height=24)
+
+    # Get the method and attempt to call it
+    method = getattr(pane, method_name)
+    with pytest.raises(error_type, match=error_match):
+        method(*args)
+
+
+class InheritanceTestCase(t.NamedTuple):
+    """Test fixture for testing inheritance behavior."""
+
+    test_id: str
+    create_base: bool
+    mutate_base: bool
+    mutate_derived: bool
+    expect_base_error: bool
+    expect_derived_error: bool
+
+
+INHERITANCE_TEST_CASES: list[InheritanceTestCase] = [
+    InheritanceTestCase(
+        test_id="mutable_base_immutable_derived",
+        create_base=True,
+        mutate_base=True,
+        mutate_derived=True,
+        expect_base_error=False,
+        expect_derived_error=True,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(InheritanceTestCase._fields),
+    INHERITANCE_TEST_CASES,
+    ids=[test.test_id for test in INHERITANCE_TEST_CASES],
+)
+def test_inheritance_behavior(
+    test_id: str,
+    create_base: bool,
+    mutate_base: bool,
+    mutate_derived: bool,
+    expect_base_error: bool,
+    expect_derived_error: bool,
+) -> None:
+    """Test inheritance behavior with mutable base class and immutable derived class."""
+    # Create base class if requested
+    if create_base:
+        base = BasePane(pane_id="base", width=80, height=24)
+
+    # Create derived class
+    derived = PaneSnapshot(pane_id="derived", width=80, height=24)
+
+    # Attempt to mutate base class if requested
+    if create_base and mutate_base:
+        if expect_base_error:
+            with pytest.raises(AttributeError):
+                base.width = 100
+        else:
+            base.width = 100
+            assert base.width == 100
+
+    # Attempt to mutate derived class if requested
+    if mutate_derived:
+        if expect_derived_error:
+            with pytest.raises(AttributeError):
+                derived.width = 100  # type: ignore
+        else:
+            derived.width = 100  # type: ignore
+            assert derived.width == 100