Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

rdoc

  • Loading branch information...
commit 84cb5f2ec47a1acfab4adaf56d312c046863ae2f 1 parent f33faed
@dchelimsky dchelimsky authored
View
2  lib/rspec/core.rb
@@ -70,7 +70,7 @@ def self.reset
configuration.reset
end
- # Returns the global [Configuration](Core/Configuration) object. While you
+ # Returns the global [Configuration](RSpec/Core/Configuration) object. While you
# _can_ use this method to access the configuration, the more common
# convention is to use [RSpec.configure](RSpec#configure-class_method).
#
View
136 lib/rspec/core/configuration.rb
@@ -7,7 +7,9 @@ module Core
#
# @example Standard settings
# RSpec.configure do |c|
- # c.drb_port = 1234
+ # c.drb = true
+ # c.drb_port = 1234
+ # c.default_path = 'behavior'
# end
#
# @example Hooks
@@ -72,25 +74,99 @@ def self.add_setting(name, opts={})
end
end
- add_setting :error_stream
- add_setting :output_stream, :alias_with => [:output, :out]
+ # @macro [attach] add_setting
+ # @attribute $1
+ # Patterns to match against lines in backtraces presented in failure
+ # messages in order to filter them out (default:
+ # DEFAULT_BACKTRACE_PATTERNS). You can either replace this list using
+ # the setter or modify it using the getter.
+ #
+ # To override this behavior and display a full backtrace, use
+ # `--backtrace` on the command line, in a `.rspec` file, or in the
+ # `rspec_options` attribute of RSpec's rake task.
+ add_setting :backtrace_clean_patterns
+
+ # Path to use if no path is provided to the `rspec` command (default:
+ # `"spec"`). Allows you to just type `rspec` instead of `rspec spec` to
+ # run all the examples in the `spec` directory.
+ add_setting :default_path
+
+ # Run examples over DRb (default: `false`). RSpec doesn't supply the DRb
+ # server, but you can use tools like spork.
add_setting :drb
+
+ # The drb_port (default: `8989`).
add_setting :drb_port
- add_setting :profile_examples
+
+ # Default: `$stderr`.
+ add_setting :error_stream
+
+ # Clean up and exit after the first failure (default: `false`).
add_setting :fail_fast
+
+ # The exit code to return if there are any failures (default: 1).
add_setting :failure_exit_code
- add_setting :run_all_when_everything_filtered
+
+ # Determines the order in which examples are run (default: OS standard
+ # load order for files, declaration order for groups and examples).
+ add_setting :order
+
+ # Default: `$stdout`.
+ # Also known as `output` and `out`
+ add_setting :output_stream, :alias_with => [:output, :out]
+
+ # Load files matching this pattern (default: `'**/*_spec.rb'`)
add_setting :pattern, :alias_with => :filename_pattern
- add_setting :files_to_run
- add_setting :include_or_extend_modules
- add_setting :backtrace_clean_patterns
- add_setting :tty
+
+ # Report the times for the 10 slowest examples (default: `false`).
+ add_setting :profile_examples
+
+ # Run all examples if none match the configured filters (default: `false`).
+ add_setting :run_all_when_everything_filtered
+
+ # Seed for random ordering (default: generated randomly each run).
+ #
+ # When you run specs with `--order random`, RSpec generates a random seed
+ # for the randomization and prints it to the `output_stream` (assuming
+ # you're using RSpec's built-in formatters). If you discover an ordering
+ # dependency (i.e. examples fail intermittently depending on order), set
+ # this (on Configuration or on the command line with `--seed`) to run
+ # using the same seed while you debug the issue.
+ #
+ # We recommend, actually, that you use the command line approach so you
+ # don't accidentally leave the seed encoded.
+ add_setting :seed
+
+ # When a block passed to pending fails (as expected), display the failure
+ # without reporting it as a failure (default: false).
+ add_setting :show_failures_in_pending_blocks
+
+ # Convert symbols to hashes with the symbol as a key with a value of
+ # `true` (default: false).
+ #
+ # This allows you to tag a group or example like this:
+ #
+ # describe "something slow", :slow do
+ # # ...
+ # end
+ #
+ # ... instead of having to type:
+ #
+ # describe "something slow", :slow => true do
+ # # ...
+ # end
add_setting :treat_symbols_as_metadata_keys_with_true_values
+
+ # @private
+ add_setting :tty
+ # @private
+ add_setting :include_or_extend_modules
+ # @private
+ add_setting :files_to_run
+ # @private
add_setting :expecting_with_rspec
- add_setting :default_path
- add_setting :show_failures_in_pending_blocks
- add_setting :order
- add_setting :seed
+ # @private
+ attr_accessor :filter_manager
DEFAULT_BACKTRACE_PATTERNS = [
/\/lib\d*\/ruby\//,
@@ -117,8 +193,6 @@ def initialize
@seed = srand % 0xFFFF
end
- attr_accessor :filter_manager
-
# @private
#
# Used to set higher priority option values from the command line.
@@ -147,7 +221,20 @@ def reset
end
# @overload add_setting(name)
- # @overload add_setting(name, options_hash)
+ # @overload add_setting(name, opts)
+ # @option opts [Symbol] :default
+ #
+ # set a default value for the generated getter and predicate methods:
+ #
+ # add_setting(:foo, :default => "default value")
+ #
+ # @option opts [Symbol] :alias_with
+ #
+ # Use `:alias_with` to alias the setter, getter, and predicate to another
+ # name, or names:
+ #
+ # add_setting(:foo, :alias_with => :bar)
+ # add_setting(:foo, :alias_with => [:bar, :baz])
#
# Adds a custom setting to the RSpec.configuration object.
#
@@ -168,23 +255,6 @@ def reset
# RSpec.configuration.foo=(value)
# RSpec.configuration.foo
# RSpec.configuration.foo? # returns true if foo returns anything but nil or false
- #
- # ### Options
- #
- # `add_setting` takes an optional hash that supports the keys `:default`
- # and `:alias_with`.
- #
- # Use `:default` to set a default value for the generated getter and
- # predicate methods:
- #
- # add_setting(:foo, :default => "default value")
- #
- # Use `:alias_with` to alias the setter, getter, and predicate to another
- # name, or names:
- #
- # add_setting(:foo, :alias_with => :bar)
- # add_setting(:foo, :alias_with => [:bar, :baz])
- #
def add_setting(name, opts={})
default = opts.delete(:default)
(class << self; self; end).class_eval do
View
36 lib/rspec/core/example_group.rb
@@ -23,12 +23,12 @@ class ExampleGroup
include Pending
include Let
- # @api private
+ # @private
def self.world
RSpec.world
end
- # @api private
+ # @private
def self.register
world.register(self)
end
@@ -45,10 +45,11 @@ def self.delegate_to_metadata(*names)
delegate_to_metadata :description, :described_class, :file_path
alias_method :display_name, :description
+ # @private
alias_method :describes, :described_class
end
- # @api private
+ # @private
def self.define_example_method(name, extra_options={})
module_eval(<<-END_RUBY, __FILE__, __LINE__)
def self.#{name}(desc=nil, *args, &block)
@@ -78,7 +79,7 @@ class << self
alias_example_to :focused, :focused => true, :focus => true
alias_example_to :focus, :focused => true, :focus => true
- # @api private
+ # @private
def self.define_nested_shared_group_method(new_name, report_label=nil)
module_eval(<<-END_RUBY, __FILE__, __LINE__)
def self.#{new_name}(name, *args, &customization_block)
@@ -127,12 +128,12 @@ def self.find_and_eval_shared(label, name, *args, &customization_block)
module_eval(&customization_block) if customization_block
end
- # The collection of examples in the group.
+ # @private
def self.examples
@examples ||= []
end
- # @api private
+ # @private
def self.filtered_examples
world.filtered_examples[self]
end
@@ -142,6 +143,7 @@ def self.descendant_filtered_examples
@descendant_filtered_examples ||= filtered_examples + children.inject([]){|l,c| l + c.descendant_filtered_examples}
end
+ # The [Metadata](Metadata) object associated with this group.
# @see Metadata
def self.metadata
@metadata if defined?(@metadata)
@@ -267,7 +269,7 @@ def self.assign_before_all_ivars(ivars, example_group_instance)
ivars.each { |ivar, val| example_group_instance.instance_variable_set(ivar, val) }
end
- # @api private
+ # @private
def self.run_before_all_hooks(example_group_instance)
return if descendant_filtered_examples.empty?
assign_before_all_ivars(superclass.before_all_ivars, example_group_instance)
@@ -276,7 +278,7 @@ def self.run_before_all_hooks(example_group_instance)
store_before_all_ivars(example_group_instance)
end
- # @api private
+ # @private
def self.run_around_each_hooks(example, initial_procsy)
example.around_hooks.reverse.inject(initial_procsy) do |procsy, around_hook|
Example.procsy(procsy.metadata) do
@@ -285,19 +287,19 @@ def self.run_around_each_hooks(example, initial_procsy)
end
end
- # @api private
+ # @private
def self.run_before_each_hooks(example)
world.run_hook_filtered(:before, :each, self, example.example_group_instance, example)
ancestors.reverse.each { |ancestor| ancestor.run_hook(:before, :each, example.example_group_instance) }
end
- # @api private
+ # @private
def self.run_after_each_hooks(example)
ancestors.each { |ancestor| ancestor.run_hook(:after, :each, example.example_group_instance) }
world.run_hook_filtered(:after, :each, self, example.example_group_instance, example)
end
- # @api private
+ # @private
def self.run_after_all_hooks(example_group_instance)
return if descendant_filtered_examples.empty?
assign_before_all_ivars(before_all_ivars, example_group_instance)
@@ -318,7 +320,7 @@ def self.run_after_all_hooks(example_group_instance)
world.run_hook_filtered(:after, :all, self, example_group_instance)
end
- # @api private
+ # @private
def self.around_hooks_for(example)
world.find_hook(:around, :each, self, example) + ancestors.reverse.inject([]){|l,a| l + a.find_hook(:around, :each, self, example)}
end
@@ -345,7 +347,7 @@ def self.run(reporter)
end
end
- # @api private
+ # @private
def self.run_examples(reporter)
filtered_examples.ordered.map do |example|
next if RSpec.wants_to_quit
@@ -357,7 +359,7 @@ def self.run_examples(reporter)
end.all?
end
- # @api private
+ # @private
def self.fail_filtered_examples(exception, reporter)
filtered_examples.each { |example| example.fail_with_exception(reporter, exception) }
@@ -369,17 +371,17 @@ def self.fail_filtered_examples(exception, reporter)
false
end
- # @api private
+ # @private
def self.fail_fast?
RSpec.configuration.fail_fast?
end
- # @api private
+ # @private
def self.any_apply?(filters)
metadata.any_apply?(filters)
end
- # @api private
+ # @private
def self.all_apply?(filters)
metadata.all_apply?(filters)
end
View
59 lib/rspec/core/hooks.rb
@@ -87,7 +87,7 @@ def run_all!(example_group_instance)
class AroundHooks < HookCollection; end
- # @api private
+ # @private
def hooks
@hooks ||= {
:around => { :each => AroundHooks.new },
@@ -241,8 +241,8 @@ def hooks
# before(:all) do
# File.open(file_to_parse, 'w') do |f|
# f.write <<-CONTENT
- # Stuff in the file
- # end
+ # stuff in the file
+ # CONTENT
# end
# end
#
@@ -262,10 +262,15 @@ def before(*args, &block)
# @api public
# @overload after(&block)
# @overload after(scope, &block)
- # @overload after(scope, tags, &block)
- # @overload after(tags, &block)
+ # @overload after(scope, conditions, &block)
+ # @overload after(conditions, &block)
+ #
# @param [Symbol] scope `:each`, `:all`, or `:suite` (defaults to `:each`)
- # @param [Hash] tags
+ # @param [Hash] conditions
+ # constrains this hook to examples matching these conditions e.g.
+ # `after(:each, :ui => true) { ... }` will only run with examples or
+ # groups declared with `:ui => true`.
+ #
# @see #before
# @see #around
# @see ExampleGroup
@@ -292,12 +297,12 @@ def before(*args, &block)
# 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
+ # 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,
@@ -310,12 +315,28 @@ def after(*args, &block)
# @api public
# @overload around(&block)
# @overload around(scope, &block)
- # @overload around(scope, tags, &block)
- # @overload around(tags, &block)
+ # @overload around(scope, conditions, &block)
+ # @overload around(conditions, &block)
+ #
# @param [Symbol] scope `:each` (defaults to `:each`)
- # @param [Hash] tags
+ # present for syntax parity with `before` and `after`, but `:each` is
+ # the only supported value.
+ #
+ # @param [Hash] conditions
+ # constrains this hook to examples matching these conditions e.g.
+ # `around(:each, :ui => true) { ... }` will only run with examples or
+ # groups declared with `:ui => true`.
+ #
# @yield [Example] the example to run
#
+ # @note the syntax of `around` is similar to that of `before` and `after`
+ # but the semantics are quite different. `before` and `after` hooks are
+ # run in the context of of the examples with which they are associated,
+ # whereas `around` hooks are actually responsible for running the
+ # examples. Consequently, `around` hooks do not have direct access to
+ # resources that are made available within the examples and their
+ # associated `before` and `after` hooks.
+ #
# @note `:each` is the only supported scope.
#
# Declare a block of code, parts of which will be run before and parts
@@ -340,26 +361,26 @@ def around(*args, &block)
hooks[:around][scope] << AroundHook.new(options, &block)
end
- # @api private
+ # @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
+ # @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
+ # @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
+ # @private
def find_hook(hook, scope, example_group_class, example = nil)
found_hooks = hooks[hook][scope].find_hooks_for(example || example_group_class)
View
3  spec/rspec/core/command_line_spec.rb
@@ -22,19 +22,16 @@ def config_options(argv=[])
end
it "returns 0 if spec passes" do
- err, out = StringIO.new, StringIO.new
result = command_line([passing_spec_filename]).run(err, out)
result.should be(0)
end
it "returns 1 if spec fails" do
- err, out = StringIO.new, StringIO.new
result = command_line([failing_spec_filename]).run(err, out)
result.should be(1)
end
it "returns 2 if spec fails and --failure-exit-code is 2" do
- err, out = StringIO.new, StringIO.new
result = command_line([failing_spec_filename, "--failure-exit-code", "2"]).run(err, out)
result.should be(2)
end
Please sign in to comment.
Something went wrong with that request. Please try again.