instance_double interface validation with metaprogramming extensions

Confirmed facts about instance_double validation

RSpec’s instance_double builds a verified double by inspecting the target class’s method table at the moment the double is created. Because Ruby’s method lookup chain includes modules mixed in with include or extend, any method that exists on the class or its ancestors after those mixins are applied will be seen by the double.

What works

• Methods defined directly in the class.
• Methods added via include or extend on a module, provided the double is instantiated after the module has been mixed in.
• Methods created with define_method on the class or an included module.

What does not work

Methods that exist only because the class implements method_missing (or respond_to_missing?) are not part of the method table, so instance_double cannot see them. Consequently, a call to such a method on the verified double will raise RSpec::Mocks::MockExpectationError (or DoubleUnexpectedMethodError) even though the real object would respond.

Steps to get the behavior you need

1. Ensure the double is created after metaprogramming: If you modify the class with include or extend in a test setup block, instantiate the instance_double in a before hook that runs after those modifications.
2. Handle method_missing:
   • Add explicit definitions for the dynamic interface using define_method on the class or a shared module.
   • Include that module in both the production code and the test double’s target class so the verified double sees the methods.
3. If you cannot modify production code: Accept that you cannot enforce the contract for method_missing-based methods with instance_double; you must fall back to a plain double or use allow/receive stubs without verification.

When the recommendation changes

The only detail that alters the above steps is the timing of the double’s creation relative to the metaprogramming extension. If you are unsure whether the double is being instantiated before or after the include/extend, please confirm that detail so we can advise whether to adjust the test setup or keep the current approach.