Skip to content

Commit 1583584

Browse files
tonytony
committed
docs(snapshots): rewrite doctests to use real fixtures and ELLIPSIS
why: original snapshot/topics docs had doctests with hardcoded outputs ($ echo "Hello World", fixed pane IDs like %1, fixed timestamps) that could never match real fixture pane content. Each doctest block also referenced 'snapshot' from a previous block, but pytest-doctest-docutils doesn't share state across markdown code blocks — every block needs to define its own variables. As a result all 10 examples failed at parse or execution time. what: - replace hardcoded output expectations with structural assertions (isinstance, 'in' membership, startswith) that work against any real pane content - explicitly redefine 'snapshot = pane.snapshot()' at the top of each block that uses it, since doctest blocks don't share state - add 'import datetime' to the recording block so the time-filter example actually runs - use 'datetime.timezone.utc' instead of unaware datetime to match the timestamp the snapshot stores - use ELLIPSIS to match the variable pane_id ('%...')
1 parent 034ef75 commit 1583584

2 files changed

Lines changed: 65 additions & 103 deletions

File tree

‎docs/api/snapshot.md‎

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -59,12 +59,11 @@ The snapshot module provides functionality for capturing and analyzing the state
5959
### Basic Snapshot
6060

6161
```python
62-
>>> pane = session.active_window.active_pane
6362
>>> snapshot = pane.snapshot()
64-
>>> print(snapshot.content_str)
65-
$ echo "Hello World"
66-
Hello World
67-
$
63+
>>> snapshot.pane_id # doctest: +ELLIPSIS
64+
'%...'
65+
>>> isinstance(snapshot.content_str, str)
66+
True
6867
```
6968

7069
### Recording Activity
@@ -74,38 +73,32 @@ $
7473
>>> recording.add_snapshot(pane)
7574
>>> pane.send_keys("echo 'Hello'")
7675
>>> recording.add_snapshot(pane)
77-
>>> print(recording.latest.content_str)
78-
$ echo 'Hello'
79-
Hello
80-
$
76+
>>> isinstance(recording.latest.content_str, str)
77+
True
78+
>>> len(recording) >= 2
79+
True
8180
```
8281

8382
### Using Output Adapters
8483

8584
```python
8685
>>> from libtmux.snapshot import TerminalOutputAdapter
87-
>>> print(snapshot.format(TerminalOutputAdapter()))
88-
=== Pane Snapshot ===
89-
Pane: %1
90-
Window: @1
91-
Session: $1
92-
Server: default
93-
Timestamp: 2024-01-01T12:00:00Z
94-
=== Content ===
95-
$ echo "Hello World"
96-
Hello World
97-
$
86+
>>> snapshot = pane.snapshot()
87+
>>> formatted = snapshot.format(TerminalOutputAdapter())
88+
>>> '=== Pane Snapshot ===' in formatted
89+
True
90+
>>> '=== Content ===' in formatted
91+
True
9892
```
9993

10094
### Custom Adapter
10195

10296
```python
103-
>>> from libtmux.snapshot import SnapshotOutputAdapter
97+
>>> from libtmux.snapshot import SnapshotOutputAdapter, PaneSnapshot
98+
>>> snapshot = pane.snapshot()
10499
>>> class MyAdapter(SnapshotOutputAdapter):
105-
... def format(self, snapshot):
106-
... return f"Content: {snapshot.content_str}"
107-
>>> print(snapshot.format(MyAdapter()))
108-
Content: $ echo "Hello World"
109-
Hello World
110-
$
100+
... def format(self, snapshot: PaneSnapshot) -> str:
101+
... return f"Content: {snapshot.content_str[:20]}"
102+
>>> snapshot.format(MyAdapter()).startswith('Content:')
103+
True
111104
```

‎docs/topics/snapshots.md‎

Lines changed: 45 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,11 @@ libtmux provides functionality to capture and analyze the state of tmux panes th
99
A snapshot captures the content and metadata of a pane at a specific point in time:
1010

1111
```python
12-
>>> pane = session.active_window.active_pane
1312
>>> snapshot = pane.snapshot()
14-
>>> print(snapshot.content_str)
15-
$ echo "Hello World"
16-
Hello World
17-
$
13+
>>> snapshot.pane_id # doctest: +ELLIPSIS
14+
'%...'
15+
>>> isinstance(snapshot.content_str, str)
16+
True
1817
```
1918

2019
Snapshots are immutable and include:
@@ -28,12 +27,18 @@ You can also capture specific ranges of the pane history:
2827
```python
2928
>>> # Capture lines 1-3 only
3029
>>> snapshot = pane.snapshot(start=1, end=3)
30+
>>> isinstance(snapshot.content_str, str)
31+
True
3132

3233
>>> # Capture from start of history
3334
>>> snapshot = pane.snapshot(start="-")
35+
>>> isinstance(snapshot.content_str, str)
36+
True
3437

3538
>>> # Capture up to current view
3639
>>> snapshot = pane.snapshot(end="-")
40+
>>> isinstance(snapshot.content_str, str)
41+
True
3742
```
3843

3944
## Recording Pane Activity
@@ -49,14 +54,19 @@ To track changes in a pane over time, use recordings:
4954
>>> recording.add_snapshot(pane)
5055

5156
>>> # Access snapshots
52-
>>> print(recording[0].content_str) # First snapshot
53-
>>> print(recording.latest.content_str) # Most recent
57+
>>> isinstance(recording[0].content_str, str)
58+
True
59+
>>> isinstance(recording.latest.content_str, str)
60+
True
5461

5562
>>> # Filter by time
63+
>>> import datetime
5664
>>> recent = recording.get_snapshots_between(
57-
... start_time=datetime.datetime.now() - datetime.timedelta(minutes=5),
58-
... end_time=datetime.datetime.now(),
65+
... start_time=datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(minutes=5),
66+
... end_time=datetime.datetime.now(datetime.timezone.utc),
5967
... )
68+
>>> isinstance(recent, list)
69+
True
6070
```
6171

6272
## Output Formats
@@ -67,96 +77,55 @@ Snapshots can be formatted in different ways for various use cases:
6777

6878
```python
6979
>>> from libtmux.snapshot import TerminalOutputAdapter
70-
>>> print(snapshot.format(TerminalOutputAdapter()))
71-
=== Pane Snapshot ===
72-
Pane: %1
73-
Window: @1
74-
Session: $1
75-
Server: default
76-
Timestamp: 2024-01-01T12:00:00Z
77-
=== Content ===
78-
$ echo "Hello World"
79-
Hello World
80-
$
80+
>>> snapshot = pane.snapshot()
81+
>>> formatted = snapshot.format(TerminalOutputAdapter())
82+
>>> '=== Pane Snapshot ===' in formatted
83+
True
84+
>>> '=== Content ===' in formatted
85+
True
8186
```
8287

8388
### CLI Output (No Colors)
8489

8590
```python
8691
>>> from libtmux.snapshot import CLIOutputAdapter
87-
>>> print(snapshot.format(CLIOutputAdapter()))
88-
=== Pane Snapshot ===
89-
Pane: %1
90-
Window: @1
91-
Session: $1
92-
Server: default
93-
Timestamp: 2024-01-01T12:00:00Z
94-
=== Content ===
95-
$ echo "Hello World"
96-
Hello World
97-
$
92+
>>> snapshot = pane.snapshot()
93+
>>> formatted = snapshot.format(CLIOutputAdapter())
94+
>>> '=== Pane Snapshot ===' in formatted
95+
True
9896
```
9997

10098
### Pytest Assertion Diffs
10199

102100
```python
103101
>>> from libtmux.snapshot import PytestDiffAdapter
104-
>>> expected = """
105-
... PaneSnapshot(
106-
... pane_id='%1',
107-
... window_id='@1',
108-
... session_id='$1',
109-
... server_name='default',
110-
... timestamp='2024-01-01T12:00:00Z',
111-
... content=[
112-
... '$ echo "Hello World"',
113-
... 'Hello World',
114-
... '$',
115-
... ],
116-
... metadata={
117-
... 'pane_height': '24',
118-
... 'pane_width': '80',
119-
... },
120-
... )
121-
... """
122-
>>> assert snapshot.format(PytestDiffAdapter()) == expected
102+
>>> snapshot = pane.snapshot()
103+
>>> formatted = snapshot.format(PytestDiffAdapter())
104+
>>> 'PaneSnapshot(' in formatted
105+
True
123106
```
124107

125108
### Syrupy Snapshot Testing
126109

127110
```python
128111
>>> from libtmux.snapshot import SyrupySnapshotAdapter
129-
>>> snapshot.format(SyrupySnapshotAdapter())
130-
{
131-
"pane_id": "%1",
132-
"window_id": "@1",
133-
"session_id": "$1",
134-
"server_name": "default",
135-
"timestamp": "2024-01-01T12:00:00Z",
136-
"content": [
137-
"$ echo \"Hello World\"",
138-
"Hello World",
139-
"$"
140-
],
141-
"metadata": {
142-
"pane_height": "24",
143-
"pane_width": "80"
144-
}
145-
}
112+
>>> snapshot = pane.snapshot()
113+
>>> formatted = snapshot.format(SyrupySnapshotAdapter())
114+
>>> 'pane_id' in formatted
115+
True
146116
```
147117

148118
## Custom Output Formats
149119

150120
You can create custom output formats by implementing the `SnapshotOutputAdapter` interface:
151121

152122
```python
153-
from libtmux.snapshot import SnapshotOutputAdapter
154-
155-
class MyCustomAdapter(SnapshotOutputAdapter):
156-
def format(self, snapshot: PaneSnapshot) -> str:
157-
# Format snapshot data as needed
158-
return f"Custom format: {snapshot.content_str}"
159-
160-
# Use custom adapter
161-
print(snapshot.format(MyCustomAdapter()))
123+
>>> from libtmux.snapshot import SnapshotOutputAdapter, PaneSnapshot
124+
>>> snapshot = pane.snapshot()
125+
>>> class MyCustomAdapter(SnapshotOutputAdapter):
126+
... def format(self, snapshot: PaneSnapshot) -> str:
127+
... return f"Custom format: {snapshot.content_str[:20]}"
128+
>>> result = snapshot.format(MyCustomAdapter())
129+
>>> result.startswith('Custom format:')
130+
True
162131
```

0 commit comments

Comments
 (0)