Expect

The expect style of writing assertions is ideal for BDD testing scenarios. It is useful for creating fluent, readable test expectations.

Language Chains

Leo provides the following language chains. They exist only to make tests more readable, unless overwritten by a plugin:

• to
• be
• been
• is
• and
• has
• have
• with
• that
• at
• of
• same
• an
• a

->not

Negates the assertion it precedes.

<?php
expect($name)->to->not->equal('brian');
expect([$obj, 'method'])->to->not->throw('Exception');
expect($obj)->to->have->property('name')
    ->and->not->equal('brian');
?>

->a(type)

• @param string $type
• @param string $message [optional]

Performs a type assertion using PHP's gettype function. The alias an can be used as well. Both an and a can be used as language chains.

<?php
expect('leo')->to->be->a('string');
expect(tmpfile())->to->be->a('resource');
expect([])->to->be->an('array');

//language chain
expect($request)->to->be->an->instanceof('Request');
?>

->include(value)

• @param mixed $value
• @param string $message [optional]

The include and contain assertions are used to check if an array or object implementing `ArrayAccess` contains a value or if a string contains a substring. Either can be used as a language chain to enable the contain flag for use with the keys assertion.

<?php
expect([1,2,3])->to->include(1);
expect('hello world')->to->contain('hello');

//language chain
expect(['name' => 'leo', 'lang' => 'php'])->to->include->keys(['name']);
?>

->ok

• @param string $message [optional]

Asserts that the target is true when cast to (bool). Can be used as both a method and a property.

<?php
expect(true)->to->be->ok;
expect("string")->to->be->ok;
expect([])->to->not->be->ok;

//as a method
expect(1)->to->be->ok();
?>

->true

• @param string $message [optional]

Asserts that the target is exactly true. Can be used as both a method and a property.

<?php
expect(true)->to->be->true;
expect(1)->to->not->be->true;

//as a method
expect(true)->to->be->true();
?>

->false

• @param string $message [optional]

Asserts that the target is exactly false. Can be used as both a method and a property.

<?php
expect(false)->to->be->false;
expect(0)->to->not->be->false;

//as a method
expect(false)->to->be->false();
?>

->null

• @param string $message [optional]

Asserts that the target is null. Can be used as both a method and a property.

<?php
expect(null)->to->be->null;
expect($mybar)->to->not->be->null;

//as a method
expect(null)->to->be->null();
?>

->empty

• @param string $message [optional]

Asserts that the target is empty via PHP's empty function. Can be used as both a method and a property.

<?php
expect([]])->to->be->empty;
expect([1,2,3])->to->not->be->empty;

//as a method
expect([])->to->be->empty();
?>

->equal(value)

• @param mixed $value
• @param string $message [optional]

Asserts that the target is strictly === equal to value. For loose comparison, the loosely flag can be used.

<?php
expect("hello")->to->equal("hello");
expect(1)->to->equal(1);
expect([1,2,3])->to->loosely->equal([1,2,3]);
?>

->above(value)

• @param number $value
• @param string $message [optional]

Asserts that the target is greater than value.

<?php
expect(6)->to->be->above(3);
?>

Can be used with the length flag if the target has a length.

<?php
expect('string')->to->have->length->above(3);
expect([1,2,3])->to->have->length->above(2);
?>

->least(value)

• @param number $value
• @param string $message [optional]

Asserts that the target is greater than or equal to value.

<?php
expect(6)->to->be->at->least(6);
?>

Can be used with the length flag if the target has a length.

<?php
expect('string')->to->have->length->of->at->least(3);
expect([1,2,3])->to->have->length->of->at->least(2);
?>

->below(value)

• @param number $value
• @param string $message [optional]

Asserts that the target is less than value.

<?php
expect(3)->to->be->below(6);
?>

Can be used with the length flag if the target has a length.

<?php
expect('hi')->to->have->length->below(3);
expect([1])->to->have->length->below(2);
?>

->most(value)

• @param number $value
• @param string $message [optional]

Asserts that the target is less than or equal to value.

<?php
expect(3)->to->be->at->most(3);
?>

Can be used with the length flag if the target has a length.

<?php
expect('hi')->to->have->length->of->at->most(3);
expect([1,2,3])->to->have->length->of->at->most(5);
?>

->within(lower, upper)

• @param number $lower
• @param number $upper
• @param string $message [optional]

Asserts that the target is between lower (inclusive), and upper (inclusive).

<?php
expect(3)->to->be->within(2, 4);
?>

Can be used with the length flag if the target has a length.

<?php
expect('hi')->to->have->length->within(2, 4);
expect([1,2,3])->to->have->length->within(2, 4);
?>

->instanceof(className)

• @param string $className
• @param string $message [optional]

Asserts that the target is an instance of the class identified by className

<?php
expect($request)->to->be->an->instanceof('Symfony\Component\HttpFoundation\Request')
expect($object)->to->be->an->instanceof('stdClass');
?>

->property(name, [value])

• @param string $name
• @param mixed $value [optional]
• @param string $message [optional]

Asserts that the target array or object has the given index or property name identified by name. If value is supplied, it will be strictly compared to that property.

<?php
$person = new stdClass();
$person->name = "brian";

expect($person)->to->have->property('name');
expect($person)->to->have->property('name', 'brian');

$arrayPerson = ['name' => 'brian'];
expect($arrayPerson)->to->have->property('name');
expect($arrayPerson)->to->have->property('name', 'brian');
?>

When used with the deep flag, the property assertion can traverse nested structures as well.

<?php
$person = new stdClass();
$person->name = new stdClass();
$person->name->first = "brian";

expect($person)->to->have->a->deep->property('name->first');
expect($person)->to->have->a->deep->property('name->first', 'brian');

$arrayPerson = [
    'name' => 'brian', 
    'hobbies' => [
        'programming',
        'reading',
        'music'
    ]
];

expect($arrayPerson)->to->have->deep->property('hobbies[0]');
expect($arrayPerson)->to->have->deep->property('hobbies[2]', 'music');
?>

A note on the property assertion: The property assertion sets the subject of the assertion to the targeted property for further chaining.

<?php
$person = new stdClass();
$person->name = new stdClass();
$person->name->first = "brian";

expect($person)
    ->to->have->a->deep->property('name->first')
    ->that->has->length(5);
?>

->length(value)

• @param number $value
• @param string $message [optional]

Asserts that a target with length has the length of value. A target has length if it is a string, an array, or implements the Countable interface.

<?php
expect('hello')->to->have->length(5);
expect([1,2,3])->to->have->length(3);
?>

This assertion can also be used as a language flag for comparison assertions.

<?php
expect([1,2,3])->to->have->length->above(2);
expect('hello')->to->have->length->below(10);
?>

->match(pattern)

• @param string $pattern
• @param string $message [optional]

The match assertion matches the target string against a regexp string.

<?php
expect('hello')->to->match('/^he/');
?>

->string(string)

• @param string $string
• @param string $message [optional]

Asserts that the target string contains the substring string.

<?php
expect('goodbye')->to->have->string('good');
?>

->keys(keys)

• @param array $keys
• @param string $message [optional]

Asserts that the target array or object has exactly the keys given. Asserts the inclusion of some keys if the contain or include flag is used.

<?php
$pet = new stdClass();
$pet->name = 'fido';
$pet->age = 7;

expect($pet)->to->have->keys(['name', 'age']);

$petArray = ['name' => 'fido', 'age' => 7, 'breed' => 'terrier'];
expect($petArray)->to->include->keys(['name', 'age']);
?>

->throw(exceptionClass, [exceptionMessage])

• @param string $exceptionClass
• @param string $exceptionMessage [optional]
• @param string $message [optional]

Asserts that the target callable throws an exception that is an instance of exceptionClass. If exceptionMessage is provided it will also assert that the exception messages are the same. The with method can be used to pass arguments to the target callable.

<?php
expect([$object, 'method'])->to->throw('RuntimeException');
expect(function($msg) { throw new Exception($msg) })
    ->with('hello')->to->throw('Exception', 'hello');

expect([$object, 'method'])->to->not->throw('Exception');
?>

->satisfy(callable)

• @param callable $callable
• @param string $message [optional]

Asserts that the target satisfies a predicate function.

<?php
expect(1)->to->satisfy('is_numeric');
expect('curly')->to->satisfy(function ($stooge) {
	return preg_match('/curly|larry|moe/', $stooge);
});
?>