class RuboCop::Cop::RSpec::NamedSubject

Checks for explicitly referenced test subjects.

RSpec lets you declare an “implicit subject” using ‘subject { … }` which allows for tests like `it { is_expected.to be_valid }`. If you need to reference your test subject you should explicitly name it using `subject(:your_subject_name) { … }`. Your test subjects should be the most important object in your tests so they deserve a descriptive name.

This cop can be configured in your configuration using ‘EnforcedStyle`, and `IgnoreSharedExamples` which will not report offenses for implicit subjects in shared example groups.

@example ‘EnforcedStyle: always` (default)

# bad
RSpec.describe User do
  subject { described_class.new }

  it 'is valid' do
    expect(subject.valid?).to be(true)
  end
end

# good
RSpec.describe User do
  subject(:user) { described_class.new }

  it 'is valid' do
    expect(user.valid?).to be(true)
  end
end

# also good
RSpec.describe User do
  subject(:user) { described_class.new }

  it { is_expected.to be_valid }
end

@example ‘EnforcedStyle: named_only`

# bad
RSpec.describe User do
  subject(:user) { described_class.new }

  it 'is valid' do
    expect(subject.valid?).to be(true)
  end
end

# good
RSpec.describe User do
  subject(:user) { described_class.new }

  it 'is valid' do
    expect(user.valid?).to be(true)
  end
end

# also good
RSpec.describe User do
  subject { described_class.new }

  it { is_expected.to be_valid }
end

# acceptable
RSpec.describe User do
  subject { described_class.new }

  it 'is valid' do
    expect(subject.valid?).to be(true)
  end
end

Constants

MSG

Public Instance Methods

on_block(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 97
def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
  if !example_or_hook_block?(node) || ignored_shared_example?(node)
    return
  end

  subject_usage(node) do |subject_node|
    check_explicit_subject(subject_node)
  end
end

Private Instance Methods

allow_explicit_subject?(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 123
def allow_explicit_subject?(node)
  !always? && !named_only?(node)
end
always?() click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 127
def always?
  style == :always
end
check_explicit_subject(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 117
def check_explicit_subject(node)
  return if allow_explicit_subject?(node)

  add_offense(node.loc.selector)
end
find_subject(block_node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 150
def find_subject(block_node)
  block_node.body&.child_nodes&.find { |send_node| subject?(send_node) }
end
ignored_shared_example?(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 109
def ignored_shared_example?(node)
  return false unless cop_config['IgnoreSharedExamples']

  node.each_ancestor(:block).any? do |ancestor|
    shared_example?(ancestor)
  end
end
named_only?(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 131
def named_only?(node)
  style == :named_only &&
    subject_definition_is_named?(node)
end
nearest_subject(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 142
def nearest_subject(node)
  node
    .each_ancestor(:block)
    .lazy
    .map { |block_node| find_subject(block_node) }
    .find(&:itself)
end
subject_definition_is_named?(node) click to toggle source
# File lib/rubocop/cop/rspec/named_subject.rb, line 136
def subject_definition_is_named?(node)
  subject = nearest_subject(node)

  subject&.send_node&.arguments?
end