Don’t Describe Your Context

RSpec gives you two ways to group examples: describe and context.

At first glance, this feels redundant. And that’s because… it is.

They’re aliases. According to the RSpec source code there’s no functional difference.

But that doesn’t mean they should be interchangeable.

A Convention That Adds Clarity

At StepWyz, we treat describe and context differently, not because we have to, but because it makes our test suites easier to read, write, and navigate.

Here’s our rule:

• Use describe when you're identifying the method under test and should always come with a corresponding subject {} block
• Use context when you're describing a variation or condition under which the method is called

This approach gives each test a clear structure: what are we testing, and under what conditions?

Let’s look at a simple example.

# user_spec.rb

describe User do
  describe "#greeting" do
    subject { user.greeting }

    let(:user) { User.new(name: name) }

    context "when the user has a name" do
      let(:name) { "Alice" }

      it { is_expected.to eq("Hello, Alice!") }
    end

    context "when the user has no name" do
      let(:name) { nil }

      it { is_expected.to eq("Hello!") }
    end
  end
end

We’ve found this pattern scales beautifully as context blocks are inherantly nestable. It reduces ambiguity, encourages DRY conditions, allows for writing compact assertions, and makes test output more legible.

You’ve probably seen test files where context and describe are used inconsistently or not at all. That doesn’t break anything, but it can make tests harder to follow and result in a lot of duplicated setup.

By applying a consistent, semantic difference between the two, you give readers (and future you) a legible map of what’s being tested and why.

Try It On Your Next Spec

You don’t need a new gem or plugin for this, just a simple agreement with your team.

Use describe for methods and context for conditions.

It’s a small shift that pays off every time you revisit your test suite.