RSpec::Core::Subject::ExampleMethods

When should is called with no explicit receiver, the call is delegated to the object returned by subject. Combined with an implicit subject (see subject), this supports very concise expressions.

@example

describe Person do
  it { should be_eligible_to_vote }
end

# File lib/rspec/core/subject.rb, line 68
def should(matcher=nil, message=nil)
  RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
end

Just like should, should_not delegates to the subject (implicit or explicit) of the example group.

@example

describe Person do
  it { should_not be_eligible_to_vote }
end

# File lib/rspec/core/subject.rb, line 80
def should_not(matcher=nil, message=nil)
  RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
end

Returns the subject defined by the example group. The subject block is only executed once per example, the result of which is cached and returned by any subsequent calls to `subject`.

If a class is passed to `describe` and no subject is explicitly declared in the example group, then `subject` will return a new instance of that class.

@note `subject` was contributed by Joe Ferris to support the one-liner

syntax embraced by shoulda matchers:

    describe Widget do
      it { should validate_presence_of(:name) }
    end

While the examples below demonstrate how to use `subject`
explicitly in specs, we think it works best for extensions like
shoulda, custom matchers, and shared example groups, where it is
not referenced explicitly in specs.

@example

# explicit declaration of subject
describe Person do
  subject { Person.new(:birthdate => 19.years.ago) }
  it "should be eligible to vote" do
    subject.should be_eligible_to_vote
  end
end

# implicit subject => { Person.new }
describe Person do
  it "should be eligible to vote" do
    subject.should be_eligible_to_vote
  end
end

describe Person do
  # one liner syntax - should is invoked on subject
  it { should be_eligible_to_vote }
end

# File lib/rspec/core/subject.rb, line 47
def subject
  if defined?(@original_subject)
    @original_subject
  else
    @original_subject = instance_eval(&self.class.subject)
  end
end