Skip to content

Commit 57939d6

Browse files
committed
docs(CHANGES): Document TextFrame features for 0.52.x (#613)
why: Document new features for release notes. what: - TextFrame primitive for terminal UI testing - pytest assertion hook with rich diff output - syrupy snapshot extension with .frame files - Optional install via libtmux[textframe]
1 parent 6f76982 commit 57939d6

File tree

1 file changed

+65
-0
lines changed

1 file changed

+65
-0
lines changed

CHANGES

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,71 @@ $ uvx --from 'libtmux' --prerelease allow python
3232

3333
<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
3434

35+
### New features
36+
37+
#### TextFrame primitive (#613)
38+
39+
New {class}`~libtmux.textframe.TextFrame` dataclass for testing terminal UI output.
40+
Provides a fixed-size ASCII frame simulator with overflow detection - useful for
41+
validating `capture_pane()` output and terminal rendering in tests.
42+
43+
```python
44+
from libtmux.textframe import TextFrame
45+
46+
frame = TextFrame(content_width=10, content_height=2)
47+
frame.set_content(["hello", "world"])
48+
print(frame.render())
49+
# +----------+
50+
# |hello |
51+
# |world |
52+
# +----------+
53+
```
54+
55+
**Features:**
56+
57+
- Configurable dimensions with `content_width` and `content_height`
58+
- Overflow handling: `overflow_behavior="error"` raises {class}`~libtmux.textframe.ContentOverflowError`
59+
with visual diagnostic, `overflow_behavior="truncate"` clips content silently
60+
- Dimension validation via `__post_init__`
61+
62+
#### pytest assertion hook for TextFrame (#613)
63+
64+
Rich assertion output when comparing {class}`~libtmux.textframe.TextFrame` objects.
65+
Shows dimension mismatches and line-by-line content diffs using `difflib.ndiff`.
66+
67+
```
68+
TextFrame comparison failed:
69+
width: 20 != 10
70+
Content diff:
71+
- +----------+
72+
+ +--------------------+
73+
```
74+
75+
#### syrupy snapshot extension for TextFrame (#613)
76+
77+
{class}`~libtmux.textframe.TextFrameExtension` stores snapshots as `.frame` files -
78+
one file per test for cleaner git diffs.
79+
80+
**Installation:**
81+
82+
```console
83+
$ pip install libtmux[textframe]
84+
```
85+
86+
**Usage:**
87+
88+
```python
89+
from libtmux.textframe import TextFrame
90+
91+
def test_pane_output(textframe_snapshot):
92+
frame = TextFrame(content_width=20, content_height=5)
93+
frame.set_content(["Hello", "World"])
94+
assert frame == textframe_snapshot
95+
```
96+
97+
The `textframe_snapshot` fixture and assertion hooks are auto-discovered via
98+
pytest's `pytest11` entry point when the `textframe` extra is installed.
99+
35100
## libtmux 0.52.1 (2025-12-07)
36101

37102
### CI

0 commit comments

Comments
 (0)