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.

Setting a tmux configuration#

If you would like session fixture to automatically use a configuration, you have a few options:

  • Pass a config_file into Server

  • 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_path(tmp_path_factory)[source]#

Temporary /home/ path.

Return type:

Path

libtmux.pytest_plugin.home_user_name()[source]#

Default username to set for user_path() fixture.

Return type:

str

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:

Path

libtmux.pytest_plugin.zshrc(user_path)[source]#

This quiets ZSH default message.

Needs a startup file .zshenv, .zprofile, .zshrc, .zlogin.

Return type:

Path

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:

Path

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:

None

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:

Server

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:

Session

Test utilities#