TextFrame: Terminal UI testing primitive with pytest/syrupy integration

[tony]

Adds libtmux.textframe, a fixed-size ASCII frame simulator for testing terminal UI output. Useful for validating capture_pane() output and terminal rendering in tests.

Install: pip install libtmux[textframe]

Features

TextFrame primitive

A dataclass for creating fixed-dimension ASCII frames with overflow detection:

from libtmux.textframe import TextFrame

frame = TextFrame(content_width=10, content_height=2)
frame.set_content(["hello", "world"])
print(frame.render())
# +----------+
# |hello     |
# |world     |
# +----------+

• Configurable overflow_behavior: "error" (raises with visual diagnostic) or "truncate" (clips silently)
• Dimension validation via __post_init__

Pane.capture_frame()

High-level method that wraps capture_pane() and returns a TextFrame:

def test_cli_output(pane, textframe_snapshot):
    pane.send_keys("echo 'Hello'", enter=True)

    # Wait for output, then capture as frame
    frame = pane.capture_frame(content_width=40, content_height=10)
    assert frame == textframe_snapshot

• Defaults to pane dimensions when width/height not specified
• Uses overflow_behavior="truncate" by default for CI robustness

pytest assertion hook

Rich diff output when comparing TextFrame objects:

TextFrame comparison failed:
  width: 20 != 10
Content diff:
- +----------+
+ +--------------------+

syrupy snapshot extension

TextFrameExtension stores snapshots as .frame files - one file per test for cleaner git diffs:

def test_pane_output(textframe_snapshot):
    frame = TextFrame(content_width=20, content_height=5)
    frame.set_content(["Hello", "World"])
    assert frame == textframe_snapshot

Plugin discovery

Registered via pytest11 entry point - fixtures and hooks are auto-discovered when libtmux[textframe] is installed.

[project.entry-points.pytest11]
libtmux-textframe = "libtmux.textframe.plugin"

[project.optional-dependencies]
textframe = ["syrupy>=4.0.0"]

Files changed

Path	Description
src/libtmux/pane.py	Add capture_frame() method
src/libtmux/textframe/__init__.py	Public API exports
src/libtmux/textframe/core.py	TextFrame dataclass, ContentOverflowError
src/libtmux/textframe/plugin.py	Syrupy extension, pytest hooks, textframe_snapshot fixture
pyproject.toml	Entry point + optional dependency
docs/internals/textframe.md	Documentation
tests/textframe/	TextFrame test suite with snapshot baselines
tests/test_pane_capture_frame.py	capture_frame() integration tests (12 tests)

See also

• Another snapshot PR, similar to WIP: Snapshot #587

[codecov]

Codecov Report

❌ Patch coverage is 54.72973% with 67 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.06%. Comparing base (81d55fa) to head (9791daa).

Files with missing lines	Patch %	Lines
src/libtmux/textframe/core.py	59.81%	37 Missing and 6 partials ⚠️
src/libtmux/textframe/plugin.py	20.68%	22 Missing and 1 partial ⚠️
src/libtmux/pane.py	88.88%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #613      +/-   ##
==========================================
+ Coverage   46.58%   47.06%   +0.47%     
==========================================
  Files          22       25       +3     
  Lines        2372     2520     +148     
  Branches      390      417      +27     
==========================================
+ Hits         1105     1186      +81     
- Misses       1098     1158      +60     
- Partials      169      176       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[tony]

Code review

Found 1 issue:

1. ImportError for users without libtmux[textframe] installed: The __init__.py unconditionally imports TextFrameExtension from plugin.py, which requires syrupy. This causes pane.capture_frame() to fail with an ImportError for users who haven't installed the optional dependency.

libtmux/src/libtmux/textframe/__init__.py

Lines 5 to 8 in d335fc9

	from libtmux.textframe.core import ContentOverflowError, TextFrame
	from libtmux.textframe.plugin import TextFrameExtension
	__all__ = ["ContentOverflowError", "TextFrame", "TextFrameExtension"]

The import chain is:

• pane.capture_frame() imports from libtmux.textframe import TextFrame
• __init__.py line 6 imports TextFrameExtension from plugin.py
• plugin.py lines 17-19 unconditionally import pytest and syrupy

Suggested fix: Make the TextFrameExtension import conditional, or move it to a separate module that's only imported when needed.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}