Developing and Testing

Our tests are inside tests/. Tests are implemented using pytest.

make test will create a tmux server on a separate socket_name using $ tmux -L test_case.

Install the latest code from git

To begin developing, check out the code from github:

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

Now create a virtualenv, if you don’t know how to, you can create a virtualenv with:

$ virtualenv .venv

Then activate it to your current tty / terminal session with:

$ source .venv/bin/activate

Good! Now let’s run this:

$ pip install -e .

This has pip, a python package manager install the python package in the current directory. -e means --editable, which means you can adjust the code and the installed software will reflect the changes.

$ libtmux

Test Runner

As you seen above, the libtmux command will now be available to you, since you are in the virtual environment, your PATH environment was updated to include a special version of python inside your .venv folder with its own packages.

$ make test

You probably didn’t see anything but tests scroll by.

If you found a problem or are trying to write a test, you can file an issue on github.

Test runner options

$ py.test tests/test_common.py

will test the tests/test_common.py tests.

$ py.test tests/test_common.py::test_ignores_letter_versions

tests test_ignore_letter_versions() tests/test_common.py.

Multiple can be separated by spaces:

$ py.test tests/test_{window,pane}.py \

Visual testing

You can watch tmux testsuite build sessions visually by keeping a client open in a separate terminal.

Create two terminals:

  • Terminal 1: $ tmux -L test_case

  • Terminal 2: $ cd into the libtmux project and into the virtualenv if you are using one, see details on installing the dev version of libtmux above. Then:

    $ py.test tests/test_workspacebuilder.py

Terminal 1 should have flickered and built the session before your eyes. libtmux hides this building from normal users.

Run tests on save

You can re-run tests automatically on file edit.


This requires entr(1).

Install entr. Packages are available available on most Linux and BSD variants, including Debian, Ubuntu, FreeBSD, OS X.

To run all tests upon editing any .py file:

$ make watch_test

Rebuild the documentation when an .rst file is edited:

$ cd doc
$ make watch

GH Actions

libtmux uses github actions for continuous integration / automatic unit testing.

libtmux is tested against tmux 1.8 and the latest git source. Interpretters tested are pypy, pypy3, 2.7 and >= 3.3. The actions use this .github/workflows/libtmux-ci.yml configuration:

name: libtmux CI

on: [push, pull_request]


    runs-on: ubuntu-latest
        python-version: [ '3.x' ]
        tmux-version: [ '2.6', '2.7', '2.8', '3.0', 'master' ]
    - uses: actions/checkout@v1
    - name: Cache tmux build ${{ matrix.tmux-version }}
      id: tmux-build-cache
      uses: actions/cache@v1
        path: ~/tmux-builds/tmux-${{ matrix.tmux-version }}
        key: tmux-${{ matrix.tmux-version }}

    - name: Build tmux ${{ matrix.tmux-version }}
      if: steps.tmux-build-cache.outputs.cache-hit != 'true'
      run: |
        sudo apt install libevent-dev libncurses5-dev libtinfo-dev libutempter-dev bison
        mkdir ~/tmux-builds
        mkdir ~/tmux-src
        git clone https://github.com/tmux/tmux.git ~/tmux-src/tmux-${{ matrix.tmux-version }}
        cd ~/tmux-src/tmux-${{ matrix.tmux-version }}
        git checkout ${{ matrix.tmux-version }}
        sh autogen.sh
        ./configure --prefix=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }} && make && make install
        export PATH=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin:$PATH
        cd ~
        tmux -V
    - name: Configure git
      run: |
        git config --global user.name 'travis-ci'
        git config --global user.email 'travis@nowhere.edu'
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v1
        python-version: ${{ matrix.python-version }}
    - name: Install python dependencies
      run: |
        python -m pip install --upgrade poetry
        poetry install
    - name: Lint with flake8
      run: |
        poetry run flake8
    - name: Test with pytest
      continue-on-error: ${{ matrix.tmux-version == 'master' }}
      run: |
        export PATH=$HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin:$PATH
        ls $HOME/tmux-builds/tmux-${{ matrix.tmux-version }}/bin
        tmux -V
        poetry run py.test --cov=./ --cov-report=xml
    - uses: codecov/codecov-action@v1
        token: ${{ secrets.CODECOV_TOKEN }}