Add shared examples.

[modocache]

Shared examples allow developers to reuse a set of describe, context,
and it nodes to test one or more classes. See the functional tests in
Tests/Shared Examples/KWSharedExampleFunctionalTest.m for sample
usage.

Addresses issues #175, #138.

• KWSharedExampleRegistry is a singleton that maintains a mapping of
  shared example names to KWSharedExample instances.
• KWSharedExample is a data structure composed of a name and context
  block.
• sharedExamplesFor creates a KWSharedExample and registers it.
• itBehavesLike looks up the KWSharedExample with the given name and
  inserts its context block into the current example group.
• SHARED_EXAMPLES_BEGIN, SHARED_EXAMPLES_END macros are used to
  ensure sharedExamplesFor are evaluated prior to any examples.
• In order to allow assertion macros like should to be compiled outside
  of the implementation block of a KWSpec--like within sharedExamplesFor,
  for example--changed macro to reference global state by using
  KWSpec class method.
• Changed all pragma marks referencing internal/private methods to
  Internal Methods.
• Removed unused KWEncodingForVoidMethod function.

Sample Usage

// CruiserSpecHelpers.m

SHARED_EXAMPLES_BEGIN(CruiserSpecHelpers)

sharedExamplesFor(@"a cruiser", ^(Class describedClass) {
    __block Cruiser *cruiser = nil;
    beforeEach(^{
        cruiser = [[describedClass alloc] initWithCallsign:@"Planet Express"];
    });

    it(@"has a callsign", ^{
        [[cruiser.callsign should] equal:@"Planet Express"];
    });
});

SHARED_EXAMPLES_END

// CruiserSpec.m

SPEC_BEGIN(CruiserSpec)

describe(@"Cruiser", ^{
    itBehavesLike(@"a cruiser", [Cruiser class]);
});

describe(@"Carrier", ^{
    itBehavesLike(@"a cruiser", [Carrier class]);
});

SPEC_END

Additional Comments

Feedback very much appreciated! Especially with regards to the following:

• I'm not particularly thrilled with the use of macros--I'd prefer to use @sharplet's CONFIG_START and CONFIG_END macros, but they don't seem to be working for me.
• Test failures are highlighted in Xcode on the line of the it block in the sharedExamplesFor block, not on the line with itBehavesLike. I don't know how to make the itBehavesLike block highlighted. Callsites? 😕

[modocache]

Is this good to merge? @supermarin @stepanhruda

[supermarin]

@modocache I know it sucks to hear this, and I'm okay if you don't agree.

It would maybe make sense to merge this after we release 2.3 converted to ARC,
so we can have some more time for testing it.

I've converted almost everything, there's 1 file left (KWMessagePattern) that'll be done tomorrow.

[modocache]

Not at all! In fact, I agree 100%. I'm of the opinion that we should prioritize refactors over new features like this, anyway. I was just wondering if anybody had seen this in the first place.

In any case ping me in this thread once you feel 2.3 has calmed down enough.

[zephyr-dev]

We would love to see support for this as well, any chance this will be merged into master anytime soon?

[supermarin]

@modocache hey sorry - totally forgot on this.

As I'm a bit out of happenings recently, what's the state of this PR, is it mergeable?

[modocache]

@supermarin Assuming I can rebase, it's mergeable, but not very well implemented. The problem is that when a shared example fails, the shared example code is highlighted, not the itBehavesLike, which is the site of the test failure.

It's probably possible to highlight the itBehavesLike line--Quick and Specta do this correctly, using different mechanisms. But I don't have the bandwith to fix that bug in this PR... 😢

[ecaselles]

@modocache @supermarin I was wondering what happened to this PR. Any reason why it has not been merged yet, 2.3 was released about 8 months ago? i.e. Is it just due to lack of time or are there any breaking issues?

[modocache]

@ecaselles Lack of time. Feel free to fork, rebase, and re-submit the PR. You could also improve it by fixing the itBehavesLike bug I mention above! 👍

[ecaselles]

@modocache 🙋 I have created PR #600 which basically rebases this PR on top of the current Kiwi version. As part of it, I have also upgraded the tests to run on XCTest instead of SenTestKit. Feel free to review it and leave feedback. 😄

[sharplet]

Closed via #600.