Added Expect

[dg]

• new feature
• BC break? no

This PR attempts to simplify the comparsion of structures that contain some variable data like this:

$actual = ['a' => md5($s), 'b' => new DateTime, 'c' => rand()];
$expected = ???
Assert::equal($expected, $actual);

I'd like make assertions that

• $actual is array
• it contains keys a, b, c
• and first value is hexa string: Assert::type('string') + Assert::match('%h%', $value)
• second value is object DateTime: Assert::type('DateTime', $value)
• the third value is integer: Assert::type('int', $value)) and >= 0 (Assert::true($value >= 0)

This PR allows to describe it using Assert::equal() + language similar to how Assert is used. Only Assert:: is replaced with Expect::

$actual = ['a' => md5($s), 'b' => new DateTime, 'c' => rand()];
$expected = [
	'a' => Expect::type('string')->andMatch('%h%')),
	'b' => Expect::type(DateTime::class), 
	'c' => Expect::type('int')->and(function ($val) { return $val >= 0; }),
];
Assert::equal($expected, $actual);

In case of error it writes:

Failed: ['a' => 'd41d8cd98f00b204e9800998ecf8427e', 'b' => DateTime(2019-02-17 22:36:36 +0100)(#532c), ...] should be equal to
    ... ['a' => type(string),match(%h%), 'b' => type(DateTime), 'c' => type(int),custom()]

Class name Expect and methods are just working names. Is Assert::equal() good choice?

[JanTvrdik]

must require Closure to avoid collision with __call

[JanTvrdik]

Maybe call it Constraint or Rule? Mockery calls it Matcher.

[JanTvrdik]

I think that it's quite problematic that both __call and __callStatic accept the same method names, making it probably impossible to document with @method annotation.

[dg]

Or what about Is for readability?

Is::notSame($expected)
Is::equal($expected)
Is::notEqual($expected)
Is::contains($needle) // hmmm 
Is::notContains($needle)
Is::nan()
Is::truthy()
Is::falsey()
Is::count(int $count)
Is::type($type)
Is::match(string $pattern) // hmmm.. add alias Is::pattern(), Assert::pattern() ?
Is::matchFile(string $file)

These ones will probably will never used:

Is::same($expected)
Is::true()
Is::false()
Is::null()

[dg]

I think that it's quite problematic that both __call and __callStatic accept the same method name, making it probably impossible to document with @method annotation.

In fact, bigger problem is that Is::abc()::xyz() is perfectly valid, but means something different, Is::xyz().

[dg]

So better will be this syntax Value::type('string')->and(Value::match('%h%')),

[milo]

👍 What about Expect class name?

[milo]

@dg You mentioned ::pattern() It is related to #350. I'm planning to split Assert::match() to ::matchRe() or ::regexp() or something like this.

[milo]

And what about implement all supported static Assert methods on Value class instead of __callStatic()? Stack trace will be cleaner.

[dg]

'Expect' sound good.

And what about implement all supported static Assert methods on Value class instead of __callStatic()? Stack trace will be cleaner.

This is of course possible, but where do you see the stack trace?

[milo]

This is of course possible, but where do you see the stack trace?

An imaginary stack trace when exception thrown somehow in Assert. Small detail only.

Nothing. As I would never said that :)