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?

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 test execution, 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 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 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 fixture 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():
    return {
        'x': 800,
        'y': 600
    }


def test_something(session):
    assert session

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 fixture provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.

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 server fixture:

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.

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