Need help with vim-vspec?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

212 Stars 11 Forks 511 Commits 12 Opened issues


Vim plugin: Testing framework for Vim script

Services available


Need anything else?

Contributors list

No Data

vim-vspec - A testing framework for Vim script


vim-vspec is a testing framework for Vim script. It consists of:

  • Utilities to run tests in an isolated Vim process,
  • A testing framework to write tests in a format which resembles RSpec, and
  • Additional syntax/indent files for Vim script to write tests.

A typical test script written with vim-vspec looks like as follows:

runtime plugin/MyGitUtilities.vim

describe 'GetGitBranchName()' before call delete('tmp/test', 'rf') call mkdir('tmp/test', 'p') cd tmp/test end

after cd - end

context 'in a non-Git directory' it 'returns "-"' Expect GetGitBranchName('.') ==# '-' end end

context 'in a Git repository' before !git init && touch foo && git add foo && git commit -m 'Initial commit' end

it 'returns the current branch'
  Expect GetGitBranchName('.') ==# 'master'

it 'detects detached HEAD state'
  !git checkout master~0
  Expect GetGitBranchName('.') ==# 'master~0'

end end

Typical ways to run tests are as follows:

# Run tests in a specific file.
# The current directory is injected into &rutimepath before running tests.
$PATH_TO_VSPEC/bin/prove-vspec -d $PWD t/branch.vim

Like the above, but run all tests in all files under the t directory.

$PATH_TO_VSPEC/bin/prove-vspec -d $PWD t/

Like the above, but you may omit t because it's the default target.

$PATH_TO_VSPEC/bin/prove-vspec -d $PWD

Its output looks like as follows:

t/branch.vim .. ok
All tests successful.
Files=1, Tests=3,  1 wallclock secs ( 0.02 usr  0.00 sys +  0.07 cusr  0.11 csys =  0.20 CPU)
Result: PASS

runs a test script in an isolated Vim process, and show a summary like the above. User-specific configurations, like
and files in
, will never be used to avoid unintentional dependencies.

For proper testing, you have to set up environment to run tests. Suppose that you want to test a plugin which depends on some other plugins, you have to:

  • Install such dependencies to somewhere, and
  • Specify where the dependencies are installed to run tests.

These steps are tedious to do by hand. It is recommended to use vim-flavor to automate such tasks. See How to set up GitHub Actios as CI for Vim plugin development for details.

Further reading

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.