rspec-conventions

RSpec Conventions (Rootstrap)

Apply these whenever producing or modifying RSpec test code. Full guide: https://github.com/rootstrap/tech-guides/blob/master/ruby/rspec/style_guide.md

Complements ruby-conventions — language-level Ruby style still applies.

Structure & Formatting

• No blank line directly after describe/context/feature opening.
• Leave one blank line after let/subject groups and after before/after blocks.
• Group let and subject together; separate them from before/after with a blank line.
• One blank line around each it block.
• Use before (not before(:each)); before(:all) should be rare and explicit.

describe & context

• describe '#method' for instance methods, describe '.method' for class methods.
• context descriptions must start with when or with, forming a grammatical sentence.

  context 'when the display name is not present'
  

• Every context should have a matching opposite/negative case — a lone context is a smell.
• Don't end it descriptions with a conditional ("...if X") — wrap in a context instead.

it / Examples

• Never start it with "should" / "should not". State behavior directly.

  it 'returns the summary'   # not: 'should return the summary'
  

• One expectation per it block (split multi-assertion examples).
• Avoid generating examples via iterators; use shared examples instead.

  shared_examples 'responds successfully' do
    it 'returns 200' do ... end
  end
  it_behaves_like 'responds successfully'
  

let & subject

• Prefer let over before { @x = ... } for test data (lazy, no instance vars).
• let is lazy (evaluated on first reference) and cached within a single example, not across examples. Use let! when you need eager evaluation before each example.
• Use let for values shared across several (not necessarily all) its in a context; avoid overuse — it hurts readability.
• Use subject when describing a single primary object.

  subject { create(:article) }