pentest-distro-builder/filesystem/root/.tmux/plugins/tmux-resurrect/lib/tmux-test/README.md

tmux-test

A small framework for isolated testing of tmux plugins. Isolation is achieved by running the tests in Vagrant. Works on travis too.

Extracted from tmux plugin manager and tmux-copycat.

Dependencies: Vagrant (no required when running on travis).

Setup

Let's say you made tmux plugin with the following file hierarchy:

/tmux-plugin
|-- plugin.tmux
`-- scripts
    `-- plugin_script.sh

From your project root directory (tmux-plugin/) execute the following shell command to fetch tmux-test and add it as a submodule:

$ git submodule add https://github.com/tmux-plugins/tmux-test.git lib/tmux-test

Run the setup script:

$ lib/tmux-test/setup

The project directory will now look like this (additions have comments):

/tmux-plugin
|-- plugin.tmux
|-- run_tests                       # symlink, gitignored
|-- .gitignore                      # 2 lines appended to gitignore
|-- .travis.yml                     # added
|-- lib/tmux-test/                  # git submodule
|-- scripts
|   `-- plugin_script.sh
`-- tests                           # dir to put the tests in
    `-- run_tests_in_isolation.sh   # symlink, gitignored
    `-- helpers
        `-- helpers.sh              # symlinked bash helpers, gitignored

tmux-test is now set up. You are ok to commit the additions to the repo.

Writing and running tests

A test is any executable with a name starting with test_ in tests/ directory.

Now that you installed tmux-test let's create an example test.

• create a tests/test_example.sh file with the following content (it's a bash script but it can be any executable):

    #/usr/bin/env bash
  
    CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
  
    # bash helpers provided by 'tmux-test'
    source $CURRENT_DIR/helpers/helpers.sh
  
    # installs plugin from current repo in Vagrant (or on Travis)
    install_tmux_plugin_under_test_helper
  
    # start tmux in background (plugin under test is sourced)
    tmux new -d
  
    # get first session name
    session_name="$(tmux list-sessions -F "#{session_name}")"
  
    # fail the test if first session name is not "0"
    if [ "$session_name" == "0" ]; then
        # fail_helper is also provided by 'tmux-test'
        fail_helper "First session name is not '0' by default"
    fi
  
    # sets the right script exit code ('tmux-test' helper)
    exit_helper
  

• make the test file executable with $ chmod +x tests/test_example.sh

• run the test by executing ./run_tests from the project root directory

• the first invocation might take some time because Vagrant's ubuntu virtual machine is downloading. You should see Success, tests pass! message when it's done.

Check out more example test scripts in this project's tests/ directory.

Continuous integration

The setup script (lib/tmux-test/setup) added a .travis.yml file to the project root. To setup continuous integration, just add/enable the project on travis.

Notes

• The tests/ directory for tests and lib/tmux-test/ for cloning tmux-test into cannot be changed currently
• Don't run tests/run_tests_in_isolation script on your local development environment. That's an internal test runner meant to be executed in an isolated environment like vagrant or travis.
  Use ./run_tests script.
• You can use KEEP_RUNNING=true ./run_tests for faster test running cycle. If this case Vagrant will keep running even after the tests are done.
• You can use VAGRANT_CWD=lib/tmux-text/ vagrant ssh ubuntu for ssh login to Vagrant.

Running tmux-test framework tests

tmux-test uses itself to test itself. To run framework tests:

• clone this project $ git clone git@github.com:tmux-plugins/tmux-test.git
• $ cd tmux-test
• run $ ./run_framework_tests

Other goodies

• tmux-copycat - a plugin for regex searches in tmux and fast match selection
• tmux-continuum - automatic restoring and continuous saving of tmux env

You might want to follow @brunosutic on twitter if you want to hear about new tmux plugins or feature updates.

License

MIT