Using Vim’s client/server functionality, this library exposes a way to spawn a Vim instance and control it programatically. Apart from being a fun party trick, this can be used to do integration testing on Vimscript.
The latest stable documentation can be found on rubydoc.info.
Any issue reports or contributions are very welcome on the GitHub issue tracker.
If you don’t already have a running Vim server, Vimrunner can be used in one of two main ways:
Vim will automatically be started and killed.
Vimrunner.start do |vim| vim.edit “file.txt” vim.insert “Hello” vim.write end
Vim will automatically be started but you must manually kill it when you are
vim = Vimrunner.start vim.edit “file.txt” vim.insert “Hello” vim.write vim.kill
Vimrunner will attempt to start up the most suitable version of Vim available, meaning one of the following:
vimif it supports headlessly creating servers (see Requirements below for more information);
mvimif you are on Mac OS X;
If you wish to always start a GUI Vim (viz. skip using a headless
vim) then you can use
start_gvim like so:
“by Vimrunner.start_gvim do |vim| # … end
If you require an even more specific version of Vim, you can pass the path to it by instantiating your own
Server instance like so:
“by Vimrunner::Server.new(“/path/to/my/specific/vim”).start do |vim| vim.edit “file.txt” end
(You can also use the non-block form of
start in both of the above examples.)
start_gvim) will return a
Client instance with which you can control Vim. For a full list of methods you can invoke on the remote Vim instance, check out the
If you already have a remote-capable Vim server running, you can connect Vimrunner to it directly by using
Vimrunner.connect! like so:
Assuming a running Vim server called FOO…
vim = Vimrunner.connect(“FOO”) if vim vim.insert(“Hello world!”) end
Or, if you’re confident there’s a running server…
vim = Vimrunner.connect!(“FOO”) vim.insert(“Hello world!”)
In case of failure to find the server
FOO, the first form will return
nil, while the second form will raise an exception.
If you’re using Vimrunner for testing vim plugins, a simple way to get up and running is by requiring the
vimrunner/rspec file. With that, your
spec_helper.rb would look like this:
“uby require ‘vimrunner’ require ‘vimrunner/rspec’
Vimrunner::RSpec.configure do |config| # Use a single Vim instance for the test suite. Set to false to use an # instance per test (slower, but can be easier to manage). config.reuse_server = true
# Decide how to start a Vim instance. In this block, an instance should be # spawned and set up with anything project-specific. config.start_vim do vim = Vimrunner.start
# Or, start a GUI instance: # vim = Vimrunner.start_gvim # Setup your plugin in the Vim instance plugin_path = File.expand_path('../..', __FILE__) vim.add_plugin(plugin_path, 'plugin/my_plugin.vim') # The returned value is the Client available in the tests. vim
This will result in:
vimhelper in every rspec example, returning the configured
- Every example is executed in a separate temporary directory to make it easier to manipulate files.
- A few helper methods from the
The specs would then look something like this:
“uby require ‘spec_helper’
describe “My Vim plugin” do specify “some behaviour” do write_file(‘test.rb’, «-EOF) def foo bar end EOF
vim.edit 'test.rb' (vim) vim.write IO.read('test.rb').should eq normalize_string_indent(<<-EOF) def bar foo end EOF
If you need a different setup, please look through the file
lib/vimrunner/rspec.rb for ideas on how to build your own testing scaffold.
Vim needs to be compiled with
+clientserver. This should be available with the
huge featuresets or by using MacVim on Mac OS X. In order to start a server without a GUI, you will also need
+xterm-clipboard as described in the Vim manual.
The client/server functionality (regrettably) needs a running X server to function, even without a GUI. This means that if you’re using it for automated tests on a remote server, you’ll probably need to start it with Xvfb.
If you are using MacVim, note that you will need the
mvim binary in your
PATH in order to start and communicate with Vim servers.
vimrunner executable opens up an irb session with
$vim set to a running
mvim) client. You can use this for interactive experimentation. A few things you can try:
“uby $vim.edit ‘some_file_name’ # edit a file $vim.insert ‘Hello, World!’ # enter insert mode and write some text $vim.normal ‘T,’ # go back to the nearest comma $vim.type ‘a
Maruku could not parse this XML/HTML: <cr>' # append a newline after the comma $vim.write # write file to disk