RSpec TextMate Bundle

This bundle works with TextMate 2 and RSpec 2 and 3. For TextMate 1 and/or RSpec 1 please use the legacy version from the branch “rspec1-textmate1”.

Installation

Open up TextMate’s preferences, go to “Bundles” and make sure “RSpec” is checked.

Running RSpec examples

Commands for running examples:

Run Examples ⌘R: Run all examples in the current spec file.
Run Single Example ⇧⌘R: Run the example on the current line (also works for example groups).
Run Examples in Selected Files/Directories ⌥⇧⌘R: Run all examples from the files / directories selected in the file browser. If nothing is selected, run all examples in spec/. Hint: ⇧⌘A ⌥⇧⌘R is a quick way to run all specs (⇧⌘A deselects everything in the file browser).
Run Again ⌥⌘R: Repeat the last run command (can be example file, single example or examples in selected files).

If your project has an .rspec file in its root, the last two commands – “Run Examples in Selected Files/Directories” and “Run Again” – are available everywhere in your project (even in files that not using the “RSpec” mode).

Configuring TextMate for running examples

The bundle runs RSpec in a subshell. The command to start RSpec is determined as such:

If a binstub (bin/rspec) is present, it is used for running RSpec (this works great for preloaders like Spring, too).
If there is no binstub, but Gemfile.lock is present, RSpec is run via bundle exec rspec.
If there is neither a binstub nor a Gemfile.lock, RSpec is simply run via rspec (not recommended – use only if you know exactly what you’re doing).

Running RSpec / Ruby from a subshell means that TextMate must be configured to work with whatever Ruby version manager you're using (rbenv, rvm, …). Normally, this means customizing the $PATH variable. See Defining a $PATH in the TextMate blog for details and caveats.

Setting the base directory for running examples

Per default, RSpec is run from the directory currently designated as “project folder” in TextMate. This can be overriden by setting TM_RSPEC_BASEDIR.

It’s even possible to have different base directories for running RSpec in a single project. Take for example a Rails Engine with the following directory layout:

app/        # Rails app
spec/       # examples for the Rails app
my_engine/
  app/      # Engine
  spec/     # examples for the Engine

The examples for the Rails app should be run from the top-level directory, but the examples for the Engine should be run from my_engine/.

To achieve this, create a file my_engine/.tm_properties with the following line:

TM_RSPEC_BASEDIR=$CWD

This makes sure that TM_RSPEC_BASEDIR is set to the full path of the my_engine/ directory whenever you’re editing a file in this directory (or one of its subdirectories). So if you’re editing my_engine/spec/foo_spec.rb and press ⌘R to run the examples, they will be run from the my_engine/ directory, while running examples in, say, spec/bar_spec.rb are still run from the top-level project directory.

Configuration

In addition to the standard TextMate shell variables, the RSpec TextMate bundle supports the following:

TM_RSPEC_BASEDIR

Set the base directory for running RSpec (defaults to the current “Project Folder”). See “Setting the base directory for running examples” above for more info and an example.

TM_RSPEC_FORMATTER

Set a custom formatter other than RSpec's TextMate formatter. Use the full classname, e.g. 'Spec::Core::Formatters::WebKit'

TM_RSPEC_OPTS

Use this to set RSpec options just as you would in an .rspec file.

RVM Integration

[NOTE: Information in this section may be outdated]

There are lots of ways to configure TextMate to work with rvm, but this is the one that we recommend:

With rvm installed, take the full path to rvm-auto-ruby, found via: which rvm-auto-ruby

Next, set up a TM_RUBY option in TextMate/Preferences/Advanced/Shell Variables that points to the rvm-auto-ruby command.

Learn more at:

History

Parts of RSpec.tmbundle are based on Florian Weber's TDDMate.

License

The license of RSpec.tmbundle is the same as RSpec's.

jefffederman/rspec.tmbundle