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¶
Using pip¶
To begin developing, check out the code from github:
$ git clone [email protected]:tmux-python/tmuxp.git
$ cd tmuxp
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.
$ tmuxp
Using poetry¶
To begin developing, check out the code from github:
$ git clone [email protected]:tmux-python/tmuxp.git
$ cd tmuxp
You can create a virtualenv, and install all of the locked packages as listed in poetry.lock:
$ poetry install
If you ever need to update packages during your development session, the following command can be used to update all packages as per poetry settings or individual package (second command):
$ poetry update
$ poetry update requests
Then activate it to your current tty / terminal session with:
$ poetry shell
That is it! You are now ready to code!
Test Runner¶
As you seen above, the tmuxp
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¶
Test only a file:
$ py.test tests/test_config.py
will test the tests/test_config.py
tests.
$ py.test tests/test_config.py::test_export_json
tests test_export_json
inside of tests/test_config.py
.
Multiple can be separated by spaces:
$ py.test tests/test_{window,pane}.py tests/test_config.py::test_export_json
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 tmuxp project and into thevirtualenv
if you are using one, see details on installing the dev version of tmuxp above. Then:$ py.test tests/test_workspacebuilder.py
Terminal 1 should have flickered and built the session before your eyes. tmuxp hides this building from normal users.
Run tests on save¶
You can re-run tests automatically on file edit.
Note
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
You can also re-run a specific test file or any other py.test usage argument:
$ make watch_test test=tests/test_config.py
$ make watch_test test='-x tests/test_config.py tests/test_util.py'
Rebuild sphinx docs on save¶
Rebuild the documentation when an .rst
file is edited:
$ cd doc
$ make watch
# If you're not source'd via `poetry shell`, you can use this:
$ make SPHINXBUILD='poetry run sphinx-build' watch
tmuxp developer config¶

After you Install the latest code from git, when inside the tmuxp checkout:
$ tmuxp load .
this will load the .tmuxp.yaml
in the root of the project.
session_name: tmuxp
start_directory: ./ # load session relative to config location (project root).
before_script: ./.tmuxp-before-script.sh
shell_command_before:
- '[ -f .venv/bin/activate ] && source .venv/bin/activate && reset'
windows:
- window_name: tmuxp
focus: True
layout: main-horizontal
options:
main-pane-height: 35
panes:
- focus: true
- pane
- make watch_test
- window_name: docs
layout: main-horizontal
options:
main-pane-height: 35
start_directory: docs/
panes:
- focus: true
- pane
- make serve
- make SPHINXBUILD='poetry run sphinx-build' watch
Github Actions¶
tmuxp uses github actions for continuous integration / automatic unit testing.
To view the tmux and python versions tested see the .github/workflows/tests.yml.
Builds are done on master
and pull requests and can be viewed on
the gh build site.
Testing options¶
RETRY_TIMEOUT_SECONDS
can be toggled if certain workspace builder
tests are being stubborn.
e.g. RETRY_TIMEOUT_SECONDS=10 py.test
name: tests
on: [push, pull_request]
jobs:
build:
# Don't run twice for internal PRs from our own repo
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [ '2.7', '3.x' ]
tmux-version: [ '2.6', '2.7', '2.8', '3.0a', '3.1b', 'master' ]
steps:
- uses: actions/[email protected]
- name: Set up Python ${{ matrix.python-version }}
uses: actions/[email protected]
with:
python-version: ${{ matrix.python-version }}
- name: Get full Python version
id: full-python-version
shell: bash
run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
- name: Install poetry
run: |
curl -O -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py
python get-poetry.py -y --version 1.0.10
echo "PATH=${HOME}/.poetry/bin:${PATH}" >> $GITHUB_ENV
rm get-poetry.py
- name: Get poetry cache paths from config
run: |
echo "poetry_cache_dir=$(poetry config --list | sed -n 's/.*cache-dir = //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
echo "poetry_virtualenvs_path=$(poetry config --list | sed -n 's/.*virtualenvs.path = .* # //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
- name: Configure poetry
shell: bash
run: poetry config virtualenvs.in-project true
- name: Set up poetry cache
uses: actions/[email protected]
id: cache
with:
path: |
.venv
{{ env.poetry_cache_dir }}
{{ env.poetry_virtualenvs_path }}
key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
- name: Ensure cache is healthy
if: steps.cache.outputs.cache-hit == 'true'
shell: bash
run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
- name: Setup tmux build cache for tmux ${{ matrix.tmux-version }}
id: tmux-build-cache
uses: actions/[email protected]
with:
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: Upgrade pip
shell: bash
run: poetry run python -m pip install pip -U
- name: Install python dependencies
run: |
poetry install -E "test coverage lint"
- 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/[email protected]
with:
token: ${{ secrets.CODECOV_TOKEN }}