vendor/plugins/rspec/lib/spec/runner/option_parser.rb

   1 require 'optparse'
   2 require 'stringio'
   3
   4 module Spec
   5   module Runner
   6     class OptionParser
   7       BUILT_IN_FORMATTERS = {
   8         'specdoc'  => Formatter::SpecdocFormatter,
   9         's'        => Formatter::SpecdocFormatter,
  10         'html'     => Formatter::HtmlFormatter,
  11         'h'        => Formatter::HtmlFormatter,
  12         'rdoc'     => Formatter::RdocFormatter,
  13         'r'        => Formatter::RdocFormatter,
  14         'progress' => Formatter::ProgressBarFormatter,
  15         'p'        => Formatter::ProgressBarFormatter,
  16         'failing_examples' => Formatter::FailingExamplesFormatter,
  17         'e'        => Formatter::FailingExamplesFormatter,
  18         'failing_behaviours' => Formatter::FailingBehavioursFormatter,
  19         'b'        => Formatter::FailingBehavioursFormatter
  20       }
  21
  22       COMMAND_LINE = {
  23         :diff =>    ["-D", "--diff [FORMAT]", "Show diff of objects that are expected to be equal when they are not",
  24                                              "Builtin formats: unified|u|context|c",
  25                                              "You can also specify a custom differ class",
  26                                              "(in which case you should also specify --require)"],
  27         :colour =>  ["-c", "--colour", "--color", "Show coloured (red/green) output"],
  28         :example => ["-e", "--example [NAME|FILE_NAME]",  "Execute example(s) with matching name(s). If the argument is",
  29                                                           "the path to an existing file (typically generated by a previous",
  30                                                           "run using --format failing_examples:file.txt), then the examples",
  31                                                           "on each line of thatfile will be executed. If the file is empty,",
  32                                                           "all examples will be run (as if --example was not specified).",
  33                                                           " ",
  34                                                           "If the argument is not an existing file, then it is treated as",
  35                                                           "an example name directly, causing RSpec to run just the example",
  36                                                           "matching that name"],
  37         :specification => ["-s", "--specification [NAME]", "DEPRECATED - use -e instead", "(This will be removed when autotest works with -e)"],
  38         :line => ["-l", "--line LINE_NUMBER", Integer, "Execute behaviout or specification at given line.",
  39                                                        "(does not work for dynamically generated specs)"],
  40         :format => ["-f", "--format FORMAT[:WHERE]",  "Specifies what format to use for output. Specify WHERE to tell",
  41                                                     "the formatter where to write the output. All built-in formats",
  42                                                     "expect WHERE to be a file name, and will write to STDOUT if it's",
  43                                                     "not specified. The --format option may be specified several times",
  44                                                     "if you want several outputs",
  45                                                     " ",
  46                                                     "Builtin formats: ",
  47                                                     "progress|p           : Text progress",
  48                                                     "specdoc|s            : Behaviour doc as text",
  49                                                     "rdoc|r               : Behaviour doc as RDoc",
  50                                                     "html|h               : A nice HTML report",
  51                                                     "failing_examples|e   : Write all failing examples - input for --example",
  52                                                     "failing_behaviours|b : Write all failing behaviours - input for --example",
  53                                                     " ",
  54                                                     "FORMAT can also be the name of a custom formatter class",
  55                                                     "(in which case you should also specify --require to load it)"],
  56         :require => ["-r", "--require FILE", "Require FILE before running specs",
  57                                           "Useful for loading custom formatters or other extensions.",
  58                                           "If this option is used it must come before the others"],
  59         :backtrace => ["-b", "--backtrace", "Output full backtrace"],
  60         :loadby => ["-L", "--loadby STRATEGY", "Specify the strategy by which spec files should be loaded.",
  61                                               "STRATEGY can currently only be 'mtime' (File modification time)",
  62                                               "By default, spec files are loaded in alphabetical order if --loadby",
  63                                               "is not specified."],
  64         :reverse => ["-R", "--reverse", "Run examples in reverse order"],
  65         :timeout => ["-t", "--timeout FLOAT", "Interrupt and fail each example that doesn't complete in the",
  66                                               "specified time"],
  67         :heckle => ["-H", "--heckle CODE", "If all examples pass, this will mutate the classes and methods",
  68                                            "identified by CODE little by little and run all the examples again",
  69                                            "for each mutation. The intent is that for each mutation, at least",
  70                                            "one example *should* fail, and RSpec will tell you if this is not the",
  71                                            "case. CODE should be either Some::Module, Some::Class or",
  72                                            "Some::Fabulous#method}"],
  73         :dry_run => ["-d", "--dry-run", "Invokes formatters without executing the examples."],
  74         :options_file => ["-O", "--options PATH", "Read options from a file"],
  75         :generate_options => ["-G", "--generate-options PATH", "Generate an options file for --options"],
  76         :runner => ["-U", "--runner RUNNER", "Use a custom BehaviourRunner."],
  77         :drb => ["-X", "--drb", "Run examples via DRb. (For example against script/spec_server)"],
  78         :version => ["-v", "--version", "Show version"],
  79         :help => ["-h", "--help", "You're looking at it"]
  80       }
  81
  82       def initialize
  83         @spec_parser = SpecParser.new
  84         @file_factory = File
  85       end
  86
  87       def create_behaviour_runner(args, err, out, warn_if_no_files)
  88         options = parse(args, err, out, warn_if_no_files)
  89         # Some exit points in parse (--generate-options, --drb) don't return the options,
  90         # but hand over control. In that case we don't want to continue.
  91         return nil unless options.is_a?(Options)
  92         options.create_behaviour_runner
  93       end
  94
  95       def parse(args, err, out, warn_if_no_files)
  96         options_file = nil
  97         args_copy = args.dup
  98         options = Options.new
  99
 100         opts = ::OptionParser.new do |opts|
 101           opts.banner = "Usage: spec (FILE|DIRECTORY|GLOB)+ [options]"
 102           opts.separator ""
 103
 104           def opts.rspec_on(name, &block)
 105             on(*COMMAND_LINE[name], &block)
 106           end
 107
 108           opts.rspec_on(:diff) {|diff| options.parse_diff(diff, out, err)}
 109
 110           opts.rspec_on(:colour) {options.colour = true}
 111
 112           opts.rspec_on(:example) {|example| options.parse_example(example)}
 113
 114           opts.rspec_on(:specification) {|example| options.parse_example(example)}
 115
 116           opts.rspec_on(:line) {|line_number| options.line_number = line_number.to_i}
 117
 118           opts.rspec_on(:format) {|format| options.parse_format(format, out, err)}
 119
 120           opts.rspec_on(:require) {|req| options.parse_require(req)}
 121
 122           opts.rspec_on(:backtrace) {options.backtrace_tweaker = NoisyBacktraceTweaker.new}
 123
 124           opts.rspec_on(:loadby) {|loadby| options.loadby = loadby}
 125
 126           opts.rspec_on(:reverse) {options.reverse = true}
 127
 128           opts.rspec_on(:timeout) {|timeout| options.timeout = timeout.to_f}
 129
 130           opts.rspec_on(:heckle) {|heckle| options.parse_heckle(heckle)}
 131
 132           opts.rspec_on(:dry_run) {options.dry_run = true}
 133
 134           opts.rspec_on(:options_file) do |options_file|
 135             return parse_options_file(options_file, out, err, args_copy, warn_if_no_files)
 136           end
 137
 138           opts.rspec_on(:generate_options) do |options_file|
 139             options.parse_generate_options(options_file, args_copy, out)
 140           end
 141
 142           opts.rspec_on(:runner) do |runner|
 143             options.parse_runner(runner, out, err)
 144           end
 145
 146           opts.rspec_on(:drb) do
 147             return parse_drb(args_copy, out, err, warn_if_no_files)
 148           end
 149
 150           opts.rspec_on(:version) {parse_version(out)}
 151
 152           opts.on_tail(*COMMAND_LINE[:help]) {parse_help(opts, out)}
 153         end
 154         opts.parse!(args)
 155
 156         if args.empty? && warn_if_no_files
 157           err.puts "No files specified."
 158           err.puts opts
 159           exit(6) if err == $stderr
 160         end
 161
 162         if options.line_number
 163           set_spec_from_line_number(options, args, err)
 164         end
 165
 166         if options.formatters.empty?
 167           options.formatters << Formatter::ProgressBarFormatter.new(out)
 168         end
 169
 170         options
 171       end
 172
 173       def parse_options_file(options_file, out_stream, error_stream, args_copy, warn_if_no_files)
 174         # Remove the --options option and the argument before writing to file
 175         index = args_copy.index("-O") || args_copy.index("--options")
 176         args_copy.delete_at(index)
 177         args_copy.delete_at(index)
 178
 179         new_args = args_copy + IO.readlines(options_file).map {|l| l.chomp.split " "}.flatten
 180         return CommandLine.run(new_args, error_stream, out_stream, true, warn_if_no_files)
 181       end
 182
 183       def parse_drb(args_copy, out_stream, error_stream, warn_if_no_files)
 184         # Remove the --drb option
 185         index = args_copy.index("-X") || args_copy.index("--drb")
 186         args_copy.delete_at(index)
 187
 188         return DrbCommandLine.run(args_copy, error_stream, out_stream, true, warn_if_no_files)
 189       end
 190
 191       def parse_version(out_stream)
 192         out_stream.puts ::Spec::VERSION::DESCRIPTION
 193         exit if out_stream == $stdout
 194       end
 195
 196       def parse_help(opts, out_stream)
 197         out_stream.puts opts
 198         exit if out_stream == $stdout
 199       end
 200
 201       def set_spec_from_line_number(options, args, err)
 202         if options.examples.empty?
 203           if args.length == 1
 204             if @file_factory.file?(args[0])
 205               source = @file_factory.open(args[0])
 206               example = @spec_parser.spec_name_for(source, options.line_number)
 207               options.parse_example(example)
 208             elsif @file_factory.directory?(args[0])
 209               err.puts "You must specify one file, not a directory when using the --line option"
 210               exit(1) if err == $stderr
 211             else
 212               err.puts "#{args[0]} does not exist"
 213               exit(2) if err == $stderr
 214             end
 215           else
 216             err.puts "Only one file can be specified when using the --line option: #{args.inspect}"
 217             exit(3) if err == $stderr
 218           end
 219         else
 220           err.puts "You cannot use both --line and --example"
 221           exit(4) if err == $stderr
 222         end
 223       end
 224     end
 225   end
 226 end