Hamcrest PHP

https://github.com/hamcrest/hamcrest-php
Admin
Hamcrest PHP is the official PHP port of the Hamcrest matcher library, allowing developers to write...
Tokens:3,145
Snippets:33
Trust Score:7.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Array Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Examples of various array-related matchers provided by Hamcrest.

```php
assertThat([], anArray());
```

```php
$list = range(2, 7, 2);
$item = 4;
assertThat($list, hasItemInArray($item));
```

```php
assertThat([2, 4, 6], arrayContainingInAnyOrder([6, 4, 2]));
assertThat([2, 4, 6], arrayContainingInAnyOrder([4, 2, 6]));
```

```php
assertThat([2, 4, 6], arrayContaining([2, 4, 6]));
assertthat([2, 4, 6], not(arrayContaining([6, 4, 2])));
```

```php
assertThat([2, 4, 6], contains([2, 4, 6]));
```

```php
assertThat(['name'=> 'foobar'], hasKeyInArray('name'));
```

```php
assertThat(['name'=> 'foobar'], hasKeyValuePair('name', 'foobar'));
```

```php
assertthat([2, 4, 6], arrayWithSize(3));
```

```php
assertThat([], emptyArray());
```

```php
assertThat([1], nonEmptyArray());
```

--------------------------------

### Registering Global Functions

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Load global proxy functions before use.

```php
\Hamcrest\Util::registerGlobalFunctions();
```

--------------------------------

### Basic Assertion Usage

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Perform assertions using the MatcherAssert class directly.

```php
\Hamcrest\MatcherAssert::assertThat('a', \Hamcrest\Matchers::equalToIgnoringCase('A'));
```

--------------------------------

### Global Proxy Function Usage

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Use global proxy functions for more readable assertions. Requires registering global functions first.

```php
$result = true;
// with an identifier
assertThat("result should be true", $result, equalTo(true));

// without an identifier
assertThat($result, equalTo(true));

// evaluate a boolean expression
assertThat($result === true);

// with syntactic sugar is()
assertThat(true, is(true));
```

--------------------------------

### Object and Instance Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for inspecting object properties, types, and identity.

```php
class Foo {
    public $name = null;

    public function __toString() {
        return "[Foo]Instance";
    }
}
$foo = new Foo;
assertThat($foo, hasToString(equalTo("[Foo]Instance")));
```

```php
$foo = new Foo;
$foo2 = new Foo;
assertThat($foo, equalTo($foo2));
```

```php
assertThat($foo, is(not(identicalTo($foo2))));
```

```php
assertThat($foo, anInstanceOf(Foo::class));
```

```php
assertThat(null, is(nullValue()));
```

```php
assertThat("", notNullValue());
```

```php
assertThat($foo, is(not(sameInstance($foo2))));
assertThat($foo, is(sameInstance($foo)));
```

```php
assertThat(1, typeOf("integer"));
```

```php
assertThat($foo, notSet("name"));
```

```php
$foo->name = "bar";
assertThat($foo, set("name"));
```

--------------------------------

### Assert XML/HTML via XPath

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Use XPath expressions to query and validate DOM structures.

```php
assertThat($dom, hasXPath('books/book/title'));
assertThat($dom, hasXPath('books/book[contains(title, "Alice")]', 3));
assertThat($dom, hasXPath('books/book/title', 'Alice in Wonderland'));
assertThat($dom, hasXPath('count(books/book)', greaterThan(10)));
```

--------------------------------

### String Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for validating string content, case sensitivity, and patterns.

```php
assertThat("", emptyString());
```

```php
assertThat(null, isEmptyOrNullString());
```

```php
assertThat("", nullOrEmptyString());
```

```php
assertThat("foo", isNonEmptyString());
```

```php
assertThat("foo", nonEmptyString());
```

```php
assertThat("Foo", equalToIgnoringCase("foo"));
```

```php
assertThat(" Foo ", equalToIgnoringWhiteSpace("Foo"));
```

```php
assertThat("foobarbaz", matchesPattern('/(foo)(bar)(baz)/'));
```

```php
assertThat("foobar", containsString("foo"));
```

```php
assertThat("fooBar", containsStringIgnoringCase("bar"));
```

```php
assertThat("foo", stringContainsInOrder("foo"));
```

```php
assertThat("foo", endsWith("oo"));
```

```php
assertThat("bar", startsWith("ba"));
```

--------------------------------

### Assert Specific Data Types

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Use type-specific matchers for common PHP data types.

```php
assertThat($count, integerValue());
assertThat(3.14159, floatValue());
assertThat('foo', stringValue());
```

--------------------------------

### Assert Array Key Existence

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify if a key exists or does not exist in an array using isset().

```php
assertThat(array('foo' => 'bar'), set('foo'));
assertThat(array('foo' => 'bar'), notSet('bar'));
```

--------------------------------

### Check Traversable Collections

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for verifying the state and size of traversable objects.

```php
$empty_it = new EmptyIterator;
assertThat($empty_it, emptyTraversable());
```

```php
$non_empty_it = new ArrayIterator(range(1, 10));
assertThat($non_empty_it, nonEmptyTraversable());
a
```

```php
$non_empty_it = new ArrayIterator(range(1, 10));
assertThat($non_empty_it, traversableWithSize(count(range(1, 10))));
`
```

--------------------------------

### assertThat Function Definition

Source: https://github.com/hamcrest/hamcrest-php/blob/master/generator/parts/functions_header.txt

The global assertThat function acts as a wrapper for Hamcrest\MatcherAssert::assertThat. It checks if the function exists before definition to avoid collisions.

```php
if (!function_exists('assertThat')) {
    /**
     * Make an assertion and throw {@link Hamcrest_AssertionError} if it fails.
     *
     * Example:
     * <pre>
     * //With an identifier
     * assertThat("assertion identifier", $apple->flavour(), equalTo("tasty"));
     * //Without an identifier
     * assertThat($apple->flavour(), equalTo("tasty"));
     * //Evaluating a boolean expression
     * assertThat("some error", $a > $b);
     * </pre>
     */
    function assertThat(): void
    {
        $args = func_get_args();
        call_user_func_array(
            array('Hamcrest\MatcherAssert', 'assertThat'),
            $args
        );
    }
}
```

--------------------------------

### Assert Object String Representation

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify the return value of an object's __toString() method.

```php
assertThat($anObject, hasToString('foo'));
```

--------------------------------

### Matching patterns with Hamcrest_Text_MatchesPattern

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Use this matcher to validate strings against regular expressions using preg_match().

```php
assertThat('foobar', matchesPattern('/o+b/'));
```

--------------------------------

### Assert PHP Types

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify the type of a variable using gettype(). Note that float values return 'double'.

```php
assertThat($count, typeOf('integer'));
assertThat(3.14159, typeOf('double'));
assertThat(array('foo', 'bar'), typeOf('array'));
assertThat(new stdClass(), typeOf('object'));
```

--------------------------------

### Assert String Content Ignoring Case

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Use these matchers to perform case-insensitive string comparisons.

```php
assertThat('fOObAr', containsStringIgnoringCase('oba'));
assertThat('fOObAr', containsString('oba')->ignoringCase());
```

--------------------------------

### XML Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matcher for verifying XML structure using XPath.

```php
$xml = <<<XML
<books>
  <book>
    <isbn>1</isbn>   
  </book>
  <book>
    <isbn>2</isbn>   
  </book>
</books>
XML;

$doc = new DOMDocument;
$doc->loadXML($xml);
assertThat($doc, hasXPath("book", 2));
```

--------------------------------

### Core Logical Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for combining other matchers using logical operators.

```php
assertThat([2,4,6], allOf(hasValue(2), arrayWithSize(3)));
```

```php
assertThat([2, 4, 6], anyOf(hasValue(8), hasValue(2)));
```

```php
assertThat([2, 4, 6], noneOf(hasValue(1), hasValue(3)));
```

```php
assertThat([2, 4, 6], both(hasValue(2))->andAlso(hasValue(4)));
```

```php
assertThat([2, 4, 6], either(hasValue(2))->orElse(hasValue(4)));
```

```php
$expected = "Dog";
$found = null;
// this assertion would result error message as Expected: is not null but: was null
//assertThat("Expected {$expected}, got {$found}", $found, is(notNullValue()));
// and this assertion would result error message as Expected: Dog but: was null
//assertThat($found, describedAs($expected, notNullValue()));
```

```php
assertThat([2, 4, 6], everyItem(notNullValue()));
```

```php
assertThat([2, 4, 6], hasItem(equalTo(2)));
```

```php
assertThat([1, 3, 5], hasItems(equalTo(1), equalTo(3)));
```

--------------------------------

### Assert Traversable Collections

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify properties of traversable objects like iterators.

```php
assertThat($iterator, emptyTraversable());
assertThat($iterator, traversableWithSize(5));
```

--------------------------------

### Numeric Comparison Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for comparing numeric values and ranges.

```php
assertThat(3, closeTo(3, 0.5));
```

```php
assertThat(2, comparesEqualTo(2));
```

```php
assertThat(2, greaterThan(1));
```

```php
assertThat(2, greaterThanOrEqualTo(2));
```

```php
assertThat(3, atLeast(2));
```

```php
assertThat(2, lessThan(3));
```

```php
assertThat(2, lessThanOrEqualTo(3));
```

```php
assertThat(2, atMost(3));
```

--------------------------------

### Test Case Integration

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Prevent tests from being marked as risky by manually updating the assertion count in tearDown.

```php
$this->addToAssertionCount(\Hamcrest\MatcherAssert::getCount());
\Hamcrest\MatcherAssert::resetCount();
```

--------------------------------

### Type-checking Matchers

Source: https://github.com/hamcrest/hamcrest-php/blob/master/README.md

Matchers for verifying the data type of a given value.

```php
assertThat([], arrayValue());
```

```php
assertThat(true, booleanValue());
```

```php
$func = function () {};
assertThat($func, callableValue());
```

```php
assertThat(3.14, doubleValue());
```

```php
assertThat(3.14, floatValue());
```

```php
assertThat(1, integerValue());
```

```php
assertThat("123", numericValue());
```

```php
$obj = new stdClass;
assertThat($obj, objectValue());
```

```php
assertThat($obj, anObject());
```

```php
$fp = fopen("/tmp/foo", "w+");
assertThat($fp, resourceValue());
```

```php
assertThat(1, scalarValue());
```

```php
assertThat("", stringValue());
```

--------------------------------

### Asserting callables with Hamcrest_Type_IsCallable

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Use these assertions to verify that various structures satisfy the is_callable() condition.

```php
assertThat('preg_match', callable());
assertThat(array('SomeClass', 'SomeMethod'), callable());
assertThat(array($object, 'SomeMethod'), callable());
assertThat($object, callable());
assertThat(function ($x, $y) { return $x + $y; }, callable());
```

--------------------------------

### Assert Numeric Values

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify if a value is numeric, including strings formatted as numbers.

```php
assertThat(5, numericValue());
assertThat('-5e+3', numericValue());
```

--------------------------------

### assertThat

Source: https://github.com/hamcrest/hamcrest-php/blob/master/generator/parts/functions_header.txt

The assertThat function makes an assertion and throws a Hamcrest_AssertionError if the condition fails. It supports optional identifiers, matcher objects, and boolean expressions.

```APIDOC
## assertThat

### Description
Make an assertion and throw Hamcrest_AssertionError if it fails.

### Signature
`assertThat([string $identifier], mixed $actual, [Matcher $matcher])`

### Parameters
- **identifier** (string) - Optional - A description of the assertion that will be included in the error message if the assertion fails.
- **actual** (mixed) - Required - The value to be tested or a boolean expression.
- **matcher** (Matcher) - Optional - The matcher to apply to the actual value.

### Usage Examples
```php
// With an identifier
assertThat("assertion identifier", $apple->flavour(), equalTo("tasty"));

// Without an identifier
assertThat($apple->flavour(), equalTo("tasty"));

// Evaluating a boolean expression
assertThat("some error", $a > $b);
```
```

--------------------------------

### Assert Scalar Values

Source: https://github.com/hamcrest/hamcrest-php/blob/master/CHANGES.txt

Verify that a value is a scalar type (bool, int, float, double, or string).

```php
assertThat($count, scalarValue());
assertThat('foo', scalarValue());
```
Tokens:
Raw