|
| 1 | +"""Syrupy snapshot extension and pytest hooks for TextFrame. |
| 2 | +
|
| 3 | +This module provides: |
| 4 | +- TextFrameExtension: A syrupy extension for .frame snapshot files |
| 5 | +- pytest_assertrepr_compare: Rich assertion output for TextFrame comparisons |
| 6 | +- textframe_snapshot: Pre-configured snapshot fixture |
| 7 | +
|
| 8 | +When installed via `pip install libtmux[textframe]`, this plugin is |
| 9 | +auto-discovered by pytest through the pytest11 entry point. |
| 10 | +""" |
| 11 | + |
| 12 | +from __future__ import annotations |
| 13 | + |
| 14 | +import typing as t |
| 15 | +from difflib import ndiff |
| 16 | + |
| 17 | +import pytest |
| 18 | +from syrupy.assertion import SnapshotAssertion |
| 19 | +from syrupy.extensions.single_file import SingleFileSnapshotExtension, WriteMode |
| 20 | + |
| 21 | +from libtmux.textframe.core import ContentOverflowError, TextFrame |
| 22 | + |
| 23 | + |
| 24 | +class TextFrameExtension(SingleFileSnapshotExtension): |
| 25 | + """Single-file extension for TextFrame snapshots (.frame files). |
| 26 | +
|
| 27 | + Each test snapshot is stored in its own .frame file, providing cleaner |
| 28 | + git diffs compared to the multi-snapshot .ambr format. |
| 29 | +
|
| 30 | + Notes |
| 31 | + ----- |
| 32 | + This extension serializes: |
| 33 | + - TextFrame objects → their render() output |
| 34 | + - ContentOverflowError → their overflow_visual attribute |
| 35 | + - Other types → str() representation |
| 36 | + """ |
| 37 | + |
| 38 | + _write_mode = WriteMode.TEXT |
| 39 | + file_extension = "frame" |
| 40 | + |
| 41 | + def serialize( |
| 42 | + self, |
| 43 | + data: t.Any, |
| 44 | + *, |
| 45 | + exclude: t.Any = None, |
| 46 | + include: t.Any = None, |
| 47 | + matcher: t.Any = None, |
| 48 | + ) -> str: |
| 49 | + """Serialize data to ASCII frame representation. |
| 50 | +
|
| 51 | + Parameters |
| 52 | + ---------- |
| 53 | + data : Any |
| 54 | + The data to serialize. |
| 55 | + exclude : Any |
| 56 | + Properties to exclude (unused for TextFrame). |
| 57 | + include : Any |
| 58 | + Properties to include (unused for TextFrame). |
| 59 | + matcher : Any |
| 60 | + Custom matcher (unused for TextFrame). |
| 61 | +
|
| 62 | + Returns |
| 63 | + ------- |
| 64 | + str |
| 65 | + ASCII representation of the data. |
| 66 | + """ |
| 67 | + if isinstance(data, TextFrame): |
| 68 | + return data.render() |
| 69 | + if isinstance(data, ContentOverflowError): |
| 70 | + return data.overflow_visual |
| 71 | + return str(data) |
| 72 | + |
| 73 | + |
| 74 | +# pytest hooks (auto-discovered via pytest11 entry point) |
| 75 | + |
| 76 | + |
| 77 | +def pytest_assertrepr_compare( |
| 78 | + config: pytest.Config, |
| 79 | + op: str, |
| 80 | + left: t.Any, |
| 81 | + right: t.Any, |
| 82 | +) -> list[str] | None: |
| 83 | + """Provide rich assertion output for TextFrame comparisons. |
| 84 | +
|
| 85 | + This hook provides detailed diff output when two TextFrame objects |
| 86 | + are compared with ==, showing dimension mismatches and content diffs. |
| 87 | +
|
| 88 | + Parameters |
| 89 | + ---------- |
| 90 | + config : pytest.Config |
| 91 | + The pytest configuration object. |
| 92 | + op : str |
| 93 | + The comparison operator (e.g., "==", "!="). |
| 94 | + left : Any |
| 95 | + The left operand of the comparison. |
| 96 | + right : Any |
| 97 | + The right operand of the comparison. |
| 98 | +
|
| 99 | + Returns |
| 100 | + ------- |
| 101 | + list[str] | None |
| 102 | + List of explanation lines, or None to use default behavior. |
| 103 | + """ |
| 104 | + if not isinstance(left, TextFrame) or not isinstance(right, TextFrame): |
| 105 | + return None |
| 106 | + if op != "==": |
| 107 | + return None |
| 108 | + |
| 109 | + lines = ["TextFrame comparison failed:"] |
| 110 | + |
| 111 | + # Dimension mismatch |
| 112 | + if left.content_width != right.content_width: |
| 113 | + lines.append(f" width: {left.content_width} != {right.content_width}") |
| 114 | + if left.content_height != right.content_height: |
| 115 | + lines.append(f" height: {left.content_height} != {right.content_height}") |
| 116 | + |
| 117 | + # Content diff |
| 118 | + left_render = left.render().splitlines() |
| 119 | + right_render = right.render().splitlines() |
| 120 | + if left_render != right_render: |
| 121 | + lines.append("") |
| 122 | + lines.append("Content diff:") |
| 123 | + lines.extend(ndiff(right_render, left_render)) |
| 124 | + |
| 125 | + return lines |
| 126 | + |
| 127 | + |
| 128 | +@pytest.fixture |
| 129 | +def textframe_snapshot(snapshot: SnapshotAssertion) -> SnapshotAssertion: |
| 130 | + """Snapshot fixture configured with TextFrameExtension. |
| 131 | +
|
| 132 | + This fixture is auto-discovered when libtmux[textframe] is installed. |
| 133 | + It provides a pre-configured snapshot for TextFrame objects. |
| 134 | +
|
| 135 | + Parameters |
| 136 | + ---------- |
| 137 | + snapshot : SnapshotAssertion |
| 138 | + The default syrupy snapshot fixture. |
| 139 | +
|
| 140 | + Returns |
| 141 | + ------- |
| 142 | + SnapshotAssertion |
| 143 | + Snapshot configured with TextFrame serialization. |
| 144 | +
|
| 145 | + Examples |
| 146 | + -------- |
| 147 | + >>> def test_my_frame(textframe_snapshot): |
| 148 | + ... frame = TextFrame(content_width=10, content_height=2) |
| 149 | + ... frame.set_content(["hello", "world"]) |
| 150 | + ... assert frame == textframe_snapshot |
| 151 | + """ |
| 152 | + return snapshot.use_extension(TextFrameExtension) |
0 commit comments