RSpec Style Guide

https://rspec.rubystyle.guide
Admin
RSpec Style Guide is a comprehensive guide outlining recommended best practices and conventions for...
Tokens:11,295
Snippets:140
Trust Score:7.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Short Example Descriptions

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Emphasizes keeping example descriptions concise (under 60 characters) and self-documenting. Demonstrates rewriting verbose descriptions.

```ruby
# bad
it 'rewrites "should not return something" as "does not return something"' do
  # ...
end

# good
it 'rewrites "should not return something"' do
  expect(rewrite('should not return something')).to
    eq 'does not return something'
end

# good - self-documenting
specify do
  expect(rewrite('should not return something')).to
    eq 'does not return something'
end
```

--------------------------------

### Example Description Structure

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Shows how to refactor example descriptions by wrapping conditional logic in a 'context' block for better organization and to encourage negative test cases.

```ruby
# bad
it 'returns the display name if it is present' do
  # ...
end

# good
context 'when display name is present' do
  it 'returns the display name' do
    # ...
  end
end

# This encourages the addition of negative test cases that might have
# been overlooked
context 'when display name is not present' do
  it 'returns nil' do
    # ...
  end
end
```

--------------------------------

### Install Rouge Gem for Syntax Highlighting

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Command to install the 'rouge' gem, which provides syntax highlighting for generated documents.

```shell
gem install rouge
```

--------------------------------

### Use `it` and `specify` Appropriately in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use `specify` for examples without descriptions and `it` for examples with descriptions. `it` is preferred for one-line examples. `specify` can also improve readability when the docstring doesn't flow well with `it`.

```ruby
# bad
it do
  # ...
end

specify 'it sends an email' do
  # ...
end

specify { is_expected.to be_truthy }

it '#do_something is deprecated' do
  ...
end

# good
specify do
  # ...
end

it 'sends an email' do
  # ...
end

it { is_expected.to be_truthy }

specify '#do_something is deprecated' do
  ...
end
```

--------------------------------

### RSpec: Multiple Expectations with Aggregated Failures

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use the `:aggregate_failures` tag for examples with multiple expectations to group failures. This can reduce setup overhead compared to separate examples for each expectation.

```ruby
# good - multiple expectations with aggregated failures
describe ArticlesController do
  #...

  describe 'GET new', :aggregate_failures do
    it 'assigns new article and renders the new article template' do
      get :new
      expect(assigns[:article]).to be_a(Article)
      expect(response).to render_template :new
    end
  end

  # ...
end
```

--------------------------------

### Generate PDF and HTML Documentation

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Commands to generate PDF and HTML versions of the RSpec style guide using AsciiDoctor.

```shell
# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc

# Generates README.html
asciidoctor README.adoc
```

--------------------------------

### RSpec: One Expectation Per Example

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Write individual examples for each expectation to improve clarity. This approach clearly isolates test failures, though it may involve repeated context initialization.

```ruby
# good - one expectation per example
describe ArticlesController do
  #...

  describe 'GET new' do
    it 'assigns a new article' do
      get :new
      expect(assigns[:article]).to be_a(Article)
    end

    it 'renders the new article template' do
      get :new
      expect(response).to render_template :new
    end
  end
end
```

--------------------------------

### Change Matcher Example

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Demonstrates the use of the 'change' matcher to assert that a block of code modifies a value.

```ruby
it 'changes something to a new value' do
  expect { do_something }.to change(something).to(new_value)
end
```

--------------------------------

### Use `it_behaves_like` for Resource List Testing

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Leverage `it_behaves_like` to include shared examples for common resource behaviors like listability, pagination, search, and filtering.

```ruby
describe 'GET /devices' do
  let(:resource) { FactoryBot.create(:device, created_from: user) }

  it_behaves_like 'a listable resource'
  it_behaves_like 'a paginable resource'
  it_behaves_like 'a searchable resource'
  it_behaves_like 'a filterable list'
end
```

--------------------------------

### Stub HTTP Requests with WebMock

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use WebMock to stub HTTP requests and avoid hitting real external services. This example stubs a GET request to an API endpoint.

```ruby
context 'with unauthorized access' do
  let(:uri) { 'http://api.lelylan.com/types' }

  before { stub_request(:get, uri).to_return(status: 401, body: fixture('401.json')) }

  it 'returns access denied' do
    page.driver.get uri
    expect(page).to have_content 'Access denied'
  end
end
```

--------------------------------

### Use Verifying Instance Doubles

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Prefer instance_double for creating doubles that verify method signatures. This example stubs the 'author' method on an 'Article' double.

```ruby
article = instance_double('Article')
allow(article).to receive(:author).and_return(nil)

presenter = described_class.new(article)
expect(presenter.title).to include('by an unknown author')
```

--------------------------------

### Avoid 'Should' in Example Descriptions

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Instructs to avoid using 'should' or 'should not' at the beginning of example descriptions. Use the third-person present tense to describe actual functionality.

```ruby
# bad
it 'should return the summary' do
  # ...
end

# good
it 'returns the summary' do
  # ...
end
```

--------------------------------

### Limit Data Loading in Tests

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Only load the necessary data for your tests. This example limits the number of users created to 2.

```ruby
RSpec.describe User do
  describe ".top" do
    subject { described_class.top(2) }

    before { FactoryBot.create_list(:user, 3) }

    it { is_expected.to have(2).items }
  end
end
```

--------------------------------

### Handle Time with Timecop

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use the Timecop gem to manage time in tests instead of stubbing Time.now. This example freezes time and asserts an expectation based on it.

```ruby
describe InvoiceReminder do
  subject(:time_with_offset) { described_class.new.get_offset_time }

  # bad
  it 'offsets the time 2 days into the future' do
    current_time = Time.now
    allow(Time).to receive(:now).and_return(current_time)
    expect(time_with_offset).to eq(current_time + 2.days)
  end

  # good
  it 'offsets the time 2 days into the future' do
    Timecop.freeze(Time.now) do
      expect(time_with_offset).to eq 2.days.from_now
    end
  end
end
```

--------------------------------

### Avoid Redundant `before(:each)` Scope in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Omit the explicit `:each` or `:example` scope for `before` and `after` blocks as it's the default. Use `:example` only when explicit clarity is needed.

```ruby
# bad
describe '#summary' do
  before(:example) do
    # ...
  end

  # ...
end

# good
describe '#summary' do
  before do
    # ...
  end

  # ...
end
```

--------------------------------

### Using `let` for Reusable Data in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Utilize `let` and `let!` for data shared across multiple examples within a group. `let!` is useful for defining variables even when not all examples reference them, such as when testing negative cases.

```ruby
# bad
it 'finds shortest path' do
  tree = Tree.new(1 => 2, 2 => 3, 2 => 6, 3 => 4, 4 => 5, 5 => 6)
  expect(dijkstra.shortest_path(tree, from: 1, to: 6)).to eq([1, 2, 6])
end

it 'finds longest path' do
  tree = Tree.new(1 => 2, 2 => 3, 2 => 6, 3 => 4, 4 => 5, 5 => 6)
  expect(dijkstra.longest_path(tree, from: 1, to: 6)).to eq([1, 2, 3, 4, 5, 6])
end

# good
let(:tree) { Tree.new(1 => 2, 2 => 3, 2 => 6, 3 => 4, 4 => 5, 5 => 6) }

it 'finds shortest path' do
  expect(dijkstra.shortest_path(tree, from: 1, to: 6)).to eq([1, 2, 6])
end

it 'finds longest path' do
  expect(dijkstra.longest_path(tree, from: 1, to: 6)).to eq([1, 2, 3, 4, 5, 6])
end
```

--------------------------------

### Empty Lines Around RSpec Examples

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Illustrates the recommended practice of using one empty line around 'it'/'specify' blocks in RSpec to separate expectations from conditional logic.

```ruby
# bad
describe '#summary' do
  let(:item) { double('something') }

  it 'returns the summary' do
    # ...
  end
  it 'does something else' do
    # ...
  end
  it 'does another thing' do
    # ...
  end
end
```

--------------------------------

### Use Verifying Partial Doubles

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use partial doubles to stub specific methods on existing objects or classes. This example stubs the 'find' method on the 'Article' class.

```ruby
allow(Article).to receive(:find).with(5).and_return(article)
```

--------------------------------

### Use Shared Examples for DRY RSpec Tests

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Refactor repetitive test logic into shared examples to avoid duplication. This improves maintainability by centralizing test behavior.

```ruby
describe 'GET /articles' do
  let(:article) { FactoryBot.create(:article, owner: owner) }

  before { page.driver.get '/articles' }

  shared_examples 'shows articles' do
    it 'shows all related articles' do
      expect(page.status_code).to be(200)
      contains_resource resource
    end
  end

  context 'when user is the owner' do
    let(:user) { owner }

    include_examples 'shows articles'
  end

  context 'when user is an admin' do
    let(:user) { FactoryBot.create(:user, :admin) }

    include_examples 'shows articles'
  end
end
```

--------------------------------

### Stub Constants with stub_const

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use stub_const to stub constants within a specific example group. This prevents constants from leaking into other examples.

```ruby
# bad
describe SomeClass do
  CONSTANT_HERE = 'I leak into global namespace'
end

# good
describe SomeClass do
  before do
    stub_const('CONSTANT_HERE', 'I only exist during this example')
  end
end
```

--------------------------------

### Context Description Naming Convention

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Illustrates the difference between bad and good context description naming in RSpec. Good descriptions form readable sentences when combined with example descriptions.

```ruby
# bad - 'Summary user logged in no display name shows a placeholder'
describe 'Summary' do
 context 'user logged in' do
   context 'no display name' do
     it 'shows a placeholder' do
     end
   end
end
end

# good - 'Summary when the user is logged in when the display name is blank shows a placeholder'
describe 'Summary' do
 context 'when the user is logged in' do
   context 'when the display name is blank' do
     it 'shows a placeholder' do
     end
   end
 end
end
```

--------------------------------

### Use Verifying Object Doubles

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use object_double for creating doubles that mimic real objects. This example creates a double for an 'Article' object and verifies its 'valid?' method.

```ruby
article = object_double(Article.new, valid?: true)
expect(article.save).to be true
```

--------------------------------

### Model spec using FactoryBot for a persisted article

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This model spec uses FactoryBot to create a real Article object and checks if it's an instance of Article and if it's persisted in the database. This is a basic setup for model testing.

```ruby
describe Article do
  subject(:article) { FactoryBot.create(:article) }

  it { is_expected.to be_an Article }
  it { is_expected.to be_persisted }
end
```

--------------------------------

### Model spec testing title validation (bad example)

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This is a cautionary example of how NOT to test model validations. Using `expect(article).to_not be_valid` without checking `errors[:attribute]` can lead to ambiguous test failures. It's better to check specific error messages.

```ruby
describe '#title' do
  it 'is required' do
    article.title = nil
    expect(article).to_not be_valid
  end
end
```

--------------------------------

### Use Verifying Class Doubles

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use class_double to create doubles for classes. This example creates a double for the 'Notifier' class and expects the 'notify' method to be called.

```ruby
notifier = class_double('Notifier')
expect(notifier).to receive(:notify).with('suspended as')
```

--------------------------------

### Leading Subject Declaration in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

When using `subject`, it should be the first declaration within an example group for better readability.

```ruby
# bad
describe Article do
  before do
    # ...
  end

  let(:user) { FactoryBot.create(:user) }
  subject { FactoryBot.create(:some_article) }

  describe '#summary' do
    # ...
  end
end

# good
describe Article do
  subject { FactoryBot.create(:some_article) }
  let(:user) { FactoryBot.create(:user) }

  before do
    # ...
  end

  describe '#summary' do
    # ...
  end
end
```

--------------------------------

### Avoid Implicit Block Expectations

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Avoid using implicit block expectations with RSpec. This example shows the 'bad' way of using a subject that is a lambda.

```ruby
# bad
subject { -> { do_something } }
it { is_expected.to change(something).to(new_value) }
```

--------------------------------

### Stub Constants with Anonymous Classes

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Stub constants with anonymous classes when the class itself needs to be defined within the test scope. This example defines and stubs 'FooClass'.

```ruby
# good - constant is stubbed
describe SomeClass do
  before do
    foo_class = Class.new(described_class) do
                  def do_something
                  end
                end
    stub_const('FooClass', foo_class)
  end

  it { expect(FooClass.new.double_that).to eq(4) }
end
```

--------------------------------

### RSpec View Spec File Naming Convention

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Follow the convention of naming view spec files by appending `_spec.rb` to the view file name. For example, `_form.html.erb` corresponds to `_form.html.erb_spec.rb`.

```ruby
# spec/views/articles/new.html.erb_spec.rb
describe 'articles/new.html.erb' do
  # ...
end
```

--------------------------------

### Describe Methods Clearly

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Recommends using '.' for class methods and '#' for instance methods in describe blocks for clarity, following Ruby documentation conventions.

```ruby
# bad
describe 'the authenticate method for User' do
  # ...
end

describe 'if the user is an admin' do
  # ...
end

# good
describe '.authenticate' do
  # ...
end

describe '#admin?' do
  # ...
end
```

--------------------------------

### Create FactoryBot Factory

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use FactoryBot.create to create instances of your models for testing.

```ruby
subject(:article) { FactoryBot.create(:article) }
```

--------------------------------

### RSpec configuration files

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Configure RSpec globally in `~/.rspec`, per project in `.rspec`, and for local overrides in `.rspec-local`. Use `rspec --init` to generate initial files.

```ruby
--color
--require spec_helper
```

```ruby
--profile 2
```

--------------------------------

### Mailer expectations for successful registration

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Test mailers by verifying subject, sender, recipient, and content. Mock the model to avoid dependencies on its creation.

```ruby
describe SubscriberMailer do
  let(:subscriber) { double(Subscription, email: 'johndoe@test.com', name: 'John Doe') }

  describe 'successful registration email' do
    subject(:email) { SubscriptionMailer.successful_registration_email(subscriber) }

    it { is_expected.to have_attributes(subject: 'Successful Registration!', from: ['infor@your_site.com'], to: [subscriber.email]) }

    it 'contains the subscriber name' do
      expect(email.body.encoded).to match(subscriber.name)
    end
  end
end
```

--------------------------------

### RSpec Context for Article Scenarios

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Demonstrates structuring RSpec tests using `context` blocks to differentiate scenarios based on the presence of an author. This improves test clarity and organization.

```ruby
# bad
describe Article do
  context 'when there is an author' do
    subject(:article) { FactoryBot.create(:article, author: user) }

    it 'shows other articles by the same author' do
      expect(article.related_stories).to include(story1, story2)
    end
  end

  context 'when the author is anonymous' do
    subject(:article) { FactoryBot.create(:article, author: nil) }

    it 'matches stories by title' do
      expect(article.related_stories).to include(story3, story4)
    end
  end
end

# good
describe Article do
  context 'when article has an author' do
    subject(:article) { FactoryBot.create(:article, author: user) }

    it 'shows other articles by the same author' do
      expect(article.related_stories).to include(story1, story2)
    end
  end

  context 'when the author is anonymous' do
    subject(:guest_article) { FactoryBot.create(:article, author: nil) }

    it 'matches stories by title' do
      expect(guest_article.related_stories).to include(story3, story4)
    end
  end
end
```

--------------------------------

### Group 'let' and Separate Hooks

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Demonstrates organizing 'let' and 'subject' blocks separately from 'before'/'after' blocks in RSpec for better readability.

```ruby
# bad
describe Article do
  subject { FactoryBot.create(:some_article) }
  let(:user) { FactoryBot.create(:user) }
  before do
    # ...
  end
  after do
    # ...
  end
  describe '#summary' do
    # ...
  end
end

# good
describe Article do
  subject { FactoryBot.create(:some_article) }
  let(:user) { FactoryBot.create(:user) }

  before do
    # ...
  end

  after do
    # ...
  end

  describe '#summary' do
    # ...
  end
end
```

--------------------------------

### Use One Empty Line Between 'describe' Blocks

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Illustrates the correct placement of empty lines between 'feature', 'context', or 'describe' blocks in RSpec.

```ruby
# bad
describe Article do
  describe '#summary' do
    context 'when there is a summary' do
      # ...
    end
    context 'when there is no summary' do
      # ...
    end

  end
  describe '#comments' do
    # ...
  end
end

# good
describe Article do
  describe '#summary' do
    context 'when there is a summary' do
      # ...
    end

    context 'when there is no summary' do
      # ...
    end
  end

  describe '#comments' do
    # ...
  end
end
```

--------------------------------

### Controller spec for POST create action

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This controller spec focuses on the behavior of the 'create' action for ArticlesController. It mocks the Article model and stubs its methods to isolate controller logic. Ensure the correct attributes are passed during the post request.

```ruby
describe ArticlesController do
  let(:article) { double(Article) }

  describe 'POST create' do
    before { allow(Article).to receive(:new).and_return(article) }

    it 'creates a new article with the given attributes' do
      expect(Article).to receive(:new).with(title: 'The New Article Title').and_return(article)
      post :create, message: { title: 'The New Article Title' }
    end

    it 'saves the article' do
      expect(article).to receive(:save)
      post :create
    end

    it 'redirects to the Articles index' do
      allow(article).to receive(:save)
      post :create
      expect(response).to redirect_to(action: 'index')
    end
  end
end
```

--------------------------------

### Built-in Matcher for Inclusion

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Shows the preferred way to check for inclusion using the 'include' matcher instead of string manipulation with 'include?' and 'be true'.

```ruby
# bad
it 'includes a title' do
  expect(article.title.include?('a lengthy title')).to be true
end

# good
it 'includes a title' do
  expect(article.title).to include 'a lengthy title'
end
```

--------------------------------

### Avoid Empty Lines After 'describe' Blocks

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Demonstrates correct and incorrect usage of empty lines after 'feature', 'context', or 'describe' descriptions in RSpec.

```ruby
# bad
describe Article do

  describe '#summary' do

    context 'when there is a summary' do

      it 'returns the summary' do
        # ...
      end
    end
  end
end

# good
describe Article do
  describe '#summary' do
    context 'when there is a summary' do
      # ...
    end
  end
end
```

--------------------------------

### Controller spec with contexts for create action

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This controller spec uses contexts to test different outcomes of the 'create' action based on whether the article saves successfully. It verifies flash messages, assignments, and template rendering for both success and failure scenarios.

```ruby
describe ArticlesController do
  let(:article) { double(Article) }

  describe 'POST create' do
    before { allow(Article).to receive(:new).and_return(article) }

    it 'creates a new article with the given attributes' do
      expect(Article).to receive(:new).with(title: 'The New Article Title').and_return(article)
      post :create, article: { title: 'The New Article Title' }
    end

    it 'saves the article' do
      expect(article).to receive(:save)
      post :create
    end

    context 'when the article saves successfully' do
      before do
        allow(article).to receive(:save).and_return(true)
      end

      it 'sets a flash[:notice] message' do
        post :create
        expect(flash[:notice]).to eq('The article was saved successfully.')
      end

      it 'redirects to the Articles index' do
        post :create
        expect(response).to redirect_to(action: 'index')
      end
    end

    context 'when the article fails to save' do
      before do
        allow(article).to receive(:save).and_return(false)
      end

      it 'assigns @article' do
        post :create
        expect(assigns[:article]).to eq(article)
      end

      it "re-renders the 'new' template" do
        post :create
        expect(response).to render_template('new')
      end
    end
  end
end
```

--------------------------------

### Use 'expect' Syntax

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Mandates the use of the newer 'expect' syntax over the older 'should' syntax for RSpec tests. Shows the correct way to configure RSpec to enforce this.

```ruby
# bad
it 'creates a resource' do
  response.should respond_with_content_type(:json)
end

# good
it 'creates a resource' do
  expect(response).to respond_with_content_type(:json)
end
```

--------------------------------

### Predicate Matcher Usage

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Demonstrates the use of RSpec's predicate matchers for cleaner and more readable boolean checks, contrasting with the 'to be true' approach.

```ruby
describe Article do
  subject(:article) { FactoryBot.create(:article) }

  # bad
  it 'is published' do
    expect(article.published?).to be true
  end

  # good
  it 'is published' do
    expect(article).to be_published
  end

  # even better
  it { is_expected.to be_published }
end
```

--------------------------------

### Add Empty Line After 'let' and Hooks

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Shows the correct placement of an empty line after 'let', 'subject', and 'before'/'after' blocks in RSpec.

```ruby
# bad
describe Article do
  subject { FactoryBot.create(:some_article) }
  describe '#summary' do
    # ...
  end
end

# good
describe Article do
  subject { FactoryBot.create(:some_article) }

  describe '#summary' do
    # ...
  end
end
```

--------------------------------

### Use `:context` Scope for RSpec `before`/`after` Hooks

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Prefer `:context` over the ambiguous `:all` scope for `before` and `after` hooks to clearly define the scope and avoid potential state leakage issues.

```ruby
# bad
describe '#summary' do
  before(:all) do
    # ...
  end

  # ...
end

# good
describe '#summary' do
  before(:context) do
    # ...
  end

  # ...
end
```

--------------------------------

### Using Contexts for Test Organization in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Employ `context` blocks to enhance the clarity, organization, and readability of your tests.

```ruby
# bad
it 'has 200 status code if logged in' do
  expect(response).to respond_with 200
end

it 'has 401 status code if not logged in' do
  expect(response).to respond_with 401
end

# good
context 'when logged in' do
  it { is_expected.to respond_with 200 }
end

context 'when logged out' do
  it { is_expected.to respond_with 401 }
end
```

--------------------------------

### Use Capybara Negative Selectors

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Prefer Capybara's `have_no_selector` and `have_no_xpath` over `to_not have_selector` and `to_not have_xpath` for more readable negative assertions.

```ruby
# bad
expect(page).to_not have_selector('input', type: 'submit')
expect(page).to_not have_xpath('tr')
```

```ruby
# good
expect(page).to have_no_selector('input', type: 'submit')
expect(page).to have_no_xpath('tr')
```

--------------------------------

### Use Factory Bot for Test Data in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Utilize Factory Bot for creating test data in integration tests. Avoid using `ModelName.create` directly in specs. Fixtures are also less maintainable than factories.

```ruby
# bad
subject(:article) do
  Article.create(
    title: 'Piccolina',
    author: 'John Archer',
    published_at: '17 August 2172',
    approved: true
  )
end
```

--------------------------------

### Avoid Generic 'be' Matcher

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Explains why the generic 'be' matcher should be avoided due to its broad acceptance. Suggests using 'be_truthy', 'not_to be_nil', or type-specific matchers for clarity.

```ruby
# bad
it 'has author' do
  expect(article.author).to be
end

# good
it 'has author' do
  expect(article.author).to be_truthy # same as the original
  expect(article.author).not_to be_nil # `be` is often used to check for non-nil value
  expect(article.author).to be_an(Author) # explicit check for the type of the value
end
```

--------------------------------

### Declaration Order in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Declare `subject`, `let!`/`let`, and `before`/`after` hooks in this specific order: `subject`, then `let!`/`let`, and finally `before`/`after` hooks.

```ruby
# bad
describe Article do
  before do
    # ...
  end

  after do
    # ...
  end

  let(:user) { FactoryBot.create(:user) }
  subject { FactoryBot.create(:some_article) }

  describe '#summary' do
    # ...
  end
end

# good
describe Article do
  subject { FactoryBot.create(:some_article) }
  let(:user) { FactoryBot.create(:user) }

  before do
    # ...
  end

  after do
    # ...
  end

  describe '#summary' do
    # ...
  end
end
```

--------------------------------

### Define Anonymous Classes for Testing

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Define anonymous classes using Class.new when you need a temporary class for testing, avoiding the need to stub constants.

```ruby
# bad
describe SomeClass do
  class FooClass < described_class
    def double_that
      some_base_method * 2
    end
  end

  it { expect(FooClass.new.double_that).to eq(4) }
end

# good - anonymous class, no constant needs to be defined
describe SomeClass do
  let(:foo_class) do
    Class.new(described_class) do
      def double_that
        some_base_method * 2
      end
    end
  end

  it { expect(foo_class.new.double_that).to eq(4) }
end
```

--------------------------------

### Use `shoulda-matchers` for Model Validations

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Employ the `shoulda-matchers` gem to simplify model validation tests. This provides concise and readable matchers for common validation scenarios.

```ruby
# bad
describe '#title' do
  it 'is required' do
    article.title = nil
    article.valid?
    expect(article.errors[:title])
      .to contain_exactly('Article has no title')
    not
  end
end
```

```ruby
# good
describe '#title' do
  it 'is required' do
    expect(article).to validate_presence_of(:title)
      .with_message('Article has no title')
  end
end
```

--------------------------------

### Model spec defining a FactoryBot article

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This model spec defines a FactoryBot factory for an Article. It's used to create article instances for other tests, promoting DRY principles in model testing.

```ruby
describe Article do
  let(:article) { FactoryBot.create(:article) }
end
```

--------------------------------

### Prefer `let` over Instance Variables in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use `let` definitions instead of instance variables for better test clarity and maintainability.

```ruby
# bad
before { @name = 'John Wayne' }

it 'reverses a name' do
  expect(reverser.reverse(@name)).to eq('enyaW nhoJ')
end

# good
let(:name) { 'John Wayne' }

it 'reverses a name' do
  expect(reverser.reverse(name)).to eq('enyaW nhoJ')
end
```

--------------------------------

### Separate describe for attribute validations

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use a separate `describe` block for each attribute that has validations. This improves readability and organization of tests.

```ruby
describe '#title' do
  it 'is required' do
    article.title = nil
    article.valid?
    expect(article.errors[:title].size).to eq(1)
  end
end

describe '#name' do
  it 'is required' do
    article.name = nil
    article.valid?
    expect(article.errors[:name].size).to eq(1)
  end
end
```

--------------------------------

### Model spec checking article validity

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This model spec verifies that an article created with FactoryBot is valid. It's a good practice to ensure that your factories produce valid model instances.

```ruby
describe Article do
  it 'is valid with valid attributes' do
    expect(article).to be_valid
  end
end
```

--------------------------------

### Mock Models in View Specs

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Always mock models within view specs. The primary purpose of views is to display information, so focus on the presentation layer and avoid testing model logic here.

```ruby
# spec/views/articles/edit.html.erb_spec.rb
describe 'articles/edit.html.erb' do
  it 'renders the form for a new article creation' do
    assign(:article, double(Article).as_null_object)
    render
    expect(rendered).to have_selector('form',
      method: 'post',
      action: articles_path
    ) do |form|
      expect(form).to have_selector('input', type: 'submit')
    end
  end
end
```

--------------------------------

### Stubbing a helper method in a view spec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

This spec demonstrates how to stub a helper method within a view spec to control its output. Ensure the helper method is allowed to receive the correct arguments and return the expected value.

```ruby
describe 'articles/show.html.erb' do
  it 'displays the formatted date of article publishing' do
    article = double(Article, published_at: Date.new(2012, 01, 01))
    assign(:article, article)

    allow(template).to_receive(:formatted_date).with(article.published_at).and_return('01.01.2012')

    render
    expect(rendered).to have_content('Published at: 01.01.2012')
  end
end
```

--------------------------------

### Simplify JSON Response Assertions in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Use `include_json` matcher for cleaner assertions on JSON responses, replacing manual parsing and key checks.

```ruby
it 'returns JSON with temperature in Celsius' do
  json = JSON.parse(response.body).with_indifferent_access
  expect(json[:celsius]).to eq 30
end
```

```ruby
it 'returns JSON with temperature in Fahrenheit' do
  json = JSON.parse(response.body).with_indifferent_access
  expect(json[:fahrenheit]).to eq 86
end
```

```ruby
it 'returns JSON with temperature in Celsius' do
  expect(response).to include_json(celsius: 30)
end
```

```ruby
it 'returns JSON with temperature in Fahrenheit' do
  expect(response).to include_json(fahrenheit: 86)
end
```

--------------------------------

### Stub View Helper Methods in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

When views utilize helper methods, stub these methods on the `template` object to isolate the view rendering process. This ensures that the view spec focuses solely on the view's behavior.

```ruby
# app/helpers/articles_helper.rb
class ArticlesHelper
  def formatted_date(date)
    # ...
  end
end
```

```ruby
# app/views/articles/show.html.erb
<%= 'Published at: #{formatted_date(@article.published_at)}' %>
```

--------------------------------

### Avoid `any_instance_of` in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Refactor tests to avoid `allow_any_instance_of` or `expect_any_instance_of`. This pattern can indicate overly complex objects and lead to ambiguous receive counts. Instead, stub methods directly on the specific instance.

```ruby
# bad
it 'has a name' do
  allow_any_instance_of(User).to receive(:name).and_return('Tweedledee')
  expect(account.name).to eq 'Tweedledee'
end
```

```ruby
# good
let(:account) { Account.new(user) }

it 'has a name' do
  allow(user).to receive(:name).and_return('Tweedledee')
  expect(account.name).to eq 'Tweedledee'
end
```

--------------------------------

### Naming for uniqueness validation

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

When testing the uniqueness of a model attribute, name the other object `another_object` to clearly indicate its purpose.

```ruby
describe Article do
  describe '#title' do
    it 'is unique' do
      another_article = FactoryBot.create(:article, title: article.title)
      article.valid?
      expect(article.errors[:title].size).to eq(1)
    end
  end
end
```

--------------------------------

### Use Named `subject` in RSpec for Clarity

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Prefer named `subject` declarations over anonymous ones when the subject is referenced in tests. Anonymous subjects are best suited for use with `is_expected`.

```ruby
# bad
describe Article do
  subject { FactoryBot.create(:article) }

  it 'is not published on creation' do
    expect(subject).not_to be_published
  end
end

# good
describe Article do
  subject { FactoryBot.create(:article) }

  it 'is not published on creation' do
    is_expected.not_to be_published
  end
end

# even better
describe Article do
  subject(:article) { FactoryBot.create(:article) }

  it 'is not published on creation' do
    expect(article).not_to be_published
  end
end
```

--------------------------------

### Avoid Stubbing Subject in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Do not stub methods of the object under test. This often indicates a design issue with the object itself. Prefer correct subject initialization or better object design.

```ruby
# bad
describe 'Article' do
  subject(:article) { Article.new }

  it 'indicates that the author is unknown' do
    allow(article).to receive(:author).and_return(nil)
    expect(article.description).to include('by an unknown author')
  end
end

# good - with correct subject initialization
describe 'Article' do
  subject(:article) { Article.new(author: nil) }

  it 'indicates that the author is unknown' do
    expect(article.description).to include('by an unknown author')
  end
end

# good - with better object design
describe 'Article' do
  subject(:presenter) { ArticlePresenter.new(article) }
  let(:article) { Article.new }

  it 'indicates that the author is unknown' do
    allow(article).to receive(:author).and_return(nil)
    expect(presenter.description).to include('by an unknown author')
  end
end
```

--------------------------------

### Use `subject` for Repetitive Test Subjects in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Employ the `subject` method to define the primary object under test, reducing repetition when multiple tests refer to the same subject.

```ruby
# bad
it { expect(hero.equipment).to be_heavy }
it { expect(hero.equipment).to include 'sword' }

# good
subject(:equipment) { hero.equipment }

it { expect(equipment).to be_heavy }
it { expect(equipment).to include 'sword' }
```

--------------------------------

### Avoid `it` in Iterators for RSpec Tests

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Do not use iterators to generate tests, as this forces developers to edit unrelated code when features change. Instead, create separate `describe` blocks for each distinct test case.

```ruby
# bad
[:new, :show, :index].each do |action|
  it 'returns 200' do
    get action
    expect(response).to be_ok
  end
end

# good - more verbose, but better for the future development
describe 'GET new' do
  it 'returns 200' do
    get :new
    expect(response).to be_ok
  end
end

describe 'GET show' do
  it 'returns 200' do
    get :show
    expect(response).to be_ok
  end
end

describe 'GET index' do
  it 'returns 200' do
    get :index
    expect(response).to be_ok
  end
end
```

--------------------------------

### Context Cases and Negative Counterparts in RSpec

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Ensure `context` blocks have a corresponding negative case to avoid code smells and ensure thorough testing. A single context without a negative counterpart may indicate a need for refactoring or a lack of purpose.

```ruby
# bad - needs refactoring
describe '#attributes' do
  context 'the returned hash' do
    it 'includes the display name' do
      # ...
    end

    it 'includes the creation time' do
      # ...
    end
  end
end

# bad - the negative case needs to be tested, but isn't
describe '#attributes' do
  context 'when display name is present' do
    before do
      article.display_name = 'something'
    end

    it 'includes the display name' do
      # ...
    end
  end
end

# good
describe '#attributes' do
  subject(:attributes) { article.attributes }
  let(:article) { FactoryBot.create(:article) }

  context 'when display name is present' do
    before do
      article.display_name = 'something'
    end

    it { is_expected.to include(display_name: article.display_name) }
  end

  context 'when display name is not present' do
    before do
      article.display_name = nil
    end

    it { is_expected.not_to include(:display_name) }
  end
end
```

--------------------------------

### Manage Incidental State in RSpec Tests

Source: https://raw.githubusercontent.com/rubocop/rspec-style-guide/refs/heads/master/README.adoc

Avoid incidental state in tests. Prefer using RSpec's expectation matching for state changes, such as `change(Article, :count).by(1)`, to ensure tests are independent and reliable.

```ruby
# bad
it 'publishes the article' do
  article.publish

  # Creating another shared Article test object above would cause this
  # test to break
  expect(Article.count).to eq(2)
end

# good
it 'publishes the article' do
  expect { article.publish }.to change(Article, :count).by(1)
end
```
Tokens:
Raw