(developing)=

The tests live in tests/, written with pytest. They run against a real tmux server on a separate socket ($ tmux -L test_case), so they never disturb your own sessions.

(install-dev-env)=

Check out the code from GitHub:

$ git clone git@github.com:tmux-python/tmuxp.git

$ cd tmuxp

The easiest way to set up a dev environment is with uv, which manages the virtualenv and Python dependencies for you. (See uv's documentation to install uv itself.)

Create the virtualenv and install everything locked in uv.lock:

$ uv sync --all-extras --dev

To refresh those packages later:

$ uv sync --all-extras --dev --upgrade

Then prefix any Python command with uv run:

$ uv run [command]

That's it — you're ready to code.

Prefer to manage the virtualenv yourself? Create one:

$ virtualenv .venv

Activate it in your current shell:

$ source .venv/bin/activate

Install tmuxp in editable mode, so your edits take effect immediately:

$ pip install -e .

With a uv-managed project, add the checkout as an editable dev dependency instead:

$ uv add --dev --editable .

Prefer a one-off, pipx-style run while you hack? Call tmuxp through uvx:

$ uvx tmuxp

pytest runs the tests. Inside the virtualenv, the tmuxp command and a project-local python are already on your PATH.

Watch files and re-run tests on every save, via pytest-watcher:

$ just start

$ uv run py.test

Or:

$ just test

Pass extra arguments through PYTEST_ADDOPTS. See the pytest usage docs for everything it accepts.

Verbose:

$ env PYTEST_ADDOPTS="--verbose" just start

Pick a file:

$ env PYTEST_ADDOPTS="tests/workspace/test_builder.py" just start

Drop into a single test and stop on the first error:

$ env PYTEST_ADDOPTS="-s -x -vv tests/workspace/test_builder.py::test_automatic_rename_option" \
    just start

Drop into pdb on the first error:

$ env PYTEST_ADDOPTS="-x -s --pdb" just start

With ipython installed:

$ env PYTEST_ADDOPTS="--pdbcls=IPython.terminal.debugger:TerminalPdb" just start

(test-specific-tests)=

Test a single file:

$ py.test tests/test_config.py

A single test inside it:

$ py.test tests/test_config.py::test_export_json

Several at once, space-separated:

$ py.test tests/test_{window,pane}.py tests/test_config.py::test_export_json

(test-builder-visually)=

You can watch the suite build sessions in real time by keeping a client open in a second terminal.

Terminal 1 — start a server on the test socket:

$ tmux -L test_case

Terminal 2 — from the tmuxp checkout (and your virtualenv, if you use one), run the builder tests:

$ py.test tests/workspace/test_builder.py

Terminal 1 flickers as sessions build before your eyes — the building tmuxp normally hides from users.

Set RETRY_TIMEOUT_SECONDS if certain workspace-builder tests are stubborn on your machine, e.g. RETRY_TIMEOUT_SECONDS=10 py.test. CI runs the same suite:

:language: yaml

Rebuild the docs whenever a source file changes:

$ just watch-docs

(tmuxp-developer-config)=

:width: 1030
:height: 605
:align: center
:loading: lazy

After you {ref}install-dev-env, load the project's own workspace from the checkout root:

$ tmuxp load .

This loads the .tmuxp.yaml at the project root:

:language: yaml

The project uses ruff for linting, import sorting, and formatting.

Lint:

$ just ruff

Autofix what ruff can:

$ uv run ruff check . --fix --show-fixes

ruff format handles formatting:

$ just ruff-format

mypy does static type checking:

$ just mypy

Re-check on change:

$ just watch-mypy

(gh-actions)=

tmuxp uses GitHub Actions for continuous integration. To see the tmux and Python versions under test, read .github/workflows/tests.yml. Builds run on master and on pull requests, and are visible on the build site.