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. github.com/rubyspec/mspec
A git submodule that tracks the RubySpecs. github.com/rubyspec/rubyspec
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:
$ cd $MAGLEV_HOME $ 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):
$ cd $MAGLEV_HOME $ 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.
add a tag What action to take when triggered
“fails” The default tag to work on
: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.
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).