include_examples does not work when block passed

[dchelimsky]

Reported by @antiveb:

# I have defined the following shared examples group
shared_examples_for 'test' do
 #... examples ...
end

describe SomeClass do
  describe '#method' do
    # then I try to put it in use here
    include_examples 'test' do
       let(:something) { :else }
    end
  end
end

In the case above the #include_examples call seems to be skipped completely.

It works if I call #include_examples without the block. It work if I use #it_behaves_like instead of #include_examples.

This happens with latest rspec 2.10.

[dchelimsky]

@antiveb that's by design, but you should be getting a warning saying "Customization blocks not supported ...". Do you think that should be an Exception instead?

[hisenb3rg]

Oh, I understand now. At first I tought #it_behaves_like and #include_examples are more/less synonims...

Well I didn't get any warning inside nested specs output, but now that I understand it I don't think it is necessary to raise errors.

[justinko]

The warning displays at the very top of the output - it's very tough to see.

I think we should raise an exception.

[dchelimsky]

I think we should raise an exception.

Either that or support customization blocks. @justinko, @myronmarston WDTY?

[justinko]

support customization blocks

That sounds good.

[myronmarston]

To be honest, I don't know what the intended difference between include_examples and it_behaves_like is. Regardless, I have a hard time thinking of a reason to not allow the customization block, so I'm on board with adding support for that.

[dchelimsky]

Playing devil's advocate here: include_examples and include_context (which are synonyms) include shared material into the current context. it_behaves_like creates a subclass of the current context and includes the shared material in the subclass, so the intent is quite different.

[dchelimsky]

Per my last comment, I don't think we should support customization blocks for include_examples or include_context since they get included directly in the current context. The question remains as to whether we should raise instead of warn. I think we should raise instead, but I'm concerned about rolling that out in a minor release. Any thoughts on that?

[myronmarston]

Hmmm....playing counterpoint to your devil's advocate: the mechanism for creating the shared examples for include_examples or it_behaves_like is the same, right (shared_examples_for)? So when shared_examples_for is used, the developer doesn't have to know up front whether the user of the shared examples will use include_context or it_behaves_like. Regardless, the shared example group may have dependencies on some helper methods that the user of the group is expected to define. In a case where I use include_examples (maybe because making it a nested group doesn't really make sense in the --format doc output, or whatever), I think I would still want to define my helper methods in a customization block, to make it explicit that the helper methods are needed by the examples included by include_examples--otherwise the helper methods appear to be floating there, unused by anything (and thus superficially look like a good candidate for removal).

[dchelimsky]

@myronmarston that's a fair argument. My concern is that the difference between include_xxx and it_behaves_like becomes somewhat subtle and arguably arbitrary (why should one suggest a nested group when the other doesn't).

[myronmarston]

My concern is that the difference between include_xxx and it_behaves_like becomes somewhat subtle and arguably arbitrary (why should one suggest a nested group when the other doesn't).

That's true, but I don't think that supporting a customization block makes it any more or less subtle and apparently arbitrary.

To me, the main benefit of the customization block (the fact that it makes explicit the relationship between helper methods and the shared examples that use them) is orthogonal to whether or not the shared examples are included in the host group or in a nested group. Thus, I don't think it makes sense to restrict it.