Vroom: Launch vim tests
Vroom is experimental. There are still some issues with vim that we haven't figured out how to work around. We reserve the right to make backwards incompatible changes in order to address these.
Vroom is for testing vim.
Let's say you're a vimscript author. You want to test your new plugin. You could find a nice vimscript test suite, but that only lets you test your vimscript functions. What you really want is a way to specify vim commands — actual input keys that that the user hits — and then verify vim's output.
This is a vroom test. > iHello, world!<ESC> Hello, world!
The above vroom test opens vim, sends the keys
iHello, world!<ESC> and then
verifies that the contents of the current buffer is
Things can get much more complex than this, of course. You need to be able to check the output of multiple buffers. You need to check what messages your functions echo. You need to sandbox vim, capture its system commands, and respond with dummy data. And a few shortcuts would be nice.
Never fear! Vroom has it all. Check the examples for details and more documentation. examples/basics.vroom is a good place to start.
vroom -h to learn about vroom's configuration options.
Did you accidentally set off a giant vroom test that's running too fast to halt?
Never fear! Pop open another terminal and
Make sure the
--servername flag matches with the vroom you're trying to kill.
You may need to run
reset in the terminal with the murdered vroom.
See the Tips and Tricks page page for some strategies for getting the most out of vroom.
Note that Vroom requires a version of vim built with the
vim --version to check). See
:help clientserver for
If you're on Ubuntu or Debian, you can install release packages from GitHub.
Otherwise, the easiest way to install vroom is to clone the vroom repository from GitHub, cd into the vroom directory, and run
python3 setup.py build && sudo python3 setup.py install
Vim 7.4.384 and later have built-in syntax support for the vroom filetype. You can install the standalone ft-vroom plugin for older versions of vim.
Vroom is invoked from the command-line on
vroom --help and https://github.com/google/vroom/wiki for more info on
Vroom cheat sheet
|2-space indent||output (buffer)||
- match modes (for message and system):
- output channels (for hijack):
@clear— Clear buffer contents (also triggered by 3 blank vroom lines).
@end— Ensure buffer matching reached end of buffer lines.
@messages— Override strictness for unexpected messages.
@system— Override strictness for unexpected system calls.
@macro— Define vroom macro.
@endmacro— End vroom macro and resume normal vroom processing.
@do— Invoke vroom macro defined with
By default, vroom uses vim to execute vroom files. You can instead invoke it
--neovim flag to execute vroom files inside neovim.
To use it, you need to install the neovim-mode dependencies:
- Install neovim for your platform according to the directions at https://github.com/neovim/neovim/wiki/Installing.
- Install neovim/python-client:
sudo pip3 install neovim
You can configure your vim plugin's vroom files to be tested continuously in Travis CI.
Just create a .travis.yml file at the root of your repository. The particulars may vary for your plugin, but here's an example configuration:
language: generic before_script: # Install your desired version of vroom. - wget https://github.com/google/vroom/releases/download/v0.12.0/vroom_0.12.0-1_all.deb - sudo dpkg -i vroom_0.12.0-1_all.deb # Install vim. - sudo apt-get install vim-gnome # Vroom's vim mode currently requires a running X server. - export DISPLAY=:99.0 - sh -e /etc/init.d/xvfb start # If your plugin depends on maktaba, clone maktaba into a sibling directory. - git clone https://github.com/google/vim-maktaba.git ../maktaba/ script: - vroom --crawl ./vroom/
It's also possible to test your plugin against neovim, but the recommended instructions are still being finalized. Details coming soon.
Vroom uses vim as a server. Unfortunately, we don't yet have a reliable way to detect when vim has finished processing commands. Vroom currently relies upon arbitrary delays. As such, tests run more slowly than is necessary. Furthermore, some lengthy commands in vroom tests require additional arbitrary delays in order to make the tests pass.