Spackle

Smoothing out the gaps between the Rubyist and the Ruby.

Well, honestly, it only fills in the gaps between RSpec and Vim right now, but that’s a good start. Cucumber support is in the works, and perhaps a few other surprises if I make the time.

Patches supporting other editors gladly accepted. Most people aren’t very editor-agnostic, but Spackle doesn’t care! (Or, at least, it wouldn’t if you patched it with support for your amazing editor that’s surely better than mine.)

Elevator Pitch

Spackle tells your editor about the errors in your code. No more need to visually scan your test output for errors, filenames, and line numbers. Just tell your editor to jump to the next error location.

Features

custom RSpec formatters that generate output compatible with Vim’s quickfix functionality
a simple Vim plugin to allow a quickfix list to be loaded from a file
shell scripts to glue Spackle’s output and Vim together
easy to use?

Quick Installation

gem install spackle --source http://gemcutter.org
spackle --install vim  # described below
echo 'Spackle.configuration.set_defaults_for :vim' > ~/.spackle

Configuration and Usage

For a tool that doesn’t do a heck of alot, it’s pretty configurable. If it could do something else, it’d be easy to tell it how to do it with either a .spackle file in your home directory, or a .spackle file in your project’s root directory.

If Spackle is useful to you, I’d love to hear about it.

PATH

Spackle installs a few utility scripts in the bin directory where executables are installed by your system’s Rubygems. If you’ve installed Spackle as root, this should be fine. If you’ve installed Spackle as a regular user, you need to make sure the appropriate bin directory is in your path.

To test your configuration, run which spackle in your terminal. If you don’t see any output, your PATH variable is not correctly configured for use with user-installed gems.

See your Rubygems documentation for more information about this.

Spackle dotfile

Without a dotfile configured, Spackle won’t do anything. This is so you can make Spackle a dependency of your project and integrate it into your code, yet leave its usage up to each individual developer.

Spackle reads its configuration from a .spackle file, which it looks for in your home directory first, and in the root directory of your project second. Spackle configuration in your project directory takes precedence over any in your home directory, so you can override global settings on a per-project basis if you like.

Example .spackle for Vim users.

Spackle.configure do |c|
  c.set_defaults_for :vim
end

See Spackle::Configuration for more information.

RSpec

Add to your spec_helper.rb:

require "spackle"
Spackle.init :with => :spec_formatter

Note: if you’re not otherwise explicitly specifying a standard RSpec formatter, Spackle’s formatter will swallow all your test run results, which probably isn’t what you want. To prevent this, simply make sure you specify another RSpec output formatter. Probably the easiest way to do this is to ensure you have the following in your spec/spec.opts

--format progress

Now whenever RSpec runs, Spackle will listen in to your test results and relay information about any errors to your editor.

Vim

Spackle needs a tiny Vim plugin installed to function properly with Vim. Simply run spackle install vim and Spackle will copy its plugin into your .vim/plugins directory.

Optional: Spackle also comes with a helper script for invoking Vim with a session named after your project’s parent directory. It’s called spackle-vim-open. If you’d like to use it, you’ll probably want to add an alias to your .profile or .bashrc. Example:

alias e='spackle-vim-open'

Architecture

Spackle’s architecture consists of three components.

NOTE: Some of this information looks forward to a future version of Spackle that, at the moment, is fictional. So if you go looking for some of the things referenced here and you can’t find them, that’s probably why. (Or it could be an error in this document!)

Error Parser Adapters

integrate with test harnesses like RSpec and Cucumber
or integrate with Ruby’s standard Error API
or parse Ruby’s standard backtrace output
convert error output into a generic intermediary Spackle::Error format
pass the errors to Spackle’s core for reformatting and output
found in Spackle::Spec, Spackle::Cucumber and Spackle::Ruby

Spackle Core

glues all the pieces together
loads user configuration
tries to do as much as it can automagically
tries to stay out of your way
routes Spackle::Error objects from the Adapters, through an Output Formatter, and finally to an output file
triggers a callback after every test run that can send error information to your editor

Output Formatters

convert the generic Error format into an output-specific format for your callback to handle
found in Spackle::Output

Spackle’s core configuration, tries to do as much automagically as it can, and tries to stay out of the way. It aids the models by routing Errors to the configured output formatter.

Known Issues

Spackle assumes you’re using something UNIXy. If you’re not, it likely won’t work. I have no interest in working on this, but I’ll gladly pull your patches.
Spackle’s current implementation only catches test failures from RSpec. Other hooks are in the works.

Credits

Spackle was inspired by wincent.com/blog/running-rspec-specs-from-inside-vim

Note on Patches/Pull Requests

This section was generated by Jeweler’s boilerplate, but it seems pretty sensible.

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.