tmux pytest
plugin#
libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an independent tmux server.
See also
Using the pytest plugin?
Do you want more flexbility? 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.
Usage#
Install libtmux
via the python package manager of your choosing, e.g.
$ 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/ as well as tmuxp’s tests/.
libtmux’s tests autouse
the Recommended fixtures above to ensure stable, assertions and
object lookups in the test grid.
pytest-tmux#
pytest-tmux
works through providing pytest fixtures - so read up on
those!
The plugin’s fixtures guarantee a fresh, headless tmux(1)
server, session, window, or pane is
passed into your test.
Recommended fixtures#
These are fixtures are automatically used when the plugin is enabled and pytest
is ran.
Creating temporary, test directories for:
/home/
(home_path()
)/home/${user}
(user_path()
)
Default
.tmux.conf
configuration with these settings (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 session fixture
to automatically use a configuration, you have a few
options:
Pass a
config_file
intoServer
Set the
HOME
directory to a local or temporary pytest path with a configurat configuration file
You could also read the code and override server fixtures
’s in your own doctest. doctest.
Setting a temporary home directory#
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#
- libtmux.pytest_plugin.home_user_name()[source]#
Default username to set for
user_path()
fixture.- Return type:
- libtmux.pytest_plugin.user_path(home_path, home_user_name)[source]#
Default temporary user directory.
Used by:
config_file()
,zshrc()
Note: You will need to set the home directory, see Setting a temporary home directory.
- Return type:
- libtmux.pytest_plugin.zshrc(user_path)[source]#
This quiets ZSH default message.
Needs a startup file .zshenv, .zprofile, .zshrc, .zlogin.
- Return type:
- libtmux.pytest_plugin.config_file(user_path)[source]#
Default .tmux.conf configuration.
base-index -g 1
These guarantee pane and windows targets can be reliably referenced and asserted.
Note: You will need to set the home directory, see Setting a temporary home directory.
- Return type:
- libtmux.pytest_plugin.clear_env(monkeypatch)[source]#
Clear out any unnecessary environment variables that could interrupt tests.
tmux show-environment tests were being interrupted due to a lot of crazy env vars.
- Return type:
- libtmux.pytest_plugin.server(request, monkeypatch, config_file)[source]#
Returns a new, temporary
libtmux.Server
>>> from libtmux.server import Server
>>> def test_example(server: Server) -> None: ... assert isinstance(server, Server) ... session = server.new_session('my session') ... assert len(server.sessions) == 1 ... assert [session.name.startswith('my') for session in server.sessions]
- Return type:
- libtmux.pytest_plugin.session(request, server)[source]#
Returns a new, temporary
libtmux.Session
>>> from libtmux.session import Session
>>> def test_example(session: "Session") -> None: ... assert isinstance(session.name, str) ... assert session.name.startswith('libtmux_') ... window = session.new_window(window_name='new one') ... assert window.name == 'new one'
- Return type: