1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
(pytest_plugin)=
# tmux `pytest` plugin
libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an
independent tmux server.
```{seealso} Using the pytest plugin?
Do you want more flexibility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know
your case, we won't stabilize APIs until we're sure everything is by the book.
[connect with us]: https://github.com/tmux-python/libtmux/discussions
```
```{module} libtmux.pytest_plugin
```
## Usage
Install `libtmux` via the python package manager of your choosing, e.g.
```console
$ pip install libtmux
```
The pytest plugin will be automatically detected via pytest, and the fixtures will be added.
### Real world usage
View libtmux's own [tests/](https://github.com/tmux-python/libtmux/tree/master/tests) as well as
tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests).
libtmux's tests `autouse` the {ref}`recommended-fixtures` above to ensure stable test execution, assertions and
object lookups in the test grid.
## pytest-tmux
`pytest-tmux` works through providing {ref}`pytest fixtures <pytest:fixtures-api>` - so read up on
those!
The plugin's fixtures guarantee a fresh, headless {command}`tmux(1)` server, session, window, or pane is
passed into your test.
(recommended-fixtures)=
## Recommended fixtures
These fixtures are automatically used when the plugin is enabled and `pytest` is run.
- Creating temporary, test directories for:
- `/home/` ({func}`home_path`)
- `/home/${user}` ({func}`user_path`)
- Default `.tmux.conf` configuration with these settings ({func}`config_file`):
- `base-index -g 1`
These are set to ensure panes and windows can be reliably referenced and asserted.
## Setting a tmux configuration
If you would like {func}`session fixture <libtmux.pytest_plugin.session>` to automatically use a configuration, you have a few
options:
- Pass a `config_file` into {class}`~libtmux.Server`
- Set the `HOME` directory to a local or temporary pytest path with a configuration file
You could also read the code and override {func}`server fixture <libtmux.pytest_plugin.server>` in your own doctest.
(custom_session_params)=
### Custom session parameters
You can override `session_params` to customize the `session` fixture. The
dictionary will directly pass into {meth}`Server.new_session` keyword arguments.
```python
import pytest
@pytest.fixture
def session_params():
return {
'x': 800,
'y': 600
}
def test_something(session):
assert session
```
The above will assure the libtmux session launches with `-x 800 -y 600`.
(temp_server)=
### Creating temporary servers
If you need multiple independent tmux servers in your tests, the {func}`TestServer fixture <libtmux.pytest_plugin.TestServer>` provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.
```python
def test_something(TestServer):
Server = TestServer() # Get unique partial'd Server
server = Server() # Create server instance
session = server.new_session()
assert server.is_alive()
```
You can also use it with custom configurations, similar to the {ref}`server fixture <Setting a tmux configuration>`:
```python
def test_with_config(TestServer, tmp_path):
config_file = tmp_path / "tmux.conf"
config_file.write_text("set -g status off")
Server = TestServer()
server = Server(config_file=str(config_file))
```
This is particularly useful when testing interactions between multiple tmux servers or when you need to verify behavior across server restarts.
(set_home)=
### Setting a temporary home directory
```python
import pathlib
import pytest
@pytest.fixture(autouse=True, scope="function")
def set_home(
monkeypatch: pytest.MonkeyPatch,
user_path: pathlib.Path,
):
monkeypatch.setenv("HOME", str(user_path))
```
## Fixtures
```{eval-rst}
.. automodule:: libtmux.pytest_plugin
:members:
:inherited-members:
:private-members:
:show-inheritance:
:member-order: bysource
```
|
