Editors

RSpec’s commandline API and pluggable formatters makes it very easy to integrate it with external tools such as text editors (including IDEs). Below we describe the general steps you need to perform to write an RSpec plugin for your editor.

The RSpec team maintains a TextMate bundle which does exactly this. You may want to look at its source if you’re about to write a plugin for a new editor.

We’d be happy to accept more editor plugins into RSpec. Please see Contribute for details. Or, if you’re a developer of an editor, perhaps you want to bundle it with the editor.

Launch RSpec from the IDE

Most advanced editors provide a mechanism to launch external processes by hitting a keystroke. Depending on your editor, you may want to launch RSpec directly via the spec spec command (which must be on your $PATH). Alternatively, if your editor makes it possible to run Ruby scripts directly, you may execute RSpec via Spec::Runner::CommandLine.run (which has a similar API to the spec command, except you can call it straight from Ruby without forking a new Ruby process).

Tell RSpec what spec(s) to run

You may want to assign different keystrokes to run your specs. You could run All specs in your project, the ones in the currently open file or just the one you have focussed in the editor. RSpec’s commandline API has a --line option which will make RSpec run the spec at the current line (it also works if the line is inside the spec). Most editors provide a way to query the current file and the line of the cursor when launching an external process, and you can use this to feed the right argument to the—line option.

Make the backtrace work with your editor

When a spec fails, the backtrace is displayed in the error message. The backtrace contains lines with file paths and line numbers. Most editors have a mechanism that will open the file and put the cursor on the right line when such a line is clicked – provided the line is on a format that the editor understands.

It is possible to customise the backtrace lines of RSpec’s output to achieve this. All you need to do is to implement your own Formatter class, typically by subclassing ProgressBarFormatter or HtmlFormatter (depending on what your editor understands). In your formatter class you can override the backtrace_line method to make the output be something that works with your editor. Example:

require File.dirname(__FILE__) + '/spec_helper'
require 'spec/runner/formatter/progress_bar_formatter'

# Example of a formatter with custom bactrace printing. Run me with:
# ruby bin/spec failing_examples -r examples/custom_formatter.rb -f CustomFormatter
class CustomFormatter < Spec::Runner::Formatter::ProgressBarFormatter
  def backtrace_line(line)
    line.gsub(/([^:]*\.rb):(\d*)/) do
      "<a href=\"file://#{File.expand_path($1)}\">#{$1}:#{$2}</a> "
    end
  end
end

Then, when the editor plugin launches RSpec, just make sure it uses the --formatter option to specify your custom formatter. Note that you will probably have to use --require too, so that the code for your custom formatter is loaded. See spec --help for details.