A simple Vimscript test framework
I use Vader to test Vimscript.
Use your favorite plugin manager.
Plug 'junegunn/vader.vim'to .vimrc
Vader [file glob ...]
Vader! [file glob ...]
vim '+Vader!*' && echo Success || echo Failure
--noforkoption when using GVim)
TODO, the block is recognized as a pending test case and does not affect the exit status.
VADER_OUTPUT_FILEis set, the test results will be written to it as well, otherwise they are written to stderr using different methods (depending on Neovim/Vim).
A Vader file is a flat sequence of blocks each of which starts with the block label, such as
Execute:, followed by the content of the block indented by 2 spaces.
If you want to skip 2-space indention, end the block label with a semi-colon instead of a colon.
The content of a Given block is pasted into the "workbench buffer" for the subsequent Do/Execute blocks. If
filetypeparameter is given,
&filetypeof the buffer is set accordingly. It is also used to syntax-highlight the block in .vader file.
Given [filetype] [(comment)]: [input text]
The content of a Do block is a sequence of normal-mode keystrokes that can freely span multiple lines. A special key can be written in its name surrounded by angle brackets preceded by a backslash (e.g.
Do block can be followed by an optional Expect block.
Do [(comment)]: [keystrokes]
The content of an Execute block is plain Vimscript to be executed.
Execute block can also be followed by an optional Expect block.
Execute [(comment)]: [vimscript]
In Execute block, the following commands are provided.
Assert [, message]
AssertEqual , [, message]
AssertNotEqual , [, message]
Save [, ...]
Restore [, ...]
The following syntax helper functions are provided:
SyntaxAt: return a string with the name of the syntax group at the following position:
SyntaxAt(): current cursor position
SyntaxAt(col): current cursor line, at given column
SyntaxAt(lnum, col): line and column
SyntaxOf(pattern[, nth=1]): return a string with the name of the syntax group at the first character of the nth match of the given pattern. Return
''if there was no match.
The path of the current
.vaderfile can be accessed via
In addition to plain Vimscript, you can also test Ruby/Python/Perl/Lua interface with Execute block as follows:
Execute [lang] [(comment)]: [ code]
See Ruby and Python examples here.
A Then block containing Vimscript can follow a Do or an Execute block. Mostly used for assertions. Can be used in conjunction with an Expect block.
Then [(comment)]: [vimscript]
If an Expect block follows an Execute block or a Do block, the result of the preceding block is compared to the content of the Expect block. Comparison is case-sensitive.
filetypeparameter is used to syntax-highlight the block.
Expect [filetype] [(comment)]: [expected output]
The content of a Before block is executed before every following Do/Execute block.
Before [(comment)]: [vim script]
The content of an After block is executed after every following Do/Execute block.
After [(comment)]: [vim script]
You can include other vader files using Include macro.
Any line that starts with
*without indentation is considered to be a comment and simply ignored.
################### # Typical comment # ###################
# Test case Execute (test assertion): %d Assert 1 == line('$')
setf python AssertEqual 'python', &filetype
Given ruby (some ruby code): def a a = 1 end
Do (indent the block): vip=
Expect ruby (indented block): def a a = 1 end
Do (indent and shift): vip= gv>
Expect ruby (indented and shifted): def a a = 1 end
Given c (C file): int i = 0;
Execute (syntax is good): AssertEqual SyntaxAt(2), 'cType' AssertEqual SyntaxOf('0'), 'cNumber'
When you test a plugin, it's generally a good idea to setup a testing environment that is isolated from the other plugins and settings irrelevant to the test. The simplest way to achieve this is to start Vim with a mini .vimrc as follows:
Travis CI integration
To make your project tested on Travis CI, you need to add.travis.ymlto your project root. For most plugins the following example should suffice.language: vim
before_script: | git clone https://github.com/junegunn/vader.vim.git
script: | vim -Nu /dev/null
(Note thatvimis not a valid language for Travis CI. It just sets up Ruby execution environment instead as the default.)
See the wiki page.
The keystrokes given to the feedkeys() function are consumed only after Vader finishes executing the content of the Do/Execute block. Take the following case as an example:
Do (Test feedkeys() function): i123 \:call feedkeys('456')\ 789
Expect (Wrong!): 123456789
You may have expected
123456789, but the result is
123789456. Unfortunately I have yet to find a workaround for this problem. Please let me know if you find one.
It is reported that CursorMoved event is not triggered inside a Do block. If you need to test a feature that involves autocommands on CursorMoved event, you have to manually invoke it in the middle of the block using
Do (Using doautocmd): jjj :doautocmd CursorMoved\
This is likely a bug of Vim itself. For some reason, search history is not correctly updated when searches are performed inside a Do block. The following test scenario fails due to this problem.
Execute (Clear search history): for _ in range(&history) call histdel('/', -1) endfor
Given (Search and destroy): I'm a street walking cheetah with a heart full of napalm I'm a runaway son of the nuclear A-bomb I'm a world's forgotten boy The one who searches and destroys
Do (Searches): /street<cr> /walking<cr> /cheetah<cr> /runaway<cr> /search<cr>
Execute (Assertions): Log string(map(range(1, &history), 'histget("/", - v:val)')) AssertEqual 'runaway', histget('/', -2) AssertEqual 'search', histget('/', -1)
The result is given as follows:
Starting Vader: 1 suite(s), 3 case(s) Starting Vader: /Users/jg/.vim/plugged/vader.vim/search-and-destroy.vader (1/3) [EXECUTE] Clear search history (2/3) [ GIVEN] Search and destroy (2/3) [ DO] Searches (3/3) [ GIVEN] Search and destroy (3/3) [EXECUTE] Assertions > ['search', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '', ''] (3/3) [EXECUTE] (X) Assertion failure: 'runaway' != '' Success/Total: 2/3 Success/Total: 2/3 (assertions: 0/1) Elapsed time: 0.36 sec.