Configuration

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 by looking in ‘.’ and ‘spec’ directories:

default.mspec
depending on RUBY_VERSION, either ruby.1.8.mspec or ruby.1.9.mspec
~/.mspecrc

Config 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/ruby/core',
    'spec/ruby/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.

Configuration Options

There are a variety of config options. These are listed below with their function and default values.

Loading configuration files

: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

Invoking the runner scripts

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.

Selecting the tag set

: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.)

Selecting the set of specs to run by filters

: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.

Selecting the set of specs to run by explicit lists of files

: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:

a simple file name
a directory name, in which case the directory is recursively searched for spec files (i.e. dir/*/_spec.rb)
a glob pattern understood by 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.

Formatting runner results

: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.

Tagging specs

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.

Triggering actions

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.