Adds a sequence method for traversable values

[lukeraymonddowning]

Me again!

Part two of my little ballet of code is the sequence method. Imagine that you have a traversable array or collection and you want to check that each item sequentially follows a set of assertions.

I often need this kind of functionality when I'm dealing with mocked responses, and I want to make sure that the values returned in a collection of objects match the mock.

Here's an example of the usage:

/**
 * The mocked UserImporter class returns 3 user objects.
 * The first user is called Luke, the second Nuno and 
 * the third Taylor. We want to check they've 
 * actually been imported as expected.
 */
$users = resolve(UserImporter::class)->import(); 

expect($users->map->name)->sequence(
    fn($expect) => $expect->toEqual('Luke'),
    fn($expect) => $expect->toEqual('Nuno'),
    fn($expect) => $expect->toEqual('Taylor'),
);

If you like this and feel it warrants becoming part of the expectation API, there is a point of discussion, which is "should a BedMethodCall exception be thrown if the number of items in the traversable is less than the number of declared sequence items?"

Have a great weekend!

[lukeraymonddowning]

There is another option here in that instead of a sequence method we could simply allow a varadic number of closures to the each method...

[nunomaduro]

Still ensure about the naming on this one.

[lukeraymonddowning]

Open to other names!

I took inspiration for the sequence name from here: https://laravel.com/docs/http-client#faking-response-sequences

[nunomaduro]

That helps - so should we go for:

expect([1, 2])->each->sequence(
    fn($number) => $number->toEqual(1),
    fn($number) => $number->toEqual(2),
);

Or:

expect([1, 2])->sequence(
    fn($number) => $number->toEqual(1),
    fn($number) => $number->toEqual(2),
);

[lukeraymonddowning]

Actually, I really like it chained to each. Refactored to that.

[lukeraymonddowning]

This now allows for:

expect([1, 2, 3])
    ->each->toBeInt()
    ->sequence(
        fn($expect) => $expect->toBe(1),
        fn($expect) => $expect->toBe(2),
        fn($expect) => $expect->toBe(3)
    );