rspec-core概览

加载测试用例

使用bundle exec rspec即可。在spec文件中加入pp caller，可得调用栈：

[".../2.7.2/lib/ruby/gems/2.7.0/gems/bootsnap-1.7.5/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:59:in `load'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/bootsnap-1.7.5/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:59:in `load'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/configuration.rb:2112:in `load_file_handling_errors'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/configuration.rb:1615:in `block in load_spec_files'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/configuration.rb:1613:in `each'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/configuration.rb:1613:in `load_spec_files'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/runner.rb:102:in `setup'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/runner.rb:86:in `run'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/runner.rb:71:in `run'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/runner.rb:45:in `invoke'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/exe/rspec:4:in `'",
 ".../2.7.2/bin/rspec:23:in `load'",
 ".../2.7.2/bin/rspec:23:in `'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli/exec.rb:63:in `load'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli/exec.rb:63:in `kernel_load'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli/exec.rb:28:in `run'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli.rb:476:in `exec'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/vendor/thor/lib/thor/command.rb:27:in `run'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/vendor/thor/lib/thor/invocation.rb:127:in `invoke_command'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/vendor/thor/lib/thor.rb:399:in `dispatch'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli.rb:30:in `dispatch'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/vendor/thor/lib/thor/base.rb:476:in `start'",
 ".../2.7.2/lib/ruby/2.7.0/bundler/cli.rb:24:in `start'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/bundler-2.1.4/libexec/bundle:46:in `block in '",
 ".../2.7.2/lib/ruby/2.7.0/bundler/friendly_errors.rb:123:in `with_friendly_errors'",
 ".../2.7.2/lib/ruby/gems/2.7.0/gems/bundler-2.1.4/libexec/bundle:34:in `'",
 ".../2.7.2/bin/bundle:23:in `load'",
 ".../2.7.2/bin/bundle:23:in `
'"]

源码如下，rspec会创建一个Runner对象，内含一个RSpec::Core::Configuration对象和RSpec::Core::ConfigurationOptions对象。如无意外，@options.configure(@configuration)会设置spec文件默认路径为项目的spec/目录，然后会用load方法加载它们

# lib/rspec/core/runner.rb
module RSpec
  module Core
    class Runner
      def self.invoke
        disable_autorun!
        status = run(ARGV, $stderr, $stdout).to_i
        exit(status) if status != 0
      end

      def self.run(args, err=$stderr, out=$stdout)
        trap_interrupt
        options = ConfigurationOptions.new(args)

        if options.options[:runner]
          options.options[:runner].call(options, err, out)
        else
          new(options).run(err, out)
        end
      end

      def initialize(options, configuration=RSpec.configuration, world=RSpec.world)
        @options       = options
        @configuration = configuration
        @world         = world
      end

      def run(err, out)
        setup(err, out)
        return @configuration.reporter.exit_early(exit_code) if RSpec.world.wants_to_quit

        run_specs(@world.ordered_example_groups).tap do
          persist_example_statuses
        end
      end

      def setup(err, out)
        configure(err, out)
        return if RSpec.world.wants_to_quit

        @configuration.load_spec_files
      ensure
        @world.announce_filters
      end

      def configure(err, out)
        @configuration.error_stream = err
        @configuration.output_stream = out if @configuration.output_stream == $stdout
        @options.configure(@configuration)
      end
    end
  end
end

简单来说，是这样的调用栈

exe/rspec
└─ RSpec::Core::Runner.invoke
    ├─ RSpec::Core::Runner#setup
    └─ RSpec::Core::Runner#run_specs

describe方法

检查describe方法的定义，可见它是这样的

[1] pry(main)> $ RSpec.describe

From: .../2.7.2/lib/ruby/gems/2.7.0/gems/rspec-core-3.10.1/lib/rspec/core/dsl.rb:42:
Owner: #
Visibility: public
Signature: describe(*args, &example_group_block)
Number of lines: 5

(class << RSpec; self; end).__send__(:define_method, name) do |*args, &example_group_block|
  group = RSpec::Core::ExampleGroup.__send__(name, *args, &example_group_block)
  RSpec.world.record(group)
  group
end

也就是这里：

# lib/rspec/core/dsl.rb
module RSpec
  module Core
    module DSL
      def self.expose_example_group_alias(name)
        return if example_group_aliases.include?(name)

        example_group_aliases << name

        (class << RSpec; self; end).__send__(:define_method, name) do |*args, &example_group_block|
          group = RSpec::Core::ExampleGroup.__send__(name, *args, &example_group_block)
          RSpec.world.record(group)
          group
        end

        expose_example_group_alias_globally(name) if exposed_globally?
      end
    end
  end
end

搜寻exposeexamplegroup_alias的用处，会发现这里

# lib/rspec/core/example_group.rb
module RSpec
  module Core
    class ExampleGroup
      def self.define_example_group_method(name, metadata={})
        idempotently_define_singleton_method(name) do |*args, &example_group_block|
          thread_data = RSpec::Support.thread_local_data
          top_level   = self == ExampleGroup

          registration_collection =
            if top_level
              # ...

              thread_data[:in_example_group] = true
              RSpec.world.example_groups
            else
              children
            end

          begin
            description = args.shift
            combined_metadata = metadata.dup
            combined_metadata.merge!(args.pop) if args.last.is_a? Hash
            args << combined_metadata

            subclass(self, description, args, registration_collection, &example_group_block)
          ensure
            thread_data.delete(:in_example_group) if top_level
          end
        end

        RSpec::Core::DSL.expose_example_group_alias(name)
      end

      define_example_group_method :example_group
      define_example_group_method :describe
      define_example_group_method :context
      define_example_group_method :xdescribe, :skip => "Temporarily skipped with xdescribe"
      define_example_group_method :xcontext,  :skip => "Temporarily skipped with xcontext"
      define_example_group_method :fdescribe, :focus => true
      define_example_group_method :fcontext,  :focus => true

      def self.subclass(parent, description, args, registration_collection, &example_group_block)
        subclass = Class.new(parent)
        subclass.set_it_up(description, args, registration_collection, &example_group_block)
        subclass.module_exec(&example_group_block) if example_group_block
        MemoizedHelpers.define_helpers_on(subclass)
        subclass
      end
    end
  end
end

这里的运作机制是：在rspec加载时，会加载lib/rspec/core/example_group.rb，这时会给ExampleGroup定义example_group、describe、context等单例方法，并且也给RSpec定义同样的单例方法，委派到ExampleGroup上

于是，当你调用RSpec.describe(..){..}时，实际上它会调用ExampleGroup.describe(..){..}创建一个ExampleGroup的子类，然后在其中执行你提供的block

新创建的ExampleGroup子类会被const_set到ExampleGroups上，常量名取自describe的第一个参数，如果describe 是递归调用，则const_set到父类上。如下：

module ExampleGroups
  extend Support::RecursiveConstMethods

  def self.assign_const(group)
    base_name   = base_name_for(group)
    const_scope = constant_scope_for(group)
    name        = disambiguate(base_name, const_scope)

    const_scope.const_set(name, group)
  end

  def self.constant_scope_for(group)
    const_scope = group.superclass
    const_scope = self if const_scope == ::RSpec::Core::ExampleGroup
    const_scope
  end
end

it方法

describe调用所带的block是在ExampleGroup子类上执行的，一般我们会在里面调用it(..){..}定义测试用例（当然，递归地调用describe、context等方法也是可以的），而it的定义也在lib/rspec/core/example_group.rb 里：

# lib/rspec/core/example_group.rb
def self.define_example_method(name, extra_options={})
  idempotently_define_singleton_method(name) do |*all_args, &block|
    desc, *args = *all_args

    options = Metadata.build_hash_from(args)
    options.update(:skip => RSpec::Core::Pending::NOT_YET_IMPLEMENTED) unless block
    options.update(extra_options)

    RSpec::Core::Example.new(self, desc, options, block)
  end
end

define_example_method :example
define_example_method :it
define_example_method :specify
define_example_method :focus,    :focus => true
define_example_method :fexample, :focus => true
define_example_method :fit,      :focus => true
define_example_method :fspecify, :focus => true
define_example_method :xexample, :skip => 'Temporarily skipped with xexample'
define_example_method :xit,      :skip => 'Temporarily skipped with xit'
define_example_method :xspecify, :skip => 'Temporarily skipped with xspecify'
define_example_method :skip,     :skip => true
define_example_method :pending,  :pending => true

it方法所做的就是创建一个Example实例，然后加入到当前ExampleGroup类的examples数组中

# lib/rspec/core/example.rb
def initialize(example_group_class, description, user_metadata, example_block=nil)
  # ...
  example_group_class.examples << self
  # ...
end

let方法

此外，在spec文件的describe和it之间，我们还会使用let定义“运行时生成并且在用例内缓存”的变量，其源码如下

# lib/rspec/core/example_group.rb
module RSpec
  module Core
    class ExampleGroup
      include MemoizedHelpers
      extend MemoizedHelpers::ClassMethods
    end
  end
end

# lib/rspec/core/memoized_helpers.rb
module RSpec
  module Core
    module MemoizedHelpers
      module ClassMethods
        def let(name, &block)
          # ...
          our_module = MemoizedHelpers.module_for(self)

          if our_module.instance_methods(false).include?(name)
            our_module.__send__(:remove_method, name)
          end
          our_module.__send__(:define_method, name, &block)

          if instance_methods(false).include?(name)
            remove_method(name)
          end

          if block.arity == 1
            define_method(name) { __memoized.fetch_or_store(name) { super(RSpec.current_example, &nil) } }
          else
            define_method(name) { __memoized.fetch_or_store(name) { super(&nil) } }
          end
        end
      end

      def self.module_for(example_group)
        get_constant_or_yield(example_group, :LetDefinitions) do
          mod = Module.new do
            include(Module.new {
              example_group.const_set(:NamedSubjectPreventSuper, self)
            })
          end

          example_group.const_set(:LetDefinitions, mod)
          mod
        end
      end

      def self.define_helpers_on(example_group)
         example_group.__send__(:include, module_for(example_group))
      end
    end
  end
end

此处代码有点绕：首先，let方法会生成一个名为:LetDefinitions的模块，并将该模块const_set到当前ExampleGroup中（如果未生成过）。然后在该模块上以let调用的参数定义实例方法，并在当前ExampleGroup上以let调用的参数定义实例方法，但内部是super调用父类。最后，再将模块include到当前ExampleGroup上（见define_helpers_on）。

如此一来，若在describe块中定义let(:abc){ 123 }，然后在it块中调用abc，因为it块是在ExampleGroup实例中执行，所以abc会被解析为ExampleGroup的实例方法，然后super到LetDefinitions 上。（在super外层会有缓存包装）

跳过测试

如果想在定义ExampleGroup时声明跳过，可以使用xdescribe、xcontext，想在定义Example时声明跳过，可以使用xit、xspecify，它们会在@metadata中注入:skip => 'Temporarily skipped with xxx'，

# lib/rspec/core/example_group.rb
def self.set_it_up(description, args, registration_collection, &example_group_block)
  # ...
  @user_metadata = Metadata.build_hash_from(args)

  @metadata = Metadata::ExampleGroupHash.create(
    superclass_metadata, @user_metadata,
    superclass.method(:next_runnable_index_for),
    description, *args, &example_group_block
  )
  # ...
  config.apply_derived_metadata_to(@metadata)
  # ...
  config.configure_group(self)
end

# lib/rspec/core/example.rb
def initialize(example_group_class, description, user_metadata, example_block=nil)
  # ...
  @metadata = Metadata::ExampleHash.create(
    @example_group_class.metadata, user_metadata,
    example_group_class.method(:next_runnable_index_for),
    description, example_block
  )
  # ...
end

然后在Example运行时，通过检查skipped?（读取@metadata）而跳过

# lib/rspec/core/example.rb
def run(example_group_instance, reporter)
  # ...

  begin
    if skipped?
      Pending.mark_pending! self, skip
    elsif !RSpec.configuration.dry_run?
      with_around_and_singleton_context_hooks do
        begin
          run_before_example
          @example_group_instance.instance_exec(self, &@example_block)

          if pending?
            Pending.mark_fixed! self

            raise Pending::PendingExampleFixedError,
                  'Expected example to fail since it is pending, but it passed.',
                  [location]
          end
        rescue Pending::SkipDeclaredInExample => _

        rescue AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt => e
          set_exception(e)
        ensure
          run_after_example
        end
      end
    end
  rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e
    set_exception(e)
  ensure
    @example_group_instance = nil # if you love something... let it go
  end

  # ...
end

此外，从上面代码也可发现，如果运行中抛出Pending::SkipDeclaredInExample，也是会使测试用例跳过的，在用例中我们可以使用skip方法触发，它所属的Pending模块被include到ExampleGroup上，因而在Example执行run时，@example_group_instance.instance_exec(self, &@example_block)可以访问到skip方法

# lib/rspec/core/pending.rb
module RSpec
  module Core
    module Pending
      def skip(message=nil)
        current_example = RSpec.current_example
        Pending.mark_skipped!(current_example, message) if current_example
        raise SkipDeclaredInExample.new(message)
      end
    end
  end
end

# lib/rspec/core/example_group.rb
module RSpec
  module Core
    class ExampleGroup
      include Pending
    end
  end
end

sharedexamples与includeexamples

shared_examples声明可复用的用例，将block注册到RSpec.world.shared_example_group_registry，而include_examples则是声明复用，从RSpec.world.shared_example_group_registry找出指定的block，然后在当前ExampleGroup上class_exec。源码如下

# lib/rspec/core/example_group.rb
def self.include_examples(name, *args, &block)
  find_and_eval_shared("examples", name, caller.first, *args, &block)
end

def self.find_and_eval_shared(label, name, inclusion_location, *args, &customization_block)
  shared_module = RSpec.world.shared_example_group_registry.find(parent_groups, name)
  unless shared_module
    raise ArgumentError, "Could not find shared #{label} #{name.inspect}"
  end
  shared_module.include_in(
    self, Metadata.relative_path(inclusion_location),
    args, customization_block
  )
end

# lib/rspec/core/shared_example_group.rb
module RSpec
  module Core
    class SharedExampleGroupModule < Module
      attr_reader :definition

      def initialize(description, definition, metadata)
        @description = description
        @definition  = definition
        @metadata    = metadata
      end

      def include_in(klass, inclusion_line, args, customization_block)
        klass.update_inherited_metadata(@metadata) unless @metadata.empty?

        SharedExampleGroupInclusionStackFrame.with_frame(@description, inclusion_line) do
          RSpec::Support::WithKeywordsWhenNeeded.class_exec(klass, *args, &@definition)
          klass.class_exec(&customization_block) if customization_block
        end
      end
    end

    module SharedExampleGroup
      module TopLevelDSL
        def self.definitions
          proc do
            def shared_examples(name, *args, &block)
              RSpec.world.shared_example_group_registry.add(:main, name, *args, &block)
            end
            alias shared_context      shared_examples
            alias shared_examples_for shared_examples
          end
        end
      end

      class Registry
        def add(context, name, *metadata_args, &block)
          # ...

          ensure_block_has_source_location(block) { CallerFilter.first_non_rspec_line }
          warn_if_key_taken context, name, block

          metadata = Metadata.build_hash_from(metadata_args)
          shared_module = SharedExampleGroupModule.new(name, block, metadata)
          shared_example_groups[context][name] = shared_module
        end

        def find(lookup_contexts, name)
          lookup_contexts.each do |context|
            found = shared_example_groups[context][name]
            return found if found
          end

          shared_example_groups[:main][name]
        end
      end
    end
  end

  instance_exec(&Core::SharedExampleGroup::TopLevelDSL.definitions)
end

hooks

在describe块中使用before、after、around可以注册回调，可以传参数:example（或:each）使回调在每个用例上运行，传:context（或:all）使回调在整个用例集上运行，其中around只可传于:example和:each。

运作时机如下，从中亦可见，如果before回调报错，则同一范围的后续before回调以及用例不会执行，但after回调还是会执行

# lib/rspec/core/runner.rb
def run_specs(example_groups)
  examples_count = @world.example_count(example_groups)
  examples_passed = @configuration.reporter.report(examples_count) do |reporter|
      # ...
      example_groups.map { |g| g.run(reporter) }.all?
    end
  end

  exit_code(examples_passed)
end


# lib/rspec/core/example_group.rb
def self.run(reporter=RSpec::Core::NullReporter)
  # ...

  begin
    run_before_context_hooks(new('before(:context) hook')) if should_run_context_hooks
    result_for_this_group = run_examples(reporter)
    # ...
  ensure
    run_after_context_hooks(new('after(:context) hook')) if should_run_context_hooks
  end
end

def self.run_examples(reporter)
  ordering_strategy.order(filtered_examples).map do |example|
    # ...
    succeeded = example.run(instance, reporter)
    # ...
  end.all?
end


# lib/rspec/core/example.rb
def run(example_group_instance, reporter)
  # ...
  with_around_and_singleton_context_hooks do
    begin
      run_before_example
      @example_group_instance.instance_exec(self, &@example_block)
      # ...
    ensure
      run_after_example
    end
  end
  # ...
end