Module RSpec::Core::MemoizedHelpers::ClassMethods
In: lib/rspec/core/memoized_helpers.rb

Methods

its   let   let!   should   should_not   subject   subject!  

Public Instance methods

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

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.

@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

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

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

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

[Validate]