vendor/plugins/rspec/doc/src/documentation/tools/extensions/editors/index.page

   1 ---
   2 title: Editors Overview
   3 ---
   4 h2. Editors Overview
   5
   6 RSpec's commandline API and pluggable formatters makes it very easy to integrate it with external tools
   7 such as text editors (including IDEs). Below we describe the general steps you need to perform to write
   8 an RSpec plugin for your editor.
   9
  10 The RSpec team maintains a TextMate bundle which does exactly this. You may want to look at its source if
  11 you're about to write a plugin for a new editor.
  12
  13 We'd be happy to accept more editor plugins into RSpec. Please see "Contribute":../../../../community/contribute.html for
  14 details. Or, if you're a developer of an editor, perhaps you want to bundle it with the editor.
  15
  16 h3. Launch RSpec from the IDE
  17
  18 Most advanced editors provide a mechanism to launch external processes by hitting a keystroke.
  19 Depending on your editor, you may want to launch RSpec directly via the <code>spec</code> spec command
  20 (which must be on your $PATH). Alternatively, if your editor makes it possible to run Ruby scripts
  21 directly, you may execute RSpec via <code>Spec::Runner::CommandLine.run</code> (which has a similar API to
  22 the <code>spec</code> command, except you can call it straight from Ruby without forking a new Ruby process).
  23
  24 h3. Tell RSpec what spec(s) to run
  25
  26 You may want to assign different keystrokes to run your specs. You could run All specs in your project,
  27 the ones in the currently open file or just the one you have focussed in the editor.
  28 RSpec's commandline API has a <code>--line</code> option which will make RSpec run the spec at the current
  29 line (it also works if the line is inside the spec).
  30 Most editors provide a way to query the current file and the line of the cursor when launching an external
  31 process, and you can use this to feed the right argument to the --line option.
  32
  33 h3. Make the backtrace work with your editor
  34
  35 When a spec fails, the backtrace is displayed in the error message. The backtrace contains lines with
  36 file paths and line numbers. Most editors have a mechanism that will open the file and put the
  37 cursor on the right line when such a line is clicked - provided the line is on a format that the editor
  38 understands.
  39
  40 It is possible to customise the backtrace lines of RSpec's output to achieve this. All you need to do is
  41 to implement your own Formatter class, typically by subclassing
  42 "ProgressBarFormatter":../rdoc/classes/Spec/Runner/Formatter/ProgressBarFormatter.html or "HtmlFormatter":../rdoc/classes/Spec/Runner/Formatter/HtmlFormatter.html
  43 (depending on what your editor understands). In your formatter class you
  44 can override the <code>backtrace_line</code> method to make the output be something that works with your editor.
  45 Example:
  46
  47 <ruby file="../rspec/examples/pure/custom_formatter.rb"/>
  48
  49 Then, when the editor plugin launches RSpec, just make sure it uses the <code>--formatter</code>
  50 option to specify *your* custom formatter. Note that you will probably have to use <code>--require</code>
  51 too, so that the code for your custom formatter is loaded. See <code>spec --help</code> for details.