An introduction to vspec


Run time:

Vspec is a library that allows you to test-drive your Vimscript code. In this tutorial, we’ll cover the basics: how to inspect the contents of a buffer, how to simulate the actions of a user, and how to invoke user-defined mappings.


Vspec lets you write tests for you Vimscript code, following a format that resembles rspec. We can use a describe block to specify a context, then wrap each individual test in an it block. Each of these blocks is closed with an end keyword, just like in ruby:

describe 'vspec'
  it 'is inspired by rspec'

Check out Kana Natsuno’s blog post for instructions on how to set up a Vim plugin to be tested by vspec.

Sample code

Here’s the vspec code that was demonstrated in the video:

nnoremap x daw

describe 'vspec'

    put! = 'Welcome to Vimcasts'


  it 'can read the contents of the buffer'
    Expect getline(1) == "Welcome to Vimcasts"

  it 'feels just like operating Vim!'
    normal gg$
    normal daw
    Expect getline(1) == 'Welcome to'
    Expect getreg('"') == ' Vimcasts'

  it 'can exercise user-defined mappings'
    normal gg$
    normal x
    Expect getline(1) == 'Welcome to'
    Expect getreg('"') == ' Vimcasts'


:normal Vs :normal!

In the demo, I used the :normal command. It’s worth noting that the :normal! command, when used with a trailing bang, will avoid user-defined mappings. That’s useful if you want to invoke built-in functionality. For example, if we had used :normal! x in our vspec test, then it would have invoked Vim’s built-in x command, ignoring our custom mapping.

In Learn Vimscript the Hard Way, Steve Losh says “when writing Vim scripts you should always use normal!, and never use plain old normal”. This is good advice when writing plugin functionality, but you can disregard it when writing vspec tests for that same plugin. If you want to test the functionality of a user-defined mapping, then :normal (without the bang) is the way to do it.

Further reading


Level-up your Vim


Boost your productivity with a Vim training class. Join a public class, or book a private session for your team.

Drew hosted a private Vim session for the shopify team that was one of the best workshops I have ever attended.

John Duff, Director of Engineering at Shopify


Make yourself a faster and more efficient developer with the help of these publications, including Practical Vim (Pragmatic Bookshelf 2012), which has over 50 five-star reviews on Amazon.

After reading it, I've switched to vim as my default editor on a daily basis with no regrets. ★★★★★

Javier Collado

Learn to use Vim efficiently in your Ruby projects

In association with thoughtbot, one of the most well respected Rails consultancies in the world, I've produced a series of screencasts on how to make navigating your Ruby projects with Vim ultra-efficient. Along the way, you’ll also learn how to make Ruby blocks a first-class text object in Vim. This lets you edit Ruby code at a higher level of abstraction. Available to buy from thoughtbot..