Use Travis CI for Vim plugin development

2013-02-08T21:12:55+09:00 / tag:vim / Comments

Travis CI provides a hosted continuous integration (CI) service for the open source community. It is integrated with GitHub and supports various languages. Since Travis CI is flexible, it is not difficult to use Travis CI for projects written in languages for which Travis CI does not offer first class support. So that it is possible to introduce CI for Vim plugins.

But there are problems to start CI for Vim plugins. For example:

Fortunately, there is a toolchain to solve the above problems. The toolchain consists of two parts; vim-vspec and vim-flavor. So that it is easy to start CI for Vim plugins with the following steps.

1. Install the toolchain to run tests

Write a Gemfile to install the toolchain, then commit it:

source 'https://rubygems.org'

gem 'vim-flavor', '~> 1.1'

Then run bundle install to install the toolchain.

2. Write a script to automate testing

Write a Rakefile to automate testing, then commit it:

#!/usr/bin/env rake

task :ci => [:dump, :test]

task :dump do
  sh 'vim --version'
end

task :test do
  sh 'bundle exec vim-flavor test'
end

Now you can run tests with rake test.

Note that tasks except test are to output extra information for tests run on Travis CI.

3. Write a configuration to run tests on Travis CI

Write a .travis.yml to configure how to run tests on Travis CI, then commit it:

language: ruby
rvm:
  - 1.9.3
script: rake ci

4. Declare dependencies of a Vim plugin to be tested

(You may skip this step if a target Vim plugin does not require any other plugins.)

Some Vim plugins require other plugins. For example, vim-textobj-function provides text objects to edit text by a function. It is not easy to implement text objects because of many edge cases. So that vim-textobj-function uses vim-textobj-user to hide such details.

And dependencies can be complex. For example,

It is hard to maintain such dependencies and compatibility problems by hand. But vim-flavor automates complex tasks. All you have to do is to write a VimFlavor to declare dependencies of a Vim plugin. For example, vim-textobj-function requires vim-textobj-user 0.3 or later (except 1.x or later). Such a dependency is declared as follows:

flavor 'kana/vim-textobj-user', '~> 0.3'

See also the document about dependency declaration of a Vim plugin.

5. Write tests for a Vim plugin

Vim plugins are run on Vim. Tests for Vim plugins often require to specify complex operations of Vim. So that the best language to write tests for Vim plugins is — Vim script.

So,

With vim-vspec, you can write tests like RSpec:

describe 'math#round_to_zero'
  it 'returns a floor for a positive number'
    Expect math#round_to_zero(1.2) == 1
    Expect math#round_to_zero(34.5) == 34
  end
end

See also tests for vim-textobj-function and tests for vim-vspec for real world examples.

6. Push the above changes to your GitHub repository

7. Brew a cup of coffee, then wait for a while…

8. Enjoy results of tests on Travis CI

Example: a result of tests for vim-textobj-function run on Travis CI