Verified doubles in RSpec: choosing between allow, expect, and spies without brittle mocks

Choosing the Right Interaction Pattern

To reduce brittle mocks and standardize a growing suite, the distinction between allow, expect, and spies should be based on whether the interaction is a requirement for execution or the primary behavior being verified.

The Rule of Thumb

• Use allow (Stubbing): When a collaborator must return a specific value for the system under test (SUT) to function, but the fact that the method was called is not the goal of the test. This prevents over-specification.
• Use expect(...).to receive (Mocking): When the call to the collaborator is the primary outcome. Use this for side-effect-heavy operations (e.g., sending an email, triggering a payment gateway) where a missing call constitutes a failure.
• Use Spies: When you prefer the Arrange-Act-Assert (AAA) pattern. Spies allow you to execute the code first and verify the interaction afterward, which often leads to more readable tests and avoids the "expectation before execution" mental overhead.

Verified Doubles: instance_double

Verified doubles solve the "silent failure" problem by checking the stubbed interface against the actual class definition.

Verification Capabilities

Feature	Behavior
Method Existence	Fails if the method does not exist on the real class.
Argument Arity	Fails if the number of arguments passed to the stub differs from the real method signature.
Class Loading	The real class must be loaded in the Ruby environment; otherwise, RSpec cannot verify the interface.

Risks of Wholesale Conversion

Converting generic double usage to instance_double across a large suite may cause a spike in failures due to:

• Outdated Mocks: Tests that were passing only because they were stubbing non-existent methods will now fail.
• Loading Overhead: Requiring real classes for every double can increase memory usage and boot time if many heavy classes are loaded solely for verification.
• Tight Coupling: While verification prevents API drift, it couples the test to the class structure more tightly than a generic double.

Verification Command

To verify that your instance_double is working, create a test with a non-existent method and run:

# This should raise a RSpec::Mocks::MockExpectationError
instance_double("User", non_existent_method: "value")

Diagnostic Detail Needed: Are you utilizing any dynamic method generation (e.g., method_missing or define_method) in your collaborators? Verified doubles cannot validate methods created dynamically at runtime.