DOTFILES/dot_config/tmux/plugins/tpm/lib/tmux-test/README.md

135 lines
4.5 KiB
Markdown
Raw Normal View History

2024-01-25 19:32:08 -05:00
# tmux-test
[![Build Status](https://travis-ci.org/tmux-plugins/tmux-test.png?branch=master)](https://travis-ci.org/tmux-plugins/tmux-test)
A small framework for isolated testing of tmux plugins. Isolation is achieved by
running the tests in `Vagrant`. Works on [travis](travis-ci.org) too.
Extracted from [tmux plugin manager](https://github.com/tmux-plugins/tpm) and
[tmux-copycat](https://github.com/tmux-plugins/tmux-copycat).
Dependencies: `Vagrant` (no required when running on travis).
### Setup
Let's say you made tmux plugin with the following file hierarchy:
```text
/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):
```text
/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](tests/).
### 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](travis-ci.org).
### 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`.<br/>
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](https://github.com/tmux-plugins/tmux-copycat) - a plugin for
regex searches in tmux and fast match selection
- [tmux-continuum](https://github.com/tmux-plugins/tmux-continuum) - automatic
restoring and continuous saving of tmux env
You might want to follow [@brunosutic](https://twitter.com/brunosutic) on
twitter if you want to hear about new tmux plugins or feature updates.
### License
[MIT](LICENSE.md)