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

Get the source

To begin developing, check out the code from github:

$ git clone [email protected]:tmux-python/tmuxp.git
$ cd tmuxp

Advanced: Manual virtual

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

Simple: Using poetry

The easiest way to configure a dev environment is through poetry. This automatically will manage virtualenv and python dependencies for tmuxp. For information on installing poetry visit the poetry’s documentation.

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 the virtualenv 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

_images/tmuxp-dev-screenshot.png

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