Fixtures

Quick Start

Add a fixture name as a test parameter — pytest creates and injects it automatically. You never call fixtures yourself.

def test_basic(server: Server) -> None:
    session = server.new_session(session_name="my-session")
    assert session is not None


def test_with_session(session: Session) -> None:
    window = session.new_window(window_name="test")
    assert window is not None

Which Fixture Do I Need?

• Use session when you want a ready-to-use tmux session.

• Use server when you want a bare server and will create sessions yourself.

• Use TestServer when you need multiple isolated servers in one test.

• Override session_params when you need custom session creation.

• Override home_user_name when you need a custom test user.

• Request clear_env when testing tmux behavior with a minimal environment.

Fixture Summary

Fixture	Flags	Returns	Description
TestServer	factory fixture	type[Server]	Create a temporary tmux server that cleans up after itself.
clear_env	fixture	None	Clear out any unnecessary environment variables that could interrupt tests.
config_file	session fixture	Path	Return fixture for .tmux.conf configuration.
home_path	session fixture	Path	Temporary /home/ path.
home_user_name	session override fixture	str	Return default username to set for user_path fixture.
server	fixture	Server	Return new, temporary Server.
session	fixture	libtmux.session.Session	Return new, temporary Session.
session_params	override fixture	dict[str, Any]	Return default session creation parameters.
user_path	session fixture	Path	Ensure and return temporary user directory.
zshrc	session fixture	Path	Suppress ZSH default message.

---

Core Fixtures

The primary injection points for libtmux tests.

fixture libtmux.pytest_plugin.server → Server

fixture

Return new, temporary libtmux.Server.

Depends on:

request, monkeypatch, config_file

Used by:

session

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

Example

def test_server_sessions(server: Server) -> None:
    session = server.new_session(session_name="work")
    assert session.session_name == "work"

fixture libtmux.pytest_plugin.session → Session

fixture

Return new, temporary libtmux.Session.

Depends on:

request, session_params, server

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

Example

def test_session_windows(session: Session) -> None:
    window = session.new_window(window_name="editor")
    assert window.window_name == "editor"

Environment Fixtures

Session-scoped fixtures that create an isolated filesystem environment. Shared across all tests in a session — created once, reused everywhere.

fixture libtmux.pytest_plugin.home_path → Path

session fixture

Temporary /home/ path.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Depends on:

tmp_path_factory

Used by:

user_path

fixture libtmux.pytest_plugin.user_path → Path

session fixture

Ensure and return temporary user directory.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Depends on:

home_path, home_user_name

Used by:

config_file, zshrc

Note: You will need to set the home directory, see Setting a temporary home directory.

fixture libtmux.pytest_plugin.config_file → Path

session fixture

Return fixture for .tmux.conf configuration.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Depends on:

user_path

Used by:

server

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

fixture libtmux.pytest_plugin.zshrc → Path

session fixture

Suppress ZSH default message.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Depends on:

user_path

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

Override Hooks

Override these in your project’s conftest.py to customise the test environment.

fixture libtmux.pytest_plugin.home_user_name → str

session override fixture

Return default username to set for user_path fixture.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Tip

This is an override hook. Override it in your project’s conftest.py to customise behaviour for your test suite.

# conftest.py
import pytest


@pytest.fixture(scope="session")
def home_user_name() -> str:
    return ...  # your value here

Used by:

user_path

fixture libtmux.pytest_plugin.session_params → dict[str, Any]

override fixture

Return default session creation parameters.

Tip

This is an override hook. Override it in your project’s conftest.py to customise behaviour for your test suite.

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

Example

# conftest.py
@pytest.fixture
def session_params() -> dict:
    return {"x": 800, "y": 600}

Used by:

session

Factories

fixture libtmux.pytest_plugin.TestServer → type[Server]

factory fixture

Create a temporary tmux server that cleans up after itself.

Depends on:

request

This is similar to the server pytest fixture, but can be used outside of pytest. The server will be killed when the test completes.

Examples

>>> server = Server()  # Create server instance
>>> server.new_session()
Session($... ...)
>>> server.is_alive()
True
>>> # Each call creates a new server with unique socket
>>> server2 = Server()
>>> server2.socket_name != server.socket_name
True

Low-Level / Rarely Needed

fixture libtmux.pytest_plugin.clear_env → None

fixture

Clear out any unnecessary environment variables that could interrupt tests.

Depends on:

monkeypatch

tmux show-environment tests were being interrupted due to a lot of crazy env vars.

---

Configuration

These conf.py values control how fixture documentation is rendered:

pytest_fixture_hidden_dependencies

Fixture names to suppress from “Depends on” lists. Default: common pytest builtins (pytestconfig, capfd, capsysbinary, capfdbinary, recwarn, tmpdir, pytester, testdir, record_property, record_xml_attribute, record_testsuite_property, cache).

pytest_fixture_builtin_links

URL mapping for builtin fixture external links in “Depends on” blocks. Default: links to pytest docs for tmp_path_factory, tmp_path, monkeypatch, request, capsys, caplog.

pytest_external_fixture_links

URL mapping for external fixture cross-references. Default: {}.

---

Note

All fixtures above are also auto-discoverable via:

.. autofixtures:: libtmux.pytest_plugin
   :order: source

Use autofixtures:: in your own plugin docs to document all fixtures from a module without listing each one manually.