Add support for passing parameters and a block through include_examples

[cbascom]

The it_should_behave_like and it_behaves_like methods of pulling in shared examples both allow you to pass parameters and a customization block. In my case I preferred the include_examples method instead of those alternatives but it did not support passing parameters or a block. This change adds that support along with tests for it.

[dchelimsky]

I think this is a good idea, but we should do it for include_context as well, and see how to merge/integrate this with it_behaves_like (since they would now all do fundamentally the same thing). Wanna take a crack at that?

[cbascom]

Sure, I will take a look at that and see what I can come up with.

[myronmarston]

I didn't even know include_examples existed before now. I guess you learn something new every day :).

@dchelimsky: what are the semantics of include_examples supposed to be, compared to it_behaves_like and include_context? I understand the difference between it_behaves_like and include_context (one creates a nested group and includes the shared behavior; the other includes the shared behavior directly in the current example group).

If include_examples is meant to be an alias for it_behaves_like, then I think we can just have it use alias_it_should_behave_like_to to define it as an alias.

As for allowing customization via parameters and a block for include_context...I think we discussed this at one point when we introduced include_context and, for some reason, decided against it...but now I forget why :(.

[cbascom]

I went ahead and added this support in the hopes that Myron is mis-remembering and there is no reason to not make this change :).

In the current implementation include_examples and include_context do basically the same thing (include the shared behavior in the current example group). The only difference is that include_context is intended to be used to only include a shared context with no examples, but there is no code enforcement of this.

[dchelimsky]

@myronmarston - include_examples and include_context have the same semantics: they get evaluated in the current group, whereas it_should_behave_like and it_behaves_like generate nested groups. The only difference is the naming and the wording of the failure message when the shared content can't be found.

After a bit more thought, I think passing params to include_[context|examples] is OK, but passing a block is a bit odd since the block would get executed in the same context in which it is declared. i.e. the following are equivalent:

describe CheckingAccoung do
  include_examples "account" do
    let(:account) { CheckingAccount.new }
  end

  it "does something special" do
    account # refers to the account defined by let(:account)
  end
end

describe CheckingAccoung do
  let(:account) { CheckingAccount.new }
  include_examples "account"

  it "does something special" do
    account # refers to the account defined by let(:account)
  end
end

This strikes me as a recipe for confusion.

What do you think about structuring it such that include_[examples|context] supports params but not a block, while it_[behaves|should_behave]_like supports both params and a block.

[cbascom]

I agree that adding the block doesn't make any sense, I removed that support in my latest commit.

I didn't add anything to raise an error if a block is provided, what do you think about that? The way it is now someone could provide a block thinking that include_[examples|context] work the same as it_[behaves|should_behave]_like and that block will just be silently ignored.

[dchelimsky]

An error or a warning suggesting the user should use it_behaves_like if he/she wants that functionality would be good.

[cbascom]

I added a warning message for both cases if a block is provided.

[dchelimsky]

Great work. Thanks!