MSpec provides a simple way to specify configuration options for the runner scripts by putting them in a file rather than using command line switches. The config files are simply Ruby files. There may be zero or more config files. The runner scripts attempt to load several config files by default. Additional config files can be specified with the -B, --config FILE command line option.
The runner scripts attempt to load the following config files in order:
default.mspecruby.1.8.mspec or ruby.1.9.mspec~/.mspecrcConfig files loaded later will override settings in config files loaded earlier. All the default config files are loaded before command line options are processed, so command line options will override config file options. Config files loaded with the -B option can override any options set before the file is loaded. Command line options are parsed left-to-right.
A config file has the following structure:
class MSpecScript
# An ordered list of the directories containing specs to run
# as the CI process.
set :ci_files, [
'spec/frozen/1.8/core',
'spec/frozen/1.8/language',
'spec/core',
'spec/compiler',
'^spec/compiler/new_compiler_spec.rb',
# These additional directories will be enabled as the
# specs in them are updated for the C++ VM.
# 'spec/debugger',
# 'spec/subtend',
# 'spec/parser',
]
# The set of substitutions to transform a spec filename
# into a tag filename.
set :tags_patterns, [
[%r(spec/ruby/), 'spec/frozen/'],
[%r(spec/), 'spec/tags/'],
[/_spec.rb$/, '_tags.txt']
]
# The default implementation to run the specs.
set :target, 'bin/rbx'
end
The MSpecScript class defines the set class method. The config file simply opens the MSpecScript class and sets various options. Since the file is simply Ruby code, any valid Ruby code can be used.
There are a variety of config options. These are listed below with their function and default values.
:path = [".", "spec"]
The directories to search when loading config files.
:config_ext = ".mspec"
The extension to append to a config file name if the bare name is not found. This enables specifying, for example, -B full for loading full.mspec
The mspec script does not run the specs directly. Instead, it processes options and invokes a runner script. These config options provide control over how the runner script is invoked.
:target = ENV["RUBY"] || "ruby"
The implementation to execute the runner script. Set with the -t, --target TARGET option.
:flags = []
Options to pass to the implementation executing the runner script. Set with the -T, --target-opt OPT option. (Compare with :options below.)
:command = "run"
The runner script to invoke, where run runs the specs, ci runs the CI set, and tag adds or removes tags.
:options = []
Options that are passed to the runner script itself. This is used internally by the mspec front script.
:requires = []
Libraries for the implementation executing the runner script to require before loading the runner script. Set with the -r, --require LIBRARY option.
:abort = true
When true, registers a signal handler for SIGINT that exits immediately.
:tags_patterns = []
A set of transformations applied in sequence to transform the name of a spec file to the name of the corresponding tag file. (See the config file example above.)
:includes = []
The set of strings to match for specs that will be run. Each string is converted into an escaped Regexp. Set with the -e, --example STR option.
:excludes = []
The set of strings to match for specs that will NOT be run. Set with the -E, --exclude STR option.
:patterns = []
The set of patterns to match for specs that will be run. Each pattern is converted into an unescaped Regexp so valid Regexp characters are accepted. Set with the -p, --pattern PATTERN option.
:xpatterns = []
The set of patterns to match for specs that will NOT be run. Set with the -P, --excl-pattern PATTERN option.
:tags = []
The set of tags to match for specs that will be run. Set with the -g, --tag TAG option.
:xtags = []
The set of tags to match for specs that will NOT be run. Set with the -G, --excl-tag TAG option.
:profiles = []
Profiles are YAML files that specify sets of methods for which to run specs.
An example profile for the Mutex class follows:
Mutex#: - lock - locked? - synchronize - unlock Mutex_m.: - define_aliases - extend_object Mutex_m#: - mu_extended - mu_initialize
This config item is the set of profiles for specs that will be run. Set with the -w, --profile FILE option.
:xprofiles = []
The set of profiles for specs that will NOT be run. Set with the -W, --excl-profile FILE option.
:files = []
Specifies a list of files for mspec-run to process if no files are given on the command line.
The entries in the list may be:
Dir[].Entries can be omitted from the list by putting '^' as the first character. The entries are processed in order, so an exclude entry (one with '^') will only remove items from the list if they are already in the list. Note that the exclusion facility works in the mspec runners for paths and files specified on the command line as well.
:ci_files = []
Specifies a list of files for mspec-ci no process if no files are given on the command line. Follows the same rules as :files above.
:formatter = nil
The method of displaying the results of running the specs. When nil, the DottedFormatter is used if the number of files to run is less than 50. Otherwise, the FileFormatter is used. Set to false to not use any formatter. This is used internally, for example, by mspec-tag to list specs that have been tagged. Set with the -f, --format FORMAT option.
The mspec-tag adds or removes tags for specs.
:tagger = :add
The default action is to add tags. The action is set with the -N, --add TAG and -R, --del TAG options.
:tag = "fails"
The default tag to add. Set with the TAG argument to the --add or --del options.
:outcome = :fail
The result of running a spec that triggers the specified tag action. The default is when the spec fails. Set with the -Q, --pass, -F, --fail, and -L, --all options.
:ltags = []
The set of tags for which to list tagged specs. Set with the --list TAG option.
While the specs are being run, certain actions can be invoked when a matching spec is encountered. (See e.g. the --spec-debug and --spec-gdb options for mspec-run.)
:atags = []
The set of tags for which to invoke the specified action. Set with the -K, --action-tag TAG option.
:astrings = []
The set of strings for matching specs for which to invoke the specified action. Set with the -S, --action-string STR option.
In some cases, Ruby exhibits different behaviors based on its execution environment. For example, the maximum value of a Fixnum before it is promoted to a Bignum is different in 32-bit and 64-bit platforms. In this cases you can use the
platform_is guard:
platform_is :wordsize => 32 do
it "converts numbers to Bignums if they get too big" do
# 32-bit behaviour goes here
end
end
platform_is_not :os => :windows do
it "runs on a real OS"
# do something...
end
end
This would "do something" on every OS but Windows.
Since each Ruby implementation may have its own quirks, you can make use of the compliant_on/non_compliant_on set of guards to make sure that your specs run only on certain implementations:
non_compliant_on :jruby do
# some code that works differently in JRuby
end
Since we're using this project to specify the behavior of MatzRuby (MRI), every compliant_on guard should include :ruby and no non_compliant_on should have it.
If you know that a certain version of Ruby has a bug and you want to guard against it you can use the ruby_bug guard:
ruby_bug "some_id_number", "version" do
it "produces 2 when adding 1 to 1" do
# CORRECT implementation goes here
(1 + 1).should == 2
end
end
In this case, some_id_number is the number of the reported issue in Ruby's Redmine tracker (because you did create an issue for this, right?). version is the Ruby version you want to guard against, for example:
ruby_bug "#1337", "1.8.6.110" do
it "produces 2 when adding 1 to 1" do
(1+1).should == 2
end
end
In this case the issue was reported in Ruby's Redmine as ticket #1337 and this spec will be ignored when the Ruby version is ruby-1.8.6 patchlevel 110.
Sometimes the behavior of certain methods will change between different Ruby versions (or revisions). If you're writing specs against several patchlevels or releases you can use the ruby_version_is guard:
ruby_version_is "" ... "1.9" do
it "adds two numbers" do
(1+1).should == 2
end
end
ruby_version_is "1.9" do
it "adds two numbers" do
(1+1).should == 3
end
end
In this case we're assuming that 1 + 1 will equal 2 in every version before 1.9 and that in 1.9 and following versions it will return 3.
If you need to make sure that you're root before running some of your specs you can use the as_superuser guard:
as_superuser do
it "is dangerous" do
FileUtils.rm_rf("/")
end
end
If the user running the specs is not root (UID = 0) the specs will be ignored.
If a Ruby implementation does not support a certain feature (and probably won't support it in the future) you can use the not_supported_on guard:
not_supported_on :rubinius do
it "does some crazy stuff that rubinius people seem to hate" do
end
end
Please note that this guard should only be used when you're almost certain that a feature won't be supported in a Ruby implementation. If you intend to guard a certain case while the implementation supports it you're better off using the MSpec tagging mechanism.
If the implementation you're specifying differs from MRI you should use the non_compliant_on guard.
If you want to make sure that another class or module is not defined in the current scope before running some tests you can use the conflicts_with guard:
conflicts_with :SomeWeirdClass do
it "will not be run if SomeWeirdClass is defined" do
...
end
end
In this case the spec will run only if SomeWeirdClass is not currently defined. It won't run if SomeWeirdClass is part of the Core classes, if it was required/included or if it was defined earlier.
In some cases you might want to make sure that a set of specs runs only under a certain runner (rSpec or MSpec). You can use the runner_is/runner_is_not guards to check this:
runner_is :rspec do
it "does something that only runs under rSpec" do
...
end
end
runner_is :mspec do
it "does something that only runs under MSpec" do
...
end
end
This guard will always return false, which means that the cases inside it will never be run. There are only a handful of acceptable uses for this guard, so please make sure to check on IRC before using it:
quarantine! do
it "will never be run" do
...
end
end
Helper for syntax-sensitive specs. The specs should be placed in a file in the versions subdirectory. For example, suppose language/method_spec.rb contains specs whose syntax depends on the Ruby version. In the language/method_spec.rb use the helper as follows:
language_version __FILE__, "method"
Then add a file "language/versions/method_1.8.rb" for the specs that are syntax-compatible with Ruby 1.8.x.
The general organization of the specs is one directory per class/module, one subdirectory per sub-class/module, and one file per method name. For example, for the Kernel module, there is the rubyspec/1.8/core/kernel directory, and there is the gsub_spec.rb that contains specs for Kernel#gsub and Kernel.gsub (i.e. instance method and module method).
The mkspec script can be used to create the skeleton files for all the methods of a class or module. The script will create the directory and file if they do not exist. If the file exists, it will be executed by mspec-run with the --dry-run option, essentially parsing the specs to check if there is a spec for the method. If not, a signpost spec like the following is inserted into the file.
describe "Float#to_s" do
it "needs to be reviewed for spec completeness" do
end
end
The purpose of the signpost spec is to provide visibility of specs for methods that are partially, or completely, missing. Generally, these specs are then tagged with 'incomplete', which is excluded from mspec-ci runs. The signpost specs should be removed once reasonably complete specs have been written for the method.
The mkspec script can be run repeatedly without affecting existing files. So, if you use it to generate files but do not fill in specs for them all. you can commit only the files that have specs and re-run the script later to re-create the files for methods not yet spec'd. In general, this is preferable to checking in numerous files that only have signpost specs in them. However, there are a number of previously empty files in the repository that have been updated using the new mkspec functionality.
$ bin/mkspec -h
mkspec [options]
-c, --constant CONSTANT Class or Module to generate spec stubs for
-b, --base DIR Directory to generate specs into
-r, --require LIBRARY A library to require
How might this work in the real world?
1. To create spec stubs for every class or module in Object
$ mkspec
2. To create spec stubs for Fixnum
$ mkspec -c Fixnum
3. To create spec stubs for Complex in 'superspec/complex'
$ mkspec -c Complex -rcomplex -b superspec
The mkspec command is intended to be run by MatzRuby. The help text above gives examples of invoking mkspec under typical circumstances.
Unlike the runner scripts, mkspec does not have a --target option. This are essentially two reasons for this. Firstly, the specs are for ensuring compatibility with the "standard" reference implementation (commonly called MRI, or MatzRuby). So, it is the classes and modules of that implementation that are of general interest. Secondly, having the --target option requires re-exec'ing the script with a different implementation. That complexity isn't really justified.
However, if you need to create specs for an implementation-specific class or module, it's still rather easy to do. For example, to create Rubinius specs for the Mailbox class, you could use the following:
shotgun/rubinius mspec/bin/mkspec -b spec/library/ -r mailbox -c Mailbox
The spec runner scripts are separated into two main parts. The first part is in bin/mspec. This script gathers all options needed to invoke the actual program that will execute the specs. The following options are available:
$ bin/mspec -h
mspec [COMMAND] [options] (FILE|DIRECTORY|GLOB)+
The mspec command sets up and invokes the sub-commands
(see below) to enable, for instance, running the specs
with different implementations such as ruby, jruby, rbx, etc.
-B, --config FILE Load FILE containing configuration options
-t, --target TARGET Implementation to run the specs, where:
r or ruby invokes ruby in PATH
r19 or ruby19 invokes ruby19 in PATH
x or rubinius invokes ./bin/rbx
X or rbx invokes rbx in PATH
j or jruby invokes jruby in PATH
i or ironruby invokes ir in PATH
-T, --target-opt OPT Pass OPT as a flag to the target implementation
-I, --include DIR Pass DIR through as the -I option to the target
-r, --require LIBRARY Pass LIBRARY through as the -r option to the target
-D, --gdb Run under gdb
-A, --valgrind Run under valgrind
--warnings Don't supress warnings
-j, --multi Run multiple (possibly parallel) subprocesses
-v, --version Show version
-h, --help Show this message
where COMMAND is one of:
run - Run the specified specs (default)
ci - Run the known good specs
tag - Add or remove tags
mspec COMMAND -h for more options
-B, --config FILE
Load FILE containing configuration options. Refer to the configuration document.
-t, --target TARGET
Selects the Ruby implementation to be used to execute the spec files.
-T, --targetopt OPT
Passes OPT as a flag to the target implementation, For example, bin/mspec -T "-d" -t r would pass the debug flag to ruby.
-I, --include DIR
Passes this option directly to the selected target (see -t).
-r, --require LIBRARY
Passes this option directly to the selected target (see -t).
-n, --name RUBY_NAME
Overrides the name used to determine the Ruby implementation. RUBY_NAME defaults to require 'rbconfig'; Config::CONFIG["RUBY_INSTALL_NAME"] if this executes without exception.
-X, --tags-dir DIR
Overrides the directory prefix used to search for the tag files that can be associated with each spec file. The default directory is spec/tags in the current working directory.
-D, --gdb
Only useful with Rubinius. Passes the --gdb argument to shotgun to launch gdb.
-A, --valgrind
Only useful with Rubinius on a platform with Valgrind installed. Passes the --valgrind option to shotgun to run under Valgrind.
-w, --warnings
Don't suppress warnings from the target (see -t).
As a Ruby implementation is undergoing development, it is not likely to pass all the specs that have been written. However, when making changes to the code, a way is needed to confirm that working features are not inadvertently broken. Generally, some sort of continuous integration (CI) mechanism serves this purpose.
To meet this need, MSpec has a special runner that excludes the specs that are tagged as failing. The bin/mspec ci command accepts a file, directory, or shell glob to specify which spec files to execute. Invoking the command without any files will cause the default set of files specified by the configuration file to be run (See the configuration document). The default formatter for bin/mspec ci is dotted output (i.e. ... for passing specs, F for failing specs, and E for errors).
$ bin/mspec ci -h
ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0]
mspec ci [options] (FILE|DIRECTORY|GLOB)+
Ask yourself:
1. How to run the specs?
2. How to display the output?
3. What action to perform?
4. When to perform it?
How to run the specs
-B, --config FILE Load FILE containing configuration options
-n, --name RUBY_NAME Set the value of RUBY_NAME (used to determine the implementation)
-Z, --dry-run Invoke formatters and other actions, but don't execute the specs
--int-spec Control-C interupts the current spec only
How to display their output
-f, --format FORMAT Formatter for reporting, where FORMAT is one of:
s, spec, specdoc SpecdocFormatter
h, html, HtmlFormatter
d, dot, dotted DottedFormatter
f, file FileFormatter
u, unit, unitdiff UnitdiffFormatter
m, summary SummaryFormatter
a, *, spin SpinnerFormatter
t, method MethodFormatter
y, yaml YamlFormatter
-o, --output FILE Write formatter output to FILE
-V, --verbose Output the name of each file processed
-m, --marker MARKER Output MARKER for each file processed
What action to perform
--spec-debug Invoke the debugger when a spec description matches (see -K, -S)
--spec-gdb Invoke Gdb when a spec description matches (see -K, -S)
When to perform it
-K, --action-tag TAG Spec descriptions marked with TAG will trigger the specified action
-S, --action-string STR Spec descriptions matching STR will trigger the specified action
Help!
-v, --version Show version
-h, --help Show this message
How might this work in the real world?
1. To simply run the known good specs
$ mspec ci
2. To run a subset of the known good specs
$ mspec ci path/to/specs
3. To start the debugger before the spec matching 'this crashes'
$ mspec ci --spec-debug -S 'this crashes'
-f, --format FORMAT
Selects the reporter to be used for showing the output from executing the specs.
-V, --verbose
Prints to STDERR each spec file that is being executed.
-m, --marker MARKER
Output MARKER for each file processed. Overrides -V
Once the mspec options are processed, the designated target is executed with the remaining options. The general purpose spec runner, bin/mspec-run, accepts a file, directory, or shell glob to specify which spec files to execute. It has the following options:
$ bin/mspec run -h
ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0]
mspec run [options] (FILE|DIRECTORY|GLOB)+
Ask yourself:
1. What specs to run?
2. How to modify the execution?
3. How to display the output?
4. What action to perform?
5. When to perform it?
What specs to run
-e, --example STR Run examples with descriptions matching STR
-E, --exclude STR Exclude examples with descriptions matching STR
-p, --pattern PATTERN Run examples with descriptions matching PATTERN
-P, --excl-pattern PATTERN Exclude examples with descriptions matching PATTERN
-g, --tag TAG Run examples with descriptions matching ones tagged with TAG
-G, --excl-tag TAG Exclude examples with descriptions matching ones tagged with TAG
-w, --profile FILE Run examples for methods listed in the profile FILE
-W, --excl-profile FILE Exclude examples for methods listed in the profile FILE
How to modify the execution
-B, --config FILE Load FILE containing configuration options
-n, --name RUBY_NAME Set the value of RUBY_NAME (used to determine the implementation)
-H, --random Randomize the list of spec files
-Z, --dry-run Invoke formatters and other actions, but don't execute the specs
--int-spec Control-C interrupts the current spec only
How to display their output
-f, --format FORMAT Formatter for reporting, where FORMAT is one of:
s, spec, specdoc SpecdocFormatter
h, html, HtmlFormatter
d, dot, dotted DottedFormatter
f, file FileFormatter
u, unit, unitdiff UnitdiffFormatter
m, summary SummaryFormatter
a, *, spin SpinnerFormatter
t, method MethodFormatter
y, yaml YamlFormatter
-o, --output FILE Write formatter output to FILE
-V, --verbose Output the name of each file processed
-m, --marker MARKER Output MARKER for each file processed
What action to perform
--spec-debug Invoke the debugger when a spec description matches (see -K, -S)
--spec-gdb Invoke Gdb when a spec description matches (see -K, -S)
-Y, --verify Verify that guarded specs pass and fail as expected
-O, --report Report guarded specs
When to perform it
-K, --action-tag TAG Spec descriptions marked with TAG will trigger the specified action
-S, --action-string STR Spec descriptions matching STR will trigger the specified action
Help!
-v, --version Show version
-h, --help Show this message
How might this work in the real world?
1. To simply run some specs:
$ mspec path/to/the/specs
mspec path/to/the_file_spec.rb
2. To run specs tagged with 'fails':
$ mspec -g fails path/to/the_file_spec.rb
3. To start the debugger before the spec matching 'this crashes':
$ mspec --spec-debug -S 'this crashes' path/to/the_file_spec.rb
-f, --format FORMAT
Selects the reporter format to output specs strings and failures. The specdoc formatter is very similar to RSpec's -f s option. The dotted formatter outputs the familiar '....F..EF..'' with exceptions listed after all specs are run. The summary formatter only outputs the elapsed time and the tallies for files, examples, failures, and errors. The spinner formatter shows a progress bar. The YAML formatter is useful for automated processing.
-e, --example STRING|FILE-E, --exclude STRING|FILE
Does not execute any spec whose description string matches STRING.
-p, --pattern PATTERN
Executes only the specs whose description string matches the Regexp PATTERN. Specify the pattern without // characters. For example, to execute all specs whose description strings contain sorts or returns, use -p '(sorts|returns)'.
-P, --exclude-pattern PATTERN
Does not execute any spec whose description string matches the Regexp PATTERN.
-g, --tag TAG
Executes only the specs whose description string matches one tagged with TAG.
-G, --exclude-tag TAG
Does not execute any spec whose description string matches one tagged with TAG.
-V, --verbose
Outputs the name of each file processed.
-m, --marker MARKER
Outputs MARKER for each file processed. Overrides -V.
There is a separate script for adding and removing tags for spec descriptions. The f, e, E, p, P, g, G, V, m options are the same as for mspec-run above.
Note: The runners make a distinction between specifying filters for which specs will be executed (e.g. f, e, E, p, P, g, G) and which specs will trigger actions. The mspec-tag script registers the TagAction to add or delete tags based on the outcome of executing a spec (e.g. pass, fail, or all). The TagAction is different than, for example DebugAction, in that TagAction will match any spec by default. You can narrow the matches by using the K or S options. In this way, you can run a whole set of specs, but only tag a select few depending on what you pass with K or S.
For example, use the following command to tag any Array#append specs that fail with the tag 'fails'. Since --add fails is the default action and tag, the following commands are equivalent:
bin/mspec tag spec/ruby/1.8/core/array/append_spec.rb bin/mspec tag --add fails spec/ruby/1.8/core/array/append_spec.rb
To remove tags for specs that now pass, use the following command. Since --pass is the default outcome, the following commands are also equivalent:
bin/mspec tag --del fails spec/ruby/1.8/core/array/append_spec.rb bin/mspec tag --del fails --pass spec/ruby/1.8/core/array/append_spec.rb
Detailed help output is available for the command.
$ bin/mspec tag -h
ruby 1.8.6 (2008-03-03 patchlevel 114) [universal-darwin9.0]
mspec tag [options] (FILE|DIRECTORY|GLOB)+
Ask yourself:
1. What specs to run?
2. How to modify the execution?
3. How to display the output?
4. What tag action to perform?
5. When to perform it?
What specs to run
-e, --example STR Run examples with descriptions matching STR
-E, --exclude STR Exclude examples with descriptions matching STR
-p, --pattern PATTERN Run examples with descriptions matching PATTERN
-P, --excl-pattern PATTERN Exclude examples with descriptions matching PATTERN
-g, --tag TAG Run examples with descriptions matching ones tagged with TAG
-G, --excl-tag TAG Exclude examples with descriptions matching ones tagged with TAG
-w, --profile FILE Run examples for methods listed in the profile FILE
-W, --excl-profile FILE Exclude examples for methods listed in the profile FILE
How to modify the execution
-B, --config FILE Load FILE containing configuration options
-n, --name RUBY_NAME Set the value of RUBY_NAME (used to determine the implementation)
-Z, --dry-run Invoke formatters and other actions, but don't execute the specs
--int-spec Control-C interupts the current spec only
How to display their output
-f, --format FORMAT Formatter for reporting, where FORMAT is one of:
s, spec, specdoc SpecdocFormatter
h, html, HtmlFormatter
d, dot, dotted DottedFormatter
f, file FileFormatter
u, unit, unitdiff UnitdiffFormatter
m, summary SummaryFormatter
a, *, spin SpinnerFormatter
t, method MethodFormatter
y, yaml YamlFormatter
-o, --output FILE Write formatter output to FILE
-V, --verbose Output the name of each file processed
-m, --marker MARKER Output MARKER for each file processed
What action to perform and when to perform it
-N, --add TAG Add TAG with format 'tag' or 'tag(comment)' (see -Q, -F, -L)
-R, --del TAG Delete TAG (see -Q, -F, -L)
-Q, --pass Apply action to specs that pass (default for --del)
-F, --fail Apply action to specs that fail (default for --add)
-L, --all Apply action to all specs
--list TAG Display descriptions of any specs tagged with TAG
--list-all Display descriptions of any tagged specs
Help!
-v, --version Show version
-h, --help Show this message
How might this work in the real world?
1. To add the 'fails' tag to failing specs
$ mspec tag path/to/the_file_spec.rb
2. To remove the 'fails' tag from passing specs
$ mspec tag --del fails path/to/the_file_spec.rb
3. To display the descriptions for all specs tagged with 'fails'
$ mspec tag --list fails path/to/the/specs
-K, --action-tag TAG
Only consider specs tagged with TAG for adding or deleting a tag. If neither this option nor -S is given, consider any spec that is executed.
-S, --action-string STR
Only consider specs matching STR for adding or deleting a tag. If neither this option nor -K is given, consider any spec that is executed.
-N, --add TAG
Create a new tag named TAG. The format is 'tag' or 'tag(comment)', where comment is any collection of characters except these three ():.
-R, --del TAG
Delete the tag TAG.
-Q, --pass
Only tag or delete tags for specs that pass.
-F, --fail
Only tag or delete tags for specs that fail. This is the default option. So, if you don't pass any of Q, F, L only the failing specs will be tagged.
-L, --all
Tag or delete tags for specs regardless of whether the spec passes or fails.
--list TAG
Display the descriptions for all specs tagged with TAG. You can provide multiple tags with --list TAG1 --list TAG2
Note that this command is not merely listing the tag files. Only the tagged specs that would actually be run are displayed. For example, specs that are excluded by guards are not display. None of the specs are actually executed.
--list-all
Display the descriptions for specs with any tags.
MSpec has several special-purpose runners scripts for various tasks like running the specs, tagging specs, and running a particular subset of the specs that are known to pass on a particular implementation. The runner scripts essentially just collect your wishes, configure the moving parts of the MSpec module, hand over control to MSpec, and get out of the way. The links below describe each of the runner scripts in detail.
Since consistency is a boon to readability, MSpec provides a script to generate template spec files. See the documentation for mkspec.