Fetching contributors…
Cannot retrieve contributors at this time
146 lines (101 sloc) 5.09 KB

RubySpecs and MagLev

We've included a recent copy of the MSpec framework (spec/mspec) and the RubySpecs (spec/rubyspec). It is the version we used when we built the system.



All of the spec related files are under $MAGLEV_HOME/spec, except the default.mspec and passing.mspec config files which live in the $MAGLEV_HOME directory.


A file read by default.mspec that list the specs under rubyspec that have a syntax error or otherwise prevent any of the expectations in that file from running. Many of the files listed here have a counterpart in localspec that has the offending bits removed.


A directory that holds the Gemstone fixes for rubyspecs that cause MagLev to choke.


A git submodule that tracks the MSpec framework.


A git submodule that tracks the RubySpecs.


The Gemstone RubySpec tags. These are maintained in the MagLev git repository.

Run MSpec with rake

There are several rake tasks that help with the specs. The most important are:

$ rake -T spec
rake spec:ci          # Run the continuous integration specs (was passingpsecs) on MagLev
rake spec:debugci     # Run the continuous integration specs on MagLev with debug
rake spec:mri         # Run the continuous integration specs against MRI

Run MSpec manually

Assuming maglev-ruby is on your PATH, you can run specs like this:

$ spec/mspec/bin/mspec -t m spec/rubyspec/core/array/at_spec.rb

To run with debug mode on (so that you end up in the Topaz prompt on an error):

$ spec/mspec/bin/mspec -t m -T -d spec/rubyspec/core/array/at_spec.rb

Tag Failing Specs

MSpec allows you to place arbitrary tags on expectations. The tags are kept in a separate directory hierarchy outside of the rubyspec dir. For the MagLev development environment, the hierarchy is kept in spec/tags/frozen, and is checked into git. The tag files are named according to the :tags_patterns configuration parameter in default.mspec at the top level git directory:

# The set of substitutions to transform a spec filename into a tag
# filename.  The transformations are applied, in the given sequence, to
# a filename, yielding a tag file name.
set :tags_patterns, [
  [%r(spec/rubyspec/), 'spec/frozen/'],
  [%r(spec/), 'spec/tags/'],
  [/_spec.rb$/, '_tags.txt']

The MagLev scheme puts the tags for a given spec into a parallel directory hierarchy under spec/tags/frozen. So, the tags for spec/rubyspec/core/array/at_spec.rb are in spec/tags/frozen/core/array/at_tags.txt.

The mspec-tag command will run tests and then tag them based on the results of running the tests.

default action

add a tag What action to take when triggered

default tag

“fails” The default tag to work on

default outcome

:fail The spec outcome that triggers the tag action

Together, the above defaults say “when the test outcome is :fail, then add a tag named ”fails“ for that expectation.

Tag Examples

Note: we don't need to specify -n maglev-ruby or -t maglev, since the defaults.mspec file has that configured.

Tag all failing specs

To tag failing specs, you can do something like the following, which tags all the failing Array specs:

$ spec/mspec/bin/mspec tag spec/rubyspec/core/array/

But suppose there are already some failures recorded, especially for some nasty bugs that prevent mspec from continuing. Then you can also add -G fails so that the tagging run won't run specs that are already known to fail, i.e., it will add to the known failures in a “safe” manner:

$ spec/mspec/bin/mspec tag -G fails spec/rubyspec/core/array/
Run specs, ignoring any tagged as fails

The -G tag option means: Exclude examples with descriptions tagged with tag:

$ spec/mspec/bin/mspec -G fails spec/rubyspec/core/array/

We have now tagged failing rubyspecs in four categories. The following switches can be used o bypass all specs that don't run:

-G fails -G breaks -G crashes -G hangs.
Run specs, untagging fixed expectations

If you've made some code changes to MagLev, and expect some previously failing specs to now pass, you can re-run the failing specs and have mspec un-tag the ones that now pass:

# delete the fails tag if the spec now runs
$ spec/mspec/bin/mspec tag --del fails spec/ruby/core/array/append_spec.rb
Tag arbitrary specs

The following will tag all the specs in select_spec.rb with the fails tag:

$ spec/mspec/bin/mspec tag --add fails -L spec/rubyspec/core/array/select_spec.rb

The -L says to “do the action” (in this case, tag) to all the specs that match (i.e. all expectations in select_spec.rb).