RSpec::Core::MemoizedHelpers::ClassMethods

Creates a nested example group named by the submitted `attribute`, and then generates an example using the submitted block.

@example

# This ...
describe Array do
  its(:size) { should eq(0) }
end

# ... generates the same runtime structure as this:
describe Array do
  describe "size" do
    it "should eq(0)" do
      subject.size.should eq(0)
    end
  end
end

The attribute can be a `Symbol` or a `String`. Given a `String` with dots, the result is as though you concatenated that `String` onto the subject in an expression.

@example

describe Person do
  subject do
    Person.new.tap do |person|
      person.phone_numbers << "555-1212"
    end
  end

  its("phone_numbers.first") { should eq("555-1212") }
end

When the subject is a `Hash`, you can refer to the Hash keys by specifying a `Symbol` or `String` in an array.

@example

describe "a configuration Hash" do
  subject do
    { :max_users => 3,
      'admin' => :all_permissions }
  end

  its([:max_users]) { should eq(3) }
  its(['admin']) { should eq(:all_permissions) }

  # You can still access to its regular methods this way:
  its(:keys) { should include(:max_users) }
  its(:count) { should eq(2) }
end

Note that this method does not modify `subject` in any way, so if you refer to `subject` in `let` or `before` blocks, you're still referring to the outer subject.

@example

describe Person do
  subject { Person.new }
  before { subject.age = 25 }
  its(:age) { should eq(25) }
end

# File lib/rspec/core/memoized_helpers.rb, line 426
def its(attribute, &block)
  describe(attribute) do
    if Array === attribute
      let(:__its_subject) { subject[*attribute] }
    else
      let(:__its_subject) do
        attribute_chain = attribute.to_s.split('.')
        attribute_chain.inject(subject) do |inner_subject, attr|
          inner_subject.send(attr)
        end
      end
    end

    def should(matcher=nil, message=nil)
      RSpec::Expectations::PositiveExpectationHandler.handle_matcher(__its_subject, matcher, message)
    end

    def should_not(matcher=nil, message=nil)
      RSpec::Expectations::NegativeExpectationHandler.handle_matcher(__its_subject, matcher, message)
    end

    example(&block)
  end
end

Generates a method whose return value is memoized after the first call. Useful for reducing duplication between examples that assign values to the same local variable.

@note `let` can enhance readability when used sparingly (1,2, or

maybe 3 declarations) in any given example group, but that can
quickly degrade with overuse. YMMV.

@note `let` uses an `||=` conditional that has the potential to

behave in surprising ways in examples that spawn separate threads,
though we have yet to see this in practice. You've been warned.

@note Because `let` is designed to create state that is reset between

each example, and `before(:all)` is designed to setup state that is
shared across _all_ examples in an example group, `let` is _not_
intended to be used in a `before(:all)` hook. RSpec 2.13.1 prints
a warning when you reference a `let` from `before(:all)` and we plan
to have it raise an error in RSpec 3.

@example

describe Thing do
  let(:thing) { Thing.new }

  it "does something" do
    # first invocation, executes block, memoizes and returns result
    thing.do_something

    # second invocation, returns the memoized value
    thing.should be_something
  end
end

# File lib/rspec/core/memoized_helpers.rb, line 190
def let(name, &block)
  # We have to pass the block directly to `define_method` to
  # allow it to use method constructs like `super` and `return`.
  raise "#let or #subject called without a block" if block.nil?
  MemoizedHelpers.module_for(self).send(:define_method, name, &block)

  # Apply the memoization. The method has been defined in an ancestor
  # module so we can use `super` here to get the value.
  define_method(name) do
    __memoized.fetch(name) { |k| __memoized[k] = super(&nil) }
  end
end

Just like `let`, except the block is invoked by an implicit `before` hook. This serves a dual purpose of setting up state and providing a memoized reference to that state.

@example

class Thing
  def self.count
    @count ||= 0
  end

  def self.count=(val)
    @count += val
  end

  def self.reset_count
    @count = 0
  end

  def initialize
    self.class.count += 1
  end
end

describe Thing do
  after(:each) { Thing.reset_count }

  context "using let" do
    let(:thing) { Thing.new }

    it "is not invoked implicitly" do
      Thing.count.should eq(0)
    end

    it "can be invoked explicitly" do
      thing
      Thing.count.should eq(1)
    end
  end

  context "using let!" do
    let!(:thing) { Thing.new }

    it "is invoked implicitly" do
      Thing.count.should eq(1)
    end

    it "returns memoized version on first invocation" do
      thing
      Thing.count.should eq(1)
    end
  end
end

# File lib/rspec/core/memoized_helpers.rb, line 256
def let!(name, &block)
  let(name, &block)
  before { __send__(name) }
end

Declares a `subject` for an example group which can then be the implicit receiver (through delegation) of calls to `should`.

Given a `name`, defines a method with that name which returns the `subject`. This lets you declare the subject once and access it implicitly in one-liners and explicitly using an intention revealing name.

@param [String,Symbol] name used to define an accessor with an

intention revealing name

@param block defines the value to be returned by `subject` in examples

@example

describe CheckingAccount, "with $50" do
  subject { CheckingAccount.new(Money.new(50, :USD)) }
  it { should have_a_balance_of(Money.new(50, :USD)) }
  it { should_not be_overdrawn }
end

describe CheckingAccount, "with a non-zero starting balance" do
  subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }
  it { should_not be_overdrawn }
  it "has a balance equal to the starting balance" do
    account.balance.should eq(Money.new(50, :USD))
  end
end

@see MemoizedHelpers#should

# File lib/rspec/core/memoized_helpers.rb, line 290
def subject(name=nil, &block)
  if name
    let(name, &block)
    alias_method :subject, name

    self::NamedSubjectPreventSuper.send(:define_method, name) do
      raise NotImplementedError, "`super` in named subjects is not supported"
    end
  else
    let(:subject, &block)
  end
end

Just like `subject`, except the block is invoked by an implicit `before` hook. This serves a dual purpose of setting up state and providing a memoized reference to that state.

@example

class Thing
  def self.count
    @count ||= 0
  end

  def self.count=(val)
    @count += val
  end

  def self.reset_count
    @count = 0
  end

  def initialize
    self.class.count += 1
  end
end

describe Thing do
  after(:each) { Thing.reset_count }

  context "using subject" do
    subject { Thing.new }

    it "is not invoked implicitly" do
      Thing.count.should eq(0)
    end

    it "can be invoked explicitly" do
      subject
      Thing.count.should eq(1)
    end
  end

  context "using subject!" do
    subject!(:thing) { Thing.new }

    it "is invoked implicitly" do
      Thing.count.should eq(1)
    end

    it "returns memoized version on first invocation" do
      subject
      Thing.count.should eq(1)
    end
  end
end

# File lib/rspec/core/memoized_helpers.rb, line 356
def subject!(name=nil, &block)
  subject(name, &block)
  before { subject }
end