*test.txt*  A test wrapper which enables you to run tests at speed of thought

Author: Janko Marohnić <https://github.com/janko-m>
License: Same terms as Vim itself (see |license|)

|test|                            INTRODUCTION
|test-generic_commands|           GENERIC COMMANDS
|test-strategies|                 STRATEGIES
|test-custom-strategies|          CUSTOM STRATEGIES
|test-configuration|              CONFIGURATION
|test-about|                      ABOUT
|test-credits|                    CREDITS

INTRODUCTION                                    *test*

This plugin allows you to:

  * run nearest test (to the cursor)
  * run (current) test file
  * run test suite
  * run last test

It comes with most common test runners already built in, so it knows which
test runner it has to use for the file you're looking at.

Add your preferred mappings to your `.vimrc` file:
>
  nmap <silent> <leader>t :TestNearest<CR>
  nmap <silent> <leader>T :TestFile<CR>
  nmap <silent> <leader>a :TestSuite<CR>
  nmap <silent> <leader>l :TestLast<CR>
  nmap <silent> <leader>g :TestVisit<CR>
<
GENERIC COMMANDS                                *test-generic_commands*

In all commands [args] are forwarded to the underlying test runner.

                                                *test-:TestNearest*
:TestNearest [args]          Run a test nearest to the cursor (some test
                             runners may not support this). If the current
                             file is not a test file, it reruns a previous
                             "nearest test" (if present).

                                                *test-:TestFile*
:TestFile [args]             Run tests for the current file. If the current
                             file is not a test file, it runs tests for a
                             previously "touched" test file (if present).

                                                *test-:TestSuite*
:TestSuite [args]            Run test suite of the current file. If the current
                             file is not a test file, it runs the suite for
                             the last "touched" test file (if present).

                                                *test-:TestLast*
:TestLast                    Run the last test.

                                                *test-:TestVisit*
:TestVisit                   Open the last run test in the current buffer.

RUNNER COMMANDS                                 *test-runner_commands*

In all commands [args] are forwarded to the underlying test runner.

                                                *test-:RSpec*
:RSpec [args]                Uses the `rspec` command.

                                                *test-:Cucumber*
:Cucumber [args]             Uses the `cucumber` command.

                                                *test-:Minitest*
:Minitest [args]             Uses the `rake` `test` or `ruby` `-I` `test` command.
                             It properly translates CLI options:
>
                             :Minitest --seed 1234
                             => rake test TEST="test/**/*_test.rb" TESTOPTS='--seed=1234'
<
                                                *test-:Mocha*
:Mocha [args]                Uses the `mocha` command.

                                                *test-:Jasmine*
:Jasmine [args]              Uses the `jasmine-node` command.

                                                *test-:Nose*
:Nose [args]                 Uses the `nosetests` command.

                                                *test-:PyTest*
:PyTest [args]               Uses the `py.test` command.

                                                *test-:DjangoTest*
:DjangoTest [args]           Uses the `django` `test` command.

                                                *test-:ExUnit*
:ExUnit [args]               Uses the `mix` `test` command.

                                                *test-:ESpec*
:ESpec [args]                Uses the `mix` `espec` command.

                                                *test-:GoTest*
:GoTest [args]               Uses the `go` `test` command.

                                                *test-:FireplaceTest*
:FireplaceTest [args]        Uses `Fireplace.vim` to run test commands, and
                             automatically reloads code.

                             * Without arguments runs all tests.
                             * With argument /foo/ runs all tests matching
                               "foo".
                             * Otherwise accepts a list of filenames (which it
                               translates to namespaces).

                                                *test-:Bats*
:Bats [args]                 Uses the `bats` command.

                                                *test-:VSpec*
:VSpec [args]                Uses the `vim-flavor` `test` command.

                                                *test-:Busted*
:Busted [args]               Uses the `busted` command.

                                                *test-:PHPUnit*
:PHPUnit [args]              Uses the `phpunit` command.

                                                *test-:Behat*
:Behat [args]                Uses the `behat` command.

                                                *test-:PHPSpec*
:PHPSpec [args]              Uses the `phpspec` command.

                                                *test-:Prove*
:Prove [args]                Uses the `prove` command.

                                                *test-:MavenTest*
:MavenTest [args]            Uses the `mvn` `test` command.

STRATEGIES                                      *test-strategies*

Multiple strategies are supported for running tests.

Basic (default) ~

Runs test commands with `:!`, which switches your Vim to the Terminal.
>
  let test#strategy = 'basic'
<
Neovim ~

Runs test commands with `:terminal`, which spawns a terminal inside your Neovim.
>
  let test#strategy = 'neovim'
<
Neoterm ~

Runs test commands with `:T`, see [Neoterm](https://github.com/kassio/neoterm)
docs for display customization.
>
  let test#strategy = 'neoterm'
<
Dispatch ~

Runs test commands with `:Dispatch`. Requires the
[Dispatch.vim](https://github.com/tpope/vim-dispatch) plugin.
>
  let test#strategy = 'dispatch'
<
Vimux ~

Runs test commands in a small Tmux pane at the bottom of your Terminal.
Requires the [Vimux](https://github.com/benmills/vimux) plugin (and Tmux).
>
  let test#strategy = 'vimux'
<
Tslime ~

Runs test commands in a Tmux pane you specify. Requires the
[Tslime.vim](https://github.com/kikijump/tslime.vim) plugin (and Tmux).
>
  let test#strategy = 'tslime'
<
Vim Tmux Runner ~

Runs test commands in a small Tmux pane. Requires the
[Vim Timux Runner](https://github.com/christoomey/vim-tmux-runner) plugin (and Tmux)
>
  let test#strategy = 'vtr'
<
<
VimShell ~

Runs test commands in a shell written in VimScript. Requires the
[VimShell](https://github.com/Shougo/vimshell.vim) plugin.
>
  let test#strategy = 'vimshell'
<
Terminal.app / iTerm.app ~

If you're in MacVim GUI, you can use this strategy to send the test commands
to your Terminal.app/iTerm.app (since executing shell commands inside Vim GUIs
isn't that nice).
>
  let test#strategy = 'terminal'
  " or
  let test#strategy = 'iterm'
<
CUSTOM STRATEGIES                               *test-custom-strategies*

Strategy is a function with command for running tests as argument.
If you want to define your own strategy - simple define new function, like this:
>
  function! MyStrategy(cmd)
    echo 'It works! Command for running tests: ' . a:cmd
  endfunction
<
Then add this function to vim-test custom strategies |dict|:
>
  let g:test#custom_strategies = {'my_strategy': function('MyStrategy')}
<
Key in this dict is a name of the strategy, value is a |Funcref|.
Choose your custom strategy:
>
  let g:test#strategy = 'my_strategy'
<
Refer to vim-test/autoload/test/strategy.vim for examples of default strategies.

CONFIGURATION                                   *test-configuration*

You may find yourself specifying certain options for your test runners in
certain situations. You can configure your prefered options with
>
  let g:test#ruby#minitest#options = '--verbose'
<
Or, if you prefer more granular approach, you can do
>
  let g:test#ruby#rspec#options = {
    \ 'nearest': '--format documentation',
    \ 'file':    '--format documentation',
    \ 'suite':   '--tag ~slow',
  \}
<
If you want to manually configure a test runner's executable, you can do
>
  let g:test#ruby#rspec#executable = 'foreman run rspec'
<
If you want to disable clearing the screen for some strategies, you can do
>
  let g:test#preserve_screen = 1
<
You can instruct test.vim to generate absolute file paths:
>
  let test#filename_modifier = ':.' " test/models/user_test.rb (default)
  let test#filename_modifier = ':p' " /User/janko/Code/my_project/test/models/user_test.rb
  let test#filename_modifier = ':~' " ~/Code/my_project/test/models/user_test.rb
<
ABOUT                                           *test-about*

You can get the latest version, see the changelog, or report a bug on GitHub:

https://github.com/janko-m/vim-test

CREDITS                                         *test-credits*

Thanks to Gary Bernhardt, the person who invented this kind of testing.
I also want to thank vim-rspec (https://github.com/thoughtbot/vim-rspec), from
which I borrowed GUI support for OS X, and Windows support. Also thanks to
vim-vroom (https://github.com/skalnik/vim-vroom).
