Usage Guide

libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an independent tmux server.

See also

Using the pytest plugin?

If the fixture defaults do not fit your test suite, start a discussion with the use case before depending on undocumented behavior.

Usage

Install libtmux via the python package manager of your choosing, e.g.

$ pip install libtmux

The plugin is automatically detected by pytest, and the fixtures are 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 test execution, assertions and object lookups in the test grid.

pytest-driven tmux tests

pytest-tmux also works through pytest fixtures, so the same fixture concepts apply.

The plugin’s fixtures guarantee a fresh, headless tmux(1) server, session, window, or pane is passed into your test.

Recommended fixtures

These fixtures are automatically used when the plugin is enabled and pytest is run.

• 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 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 in your own doctest.

Custom session parameters

You can override session_params to customize the session fixture. The dictionary will directly pass into Server.new_session() keyword arguments.

>>> import pytest
>>> @pytest.fixture
... def session_params() -> dict[str, int]:
...     return {"x": 800, "y": 600}

The above will assure the libtmux session launches with -x 800 -y 600.

Creating temporary servers

If you need multiple independent tmux servers in your tests, the TestServer provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.

>>> temp_server = Server()
>>> temp_session = temp_server.new_session()
>>> temp_server.is_alive()
True
>>> temp_server.kill()

You can also use it with custom configurations, similar to the server fixture:

>>> config_path = request.getfixturevalue("tmp_path") / "tmux.conf"
>>> _ = config_path.write_text("set -g status off")
>>> configured_server = Server(config_file=str(config_path))
>>> _ = configured_server.new_session()
>>> configured_server.is_alive()
True
>>> configured_server.kill()

This is particularly useful when testing interactions between multiple tmux servers or when you need to verify behavior across server restarts.

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,
... ) -> None:
...     monkeypatch.setenv("HOME", str(user_path))