Write more expressive tests with Hamcrest Gareth Ellis NomadPHP Lightning Talk, October 2016 

What is Hamcrest? 

Matcher library originally written in Java, ported to PHP Allows for more expressive assertions in your code 

PHPUnit: $this->assertEquals(“2”, $someValue); Hamcrest: assertThat($someValue, is(equalTo(“2”))); 

$food = $data_source->getFood(); $fruit = [ 'orange', 'apple', 'pear', ]; $this->assertEquals(0, count(array_diff($food, $fruit))); $this->assertEquals(0, count(array_diff($fruit, $food))); assertThat($food, containsOnlyValuesFrom($fruit)); Real-world example 

assertThat(3, is(greaterThan(2))); assertThat($someValue, is(atMost(99))); Number matchers! 

assertThat($someString, is(equalToIgnoringCase(“A sTrIng”))); assertThat($someString, containsString($subString)); assertThat($someString, startsWith(“foo”)); String matchers! 

assertThat($object, is(anInstanceOf(SomeClass::class))); assertThat(“string”, is(stringValue())); assertThat(123, is(not(stringValue()))); Type matchers! 

assertThat($option, is(anyOf($arrayOfOptions))); assertThat($option, is(noneOf($arrayOfBlackListedOptions))); Inclusion/exclusion matchers! 

assertThat($array, contains($someValue)); assertThat($array, is(arrayContainingInAnyOrder([“foo”, “bar”]))); assertThat($array, is(arrayWithSize(4))); Array matchers! 

assertThat(“a string”, is(both(stringValue())->andAlso(not(emptyString()))); Chained matchers! 

$ composer require hamcrest/hamcrest-php Usage 

$ composer require –dev graze/hamcrest-test-listener With PHPUnit (optional) In phpunit.xml: Allows PHPUnit to listen for Hamcrest assertions 

require “vendors/hamcrest/hamcrest-php/hamcrest/Hamcrest.php”; Include Hamcrest’s global functions Or autoload via composer.json: { “autoload”: { “files”: [ “./vendors/hamcrest/hamcrest-php/hamcrest/Hamcrest.php” ] } } 

Maximum expressiveness Custom matchers 

$redirectUrl = “/my_app/some_page?foo=bar”; $this->assertEquals(302, $controller->response->statusCode()); $headers = $controller->response->header(); $this->assertArrayHasKey($headers, “Location”); $this->assertEquals($headers[“Location”], $redirectUrl); Have you ever done anything like this in a test? 

$redirectUrl = “/my_app/some_page?foo=bar”; assertThat($controller, redirectedToUrl($redirectUrl)); Wouldn’t it be much nicer to do this instead? assertThat() takes any value as its first argument… …and an instance of \Hamcrest \Matcher as its second argument Functions exist only as expressive factories for instantiating matchers 

class Cake2ControllerRedirectMatcher extends \Hamcrest\BaseMatcher { private $url; public function __construct($url) { $this->url = $url; } public function matches($controller) { } public function describeTo(Description $description) { } } 

class Cake2ControllerRedirectMatcher extends \Hamcrest\BaseMatcher { /* snip */ /** * @param Controller $controller * @return bool */ public function matches($controller) { assertThat($controller, is(anInstanceOf(Controller::class))); $headers = $controller->response->header(); if (!isset($headers["Location"])) { return false; } return $controller->response->statusCode() === 302 && $headers[“Location”] === $this->url; } } 

assertThat(‘foo’, is(intValue())); PHP Fatal error: Uncaught Hamcrest\AssertionError: Expected: is an integer but: was a string "foo" 

class Cake2ControllerRedirectMatcher extends \Hamcrest\BaseMatcher { /* snip */ public function describeTo(\Hamcrest\Description $description) { $description->appendText("Controller to have status code 302 and a header location containing "); $description->appendValue($this->url); } } 

class Cake2ControllerRedirectMatcher extends \Hamcrest\BaseMatcher { /* snip */ public function describeMismatch($controller, \Hamcrest\Description $description) { $description->appendText( “Controller response status code:” . $controller->response->statusCode() . “…” ); $headers = $controller->response->header(); if (!isset($headers[‘Location’])) { $this->appendText(“Location header has not been set”); } else { $description->appendText(“Location header is set as: “); $description->appendValue($headers[“Location”]); } } } 

function redirectedToUrl($url) { return new Cake2ControllerRedirectMatcher($url); } assertThat($controller, redirectedToUrl(“/some/url”)); 

function doSomethingToAString($string) { if (!is_string($string) { throw new InvalidArgumentException(“{$string} is not a string”); } //do something } Not just for tests – reduce boilerplate function doSomethingToAString($string) { assertThat($string, is(stringValue())); //throws \Hamcrest\AssertionError //do something } 

$array = [‘Hello NomadPHP’, ‘Hello Gareth’, ‘Goodbye :-(‘]; $filtered = array_filter($array, startsWith(‘Hello’)); //[‘Hello NomadPHP’, ‘Hello Gareth’] Matchers as callables 

//Mockery $mock->shouldReceive(“some_method”) ->with(stringValue()); //Phake Phake::verify($mock)->some_method(stringValue()); Use with mocking libraries Both Phake and Mockery support using Hamcrest matchers for declaring expectations 

Thank you for listening @garethellis https://github.com/garethellis36/hamcrest-matchers