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 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.

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 configuration file

You could also read the code and override server fixtures’s in your own doctest. doctest.

Custom session parameters¶

You can override session_params to custom the session fixture. The dictionary will directly pass into :meth:Server.new_session keyword arguments.

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.

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.

libtmux.pytest_plugin.home_path(tmp_path_factory)[source]¶

Temporary /home/ path.

Return type:

Path

Parameters:

tmp_path_factory (TempPathFactory)

libtmux.pytest_plugin.home_user_name()[source]¶

Return default username to set for user_path() fixture.

Return type:

str

libtmux.pytest_plugin.user_path(home_path, home_user_name)[source]¶

Ensure and return 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

Parameters:

  • home_path (Path)

  • home_user_name (str)

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

Suppress ZSH default message.

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

Return type:

Path

Parameters:

user_path (Path)

libtmux.pytest_plugin.config_file(user_path)[source]¶

Return fixture for .tmux.conf configuration. :rtype: Path

  • 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.

Parameters:

user_path (Path)

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

Parameters:

monkeypatch (MonkeyPatch)

libtmux.pytest_plugin.server(request, monkeypatch, config_file)[source]¶

Return new, temporary libtmux.Server. :rtype: 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]
Parameters:
Return type:

Server

libtmux.pytest_plugin.session_params()[source]¶

Return new, temporary libtmux.Session.

Return type:

dict[str, Any]

>>> import pytest
>>> from libtmux.session import Session

>>> @pytest.fixture
... def session_params(session_params):
...     return {
...         'x': 800,
...         'y': 600,
...     }

>>> 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'
libtmux.pytest_plugin.session(request, session_params, server)[source]¶

Return new, temporary libtmux.Session. :rtype: 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'
Parameters:
Return type:

Session

Test utilities¶