rspec-core 2.7.1 → 2.8.0.rc1

data/lib/rspec/core/formatters/base_formatter.rb

@@ -95,6 +95,9 @@ module RSpec
         def dump_pending
         end
 
+        def seed(number)
+        end
+
         # This method is invoked at the very end. Allows the formatter to clean up, like closing open streams.
         def close
           restore_sync_output
@@ -142,7 +145,6 @@ module RSpec
             match = line.match(/(.+?):(\d+)(|:\d+)/)
             match && match[1].downcase == path.downcase
           }
-
         end
 
         def start_sync_output

data/lib/rspec/core/formatters/base_text_formatter.rb

@@ -86,6 +86,12 @@ module RSpec
           end
         end
 
+        def seed(number)
+          output.puts
+          output.puts "Randomized with seed #{number}"
+          output.puts
+        end
+
         def close
           output.close if IO === output && output != $stdout
         end

data/lib/rspec/core/formatters/snippet_extractor.rb

@@ -8,7 +8,7 @@ module RSpec
         begin
           require 'syntax/convertors/html'
           @@converter = Syntax::Convertors::HTML.for_syntax "ruby"
-        rescue LoadError => e
+        rescue LoadError
           @@converter = NullConverter.new
         end
 

data/lib/rspec/core/hooks.rb

@@ -77,7 +77,7 @@ module RSpec
 
       class AfterHooks < HookCollection
         def run_all(example_group_instance)
-          reverse.each {|h| h.run_in(example_group_instance) } 
+          reverse.each {|h| h.run_in(example_group_instance) }
         end
 
         def run_all!(example_group_instance)
@@ -87,6 +87,7 @@ module RSpec
 
       class AroundHooks < HookCollection; end
 
+      # @api private
       def hooks
         @hooks ||= {
           :around => { :each => AroundHooks.new },
@@ -95,37 +96,232 @@ module RSpec
         }
       end
 
+      # @api public
+      # @overload before(&block)
+      # @overload before(scope, &block)
+      # @overload before(scope, tags, &block)
+      # @overload before(tags, &block)
+      # @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
+      # @param [Hash] tags
+      # @see #after
+      # @see #around
+      # @see ExampleGroup
+      # @see SharedContext
+      # @see SharedExampleGroup
+      # @see Configuration
+      #
+      # Declare a block of code to be run before each example (using `:each`)
+      # or once before any example (using `:all`). These are usually declared
+      # directly in the [ExampleGroup](ExampleGroup) to which they apply, but
+      # they can also be shared across multiple groups.
+      #
+      # You can also use `before(:suite)` to run a block of code before any
+      # example groups are run. This should be declared in
+      # [RSpec.configure](../../RSpec#configure-class_method)
+      #
+      # Instance variables declared in `before(:each)` or `before(:all)` are
+      # accessible within each example.
+      #
+      # ### Exceptions
+      #
+      # When an exception is raised in a `before` block, RSpec skips any
+      # subsequent `before` blocks and the example, but runs all of the
+      # `after(:each)` and `after(:all)` hooks.
+      #
+      # ### Order
+      #
+      # `before` hooks are stored in three scopes, which are run in order:
+      # `:suite`, `:all`, and `:each`. They can also be declared in several
+      # different places: `RSpec.configure`, a parent group, the current group.
+      # They are run in the following order:
+      #
+      #     before(:all) declared in RSpec.configure
+      #     before(:all) declared in a parent group
+      #     before(:all) declared in the current group
+      #     before(:each) declared in RSpec.configure
+      #     before(:each) declared in a parent group
+      #     before(:each) declared in the current group
+      #
+      # If more than one `before` is declared within any one scope, they are run
+      # in the order in which they are declared.
+      #
+      # ### Warning: implicit before blocks
+      #
+      # `before` hooks can also be declared in shared contexts which get
+      # included implicitly either by you or by extension libraries. Since
+      # RSpec runs these in the order in which they are declared within each
+      # scope, load order matters, and can lead to confusing results when one
+      # before block depends on state that is prepared in another before block
+      # that gets run later.
+      #
+      # ### Warning: `before(:all)`
+      #
+      # It is very tempting to use `before(:all)` to speed things up, but we
+      # recommend that you avoid this as there are a number of gotchas, as well
+      # as things that simply don't work.
+      #
+      # #### context
+      #
+      # `before(:all)` is run in an example that is generated to provide group
+      # context for the block.
+      #
+      # #### instance variables
+      #
+      # Instance variables declared in `before(:all)` are shared across all the
+      # examples in the group.  This means that each example can change the
+      # state of a shared object, resulting in an ordering dependency that can
+      # make it difficult to reason about failures.
+      #
+      # ### other frameworks
+      #
+      # Mock object frameworks and database transaction managers (like
+      # ActiveRecord) are typically designed around the idea of setting up
+      # before an example, running that one example, and then tearing down.
+      # This means that mocks and stubs can (sometimes) be declared in
+      # `before(:all)`, but get torn down before the first real example is ever
+      # run.
+      #
+      # You _can_ create database-backed model objects in a `before(:all)` in
+      # rspec-rails, but it will not be wrapped in a transaction for you, so
+      # you are on your own to clean up in an `after(:all)` block.
+      #
+      # @example before(:each) declared in an [ExampleGroup](ExampleGroup)
+      #
+      #     describe Thing do
+      #       before(:each) do
+      #         @thing = Thing.new
+      #       end
+      #
+      #       it "does something" do
+      #         # here you can access @thing
+      #       end
+      #     end
+      #
+      # @example before(:all) declared in an [ExampleGroup](ExampleGroup)
+      #
+      #     describe Parser do
+      #       before(:all) do
+      #         File.open(file_to_parse, 'w') do |f|
+      #           f.write <<-CONTENT
+      #             Stuff in the file
+      #           end
+      #         end
+      #       end
+      #
+      #       it "parses the file" do
+      #         Parser.parse(file_to_parse)
+      #       end
+      #
+      #       after(:all) do
+      #         File.delete(file_to_parse)
+      #       end
+      #     end
       def before(*args, &block)
         scope, options = scope_and_options_from(*args)
         hooks[:before][scope] << BeforeHook.new(options, &block)
       end
 
+      # @api public
+      # @overload after(&block)
+      # @overload after(scope, &block)
+      # @overload after(scope, tags, &block)
+      # @overload after(tags, &block)
+      # @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
+      # @param [Hash] tags
+      # @see #before
+      # @see #around
+      # @see ExampleGroup
+      # @see SharedContext
+      # @see SharedExampleGroup
+      # @see Configuration
+      #
+      # Declare a block of code to be run after each example (using `:each`) or
+      # once after all examples (using `:all`). See
+      # [#before](Hooks#before-instance_method) for more information about
+      # ordering.
+      #
+      # ### Exceptions
+      #
+      # `after` hooks are guaranteed to run even when there are exceptions in
+      # `before` hooks or examples.  When an exception is raised in an after
+      # block, the exception is captured for later reporting, and subsequent
+      # `after` blocks are run.
+      #
+      # ### Order
+      #
+      # `after` hooks are stored in three scopes, which are run in order:
+      # `:each`, `:all`, and `:suite`. They can also be declared in several
+      # different places: `RSpec.configure`, a parent group, the current group.
+      # They are run in the following order:
+      #
+      #     after(:each) declared in the current group
+      #     after(:each) declared in a parent group
+      #     after(:each) declared in RSpec.configure
+      #     after(:all) declared in the current group
+      #     after(:all) declared in a parent group
+      #     after(:all) declared in RSpec.configure
+      #
+      # This is the reverse of the order in which `before` hooks are run.
+      # Similarly, if more than one `after` is declared within any one scope,
+      # they are run in reverse order of that in which they are declared.
       def after(*args, &block)
         scope, options = scope_and_options_from(*args)
         hooks[:after][scope] << AfterHook.new(options, &block)
       end
 
+      # @api public
+      # @overload around(&block)
+      # @overload around(scope, &block)
+      # @overload around(scope, tags, &block)
+      # @overload around(tags, &block)
+      # @param [Symbol] scope `:each` (defaults to `:each`)
+      # @param [Hash] tags
+      # @yield [Example] the example to run
+      #
+      # @note `:each` is the only supported scope.
+      #
+      # Declare a block of code, parts of which will be run before and parts
+      # after the example. It is your responsibility to run the example:
+      #
+      #     around(:each) do |ex|
+      #       # do some stuff before
+      #       ex.run
+      #       # do some stuff after
+      #     end
+      #
+      # The yielded example aliases `run` with `call`, which lets you treat it
+      # like a `Proc`.  This is especially handy when working with libaries
+      # that manage their own setup and teardown using a block or proc syntax,
+      # e.g.
+      #
+      #     around(:each) {|ex| Database.transaction(&ex)}
+      #     around(:each) {|ex| FakeFS(&ex)}
+      #
       def around(*args, &block)
         scope, options = scope_and_options_from(*args)
         hooks[:around][scope] << AroundHook.new(options, &block)
       end
 
+      # @api private
       # Runs all of the blocks stored with the hook in the context of the
       # example. If no example is provided, just calls the hook directly.
       def run_hook(hook, scope, example_group_instance=nil)
         hooks[hook][scope].run_all(example_group_instance)
       end
 
+      # @api private
       # Just like run_hook, except it removes the blocks as it evalutes them,
       # ensuring that they will only be run once.
       def run_hook!(hook, scope, example_group_instance)
         hooks[hook][scope].run_all!(example_group_instance)
       end
 
+      # @api private
       def run_hook_filtered(hook, scope, group, example_group_instance, example = nil)
         find_hook(hook, scope, group, example).run_all(example_group_instance)
       end
 
+      # @api private
       def find_hook(hook, scope, example_group_class, example = nil)
         found_hooks = hooks[hook][scope].find_hooks_for(example || example_group_class)
 

data/lib/rspec/core/let.rb

@@ -6,7 +6,7 @@ module RSpec
         # Generates a method whose return value is memoized
         # after the first call.
         #
-        # == Examples
+        # @example
         #
         #  describe Thing do
         #    let(:thing) { Thing.new }
@@ -30,7 +30,7 @@ module RSpec
         # purpose of setting up state and providing a memoized
         # reference to that state.
         #
-        # == Examples
+        # @example
         #
         #  class Thing
         #    def self.count
@@ -86,6 +86,7 @@ module RSpec
       end
 
       module InstanceMethods
+        private
         def __memoized
           @__memoized ||= {}
         end

data/lib/rspec/core/metadata.rb

@@ -1,10 +1,16 @@
 module RSpec
   module Core
+    # Each ExampleGroup class and Example instance ...
+    #
+    # @see Example#metadata
+    # @see ExampleGroup.metadata
     class Metadata < Hash
 
-      # Used to extend metadata Hashes to support lazy evaluation of locations
-      # and descriptions.
       module MetadataHash
+
+        # Supports lazy evaluation of some values. Extended by
+        # ExampleMetadataHash and GroupMetadataHash, which get mixed in to
+        # Metadata for ExampleGroups and Examples (respectively).
         def [](key)
           return super if has_key?(key)
           case key
@@ -58,9 +64,19 @@ module RSpec
         end
       end
 
+      # Mixed in to Metadata for an Example (extends MetadataHash) to support
+      # lazy evaluation of some values.
+      module ExampleMetadataHash
+        include MetadataHash
+      end
+
+      # Mixed in to Metadata for an ExampleGroup (extends MetadataHash) to
+      # support lazy evaluation of some values.
       module GroupMetadataHash
         include MetadataHash
 
+        private
+
         def described_class_for(*)
           ancestors.each do |g|
             return g[:describes] if g.has_key?(:describes)
@@ -76,7 +92,7 @@ module RSpec
 
         def full_description_for(*)
           build_description_from(*ancestors.reverse.map do |a|
-            a.has_key?(:full_description) ? a[:full_description] : a[:description_args]
+            a[:description_args]
           end.flatten)
         end
 
@@ -105,6 +121,7 @@ module RSpec
         yield self if block_given?
       end
 
+      # @api private
       def process(*args)
         user_metadata = args.last.is_a?(Hash) ? args.pop : {}
         ensure_valid_keys(user_metadata)
@@ -115,18 +132,22 @@ module RSpec
         update(user_metadata)
       end
 
+      # @api private
       def for_example(description, user_metadata)
-        dup.extend(MetadataHash).configure_for_example(description, user_metadata)
+        dup.extend(ExampleMetadataHash).configure_for_example(description, user_metadata)
       end
 
+      # @api private
       def any_apply?(filters)
         filters.any? {|k,v| filter_applies?(k,v)}
       end
 
+      # @api private
       def all_apply?(filters)
         filters.all? {|k,v| filter_applies?(k,v)}
       end
 
+      # @api private
       def filter_applies?(key, value, metadata=self)
         case value
         when Hash

data/lib/rspec/core/option_parser.rb

@@ -28,22 +28,62 @@ module RSpec::Core
       OptionParser.new do |parser|
         parser.banner = "Usage: rspec [options] [files or directories]\n\n"
 
-        parser.on('-b', '--backtrace', 'Enable full backtrace') do |o|
-          options[:full_backtrace] = true
+        parser.on('-I DIRECTORY', 'specify $LOAD_PATH directory (may be used more than once)') do |dir|
+          options[:libs] ||= []
+          options[:libs] << dir
         end
 
-        parser.on('-c', '--[no-]color', '--[no-]colour', 'Enable color in the output') do |o|
-          options[:color_enabled] = o
+        parser.on('-r', '--require PATH', 'Require a file') do |path|
+          options[:requires] ||= []
+          options[:requires] << path
+        end
+
+        parser.on('-O', '--options PATH', 'Specify the path to a custom options file') do |path|
+          options[:custom_options_file] = path
+        end
+
+        parser.on('--order TYPE', 'Run examples by the specified order type',
+                  '  [rand] randomized',
+                  '  [random] alias for rand',
+                  '  [random:SEED] e.g. --order random:123') do |o|
+          options[:order] = o
+        end
+
+        parser.on('--seed SEED', "Equivalent of --order rand:SEED") do |seed|
+          options[:order] = "rand:#{seed}"
         end
 
         parser.on('-d', '--debugger', 'Enable debugging') do |o|
           options[:debug] = true
         end
 
-        parser.on('-e', '--example STRING', "Run examples whose full nested names include STRING") do |o|
-          options[:full_description] = Regexp.compile(Regexp.escape(o))
+        parser.on('--fail-fast', 'Abort the run on first failure') do |o|
+          options[:fail_fast] = true
+        end
+
+        parser.on('--failure-exit-code CODE', 'Override the exit code used when there are failing specs') do |o|
+          options[:failure_exit_code] = o.to_i
         end
 
+        parser.on('-X', '--[no-]drb', 'Run examples via DRb') do |o|
+          options[:drb] = o
+        end
+
+        parser.on('--drb-port [PORT]', 'Port to connect to on the DRb server') do |o|
+          options[:drb_port] = o.to_i
+        end
+
+        parser.on('--configure COMMAND', 'Generate configuration files') do |cmd|
+          CommandLineConfiguration.new(cmd).run
+          exit
+        end
+
+        parser.on("--tty", "Used internally by rspec when sending commands to other processes") do |o|
+          options[:tty] = true
+        end
+
+        parser.separator("\n  **** Output formatting ****\n\n")
+
         parser.on('-f', '--format FORMATTER', 'Choose a formatter',
                 '  [p]rogress (default - dots)',
                 '  [d]ocumentation (group and example names)',
@@ -63,84 +103,79 @@ module RSpec::Core
           options[:formatters].last << o
         end
 
-        parser.on_tail('-h', '--help', "You're looking at it.") do
-          puts parser
-          exit
-        end
-
-        parser.on('-I DIRECTORY', 'specify $LOAD_PATH directory (may be used more than once)') do |dir|
-          options[:libs] ||= []
-          options[:libs] << dir
-        end
-
-        parser.on('-l', '--line_number LINE', 'Specify the line number of an example to run.  May be specified multiple times.') do |o|
-          (options[:line_numbers] ||= []) << o
+        parser.on('-b', '--backtrace', 'Enable full backtrace') do |o|
+          options[:full_backtrace] = true
         end
 
-        parser.on('-O', '--options PATH', 'Specify the path to an options file') do |path|
-          options[:custom_options_file] = path
+        parser.on('-c', '--[no-]color', '--[no-]colour', 'Enable color in the output') do |o|
+          options[:color] = o
         end
 
         parser.on('-p', '--profile', 'Enable profiling of examples with output of the top 10 slowest examples') do |o|
           options[:profile_examples] = o
         end
 
-        parser.on('-P', '--pattern PATTERN', 'Load files matching this pattern. Default is "spec/**/*_spec.rb"') do |o|
-          options[:pattern] = o
-        end
+        parser.separator <<-FILTERING
 
-        parser.on('-r', '--require PATH', 'Require a file') do |path|
-          options[:requires] ||= []
-          options[:requires] << path
-        end
+  **** Filtering and tags ****
 
-        parser.on('-v', '--version', 'Show version') do
-          puts RSpec::Core::Version::STRING
-          exit
-        end
+    In addition to the following options for selecting specific files, groups,
+    or examples, you can select a single example by appending the line number to
+    the filename:
 
-        parser.on('-X', '--[no-]drb', 'Run examples via DRb') do |o|
-          options[:drb] = o
-        end
+      rspec path/to/a_spec.rb:37
 
-        parser.on('--configure COMMAND', 'Generate configuration files') do |cmd|
-          CommandLineConfiguration.new(cmd).run
-          exit
-        end
+FILTERING
 
-        parser.on('--drb-port [PORT]', 'Port to connect to on the DRb server') do |o|
-          options[:drb_port] = o.to_i
+        parser.on('-P', '--pattern PATTERN', 'Load files matching pattern (default: "spec/**/*_spec.rb")') do |o|
+          options[:pattern] = o
         end
 
-        parser.on('--fail-fast', 'Abort the run on first failure.') do |o|
-          options[:fail_fast] = true
+        parser.on('-e', '--example STRING', "Run examples whose full nested names include STRING") do |o|
+          options[:full_description] = Regexp.compile(Regexp.escape(o))
         end
 
-        parser.on('--failure-exit-code CODE', 'Override the exit code used when there are failing specs.') do |o|
-          options[:failure_exit_code] = o.to_i
+        parser.on('-l', '--line_number LINE', 'Specify line number of an example or group (may be specified multiple times)') do |o|
+          (options[:line_numbers] ||= []) << o
         end
 
-        parser.on('-t', '--tag TAG[:VALUE]', 'Run examples with the specified tag',
-                'To exclude examples, add ~ before the tag (e.g. ~slow)',
-                '(TAG is always converted to a symbol)') do |tag|
-          filter_type = tag =~ /^~/ ? :exclusion_filter : :filter
+        parser.on('-t', '--tag TAG[:VALUE]',
+                  'Run examples with the specified tag, or exclude',
+                  'examples by ading ~ before the tag (e.g. ~slow)',
+                  '(TAG is always converted to a symbol)') do |tag|
+          filter_type = tag =~ /^~/ ? :exclusion_filter : :inclusion_filter
 
           name,value = tag.gsub(/^(~@|~|@)/, '').split(':')
           name = name.to_sym
-          value = true if value.nil?
 
           options[filter_type] ||= {}
-          options[filter_type][name] = value
-        end
-
-        parser.on('--tty', 'Used internally by rspec when sending commands to other processes') do |o|
-          options[:tty] = true
+          options[filter_type][name] = case value
+                                       when /^(true|false|nil)$/
+                                         eval(value)
+                                       when nil
+                                         true
+                                       else
+                                         value
+                                       end
         end
 
         parser.on('--default_path PATH', 'Set the default path where RSpec looks for examples.',
                                          'Can be a path to a file or a directory') do |path|
           options[:default_path] = path
         end
+
+        parser.separator("\n  **** Utility ****\n\n")
+
+        parser.on('-v', '--version', 'Show version') do
+          puts RSpec::Core::Version::STRING
+          exit
+        end
+
+        parser.on_tail('-h', '--help', "You're looking at it.") do
+          puts parser
+          exit
+        end
+
       end
     end
   end