Fluent Assertions for PHP provides a human readable syntax for your unit test assertions.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.skylift
.vscode
src
test
.gitignore
.travis.yml
LICENSE
README.md
Vagrantfile
phpunit-4.8.24.phar
proofofconcept.php
vagrant.sh

README.md

Fluent Assertions for PHP

Build Status

Fluent Assertions for PHP is an unofficial port of the Fluent Assertions for .NET library.

It extends PHPUnit's base test class providing a very readable syntax for your unit tests that should make them easier to understand.

It also provides many powerful pre-written assertions allowing you to easily check that a result is exactly what it is expected be, including checking class inheritance, interface implementations, array searching and more.

Examples

$this->assert($object->stringProperty)->should()->be("string");
$this->assert("string")->should()->contain("str");
$this->assert($array)->should()->haveItemCount(10);
$this->assert($array)->should()->containItem("fourth item");

$this->assert($object)->should()->notBeNull();

$this->assert($object->doWork())->should()->throwException("MyException");
$this->assert($object->doWork())->should()->throwError("PHP_Error_Type");

$this->assert($class)->should()->implement("MyClass");
$this->assert($class)->should()->extend("MyClass");

Version Support

Currently Fluent Assertions for PHP only supports PHPUnit.

PHP : 5.3.x to latest

PHPUnit : 4.8 to latest

Reference

Getting Started

  • Include FluentAssertionsTestCase.php (or get from composer? TODO)
  • Set your test classes to inherit from FluentAssertionsTestCase instead of PHPUnit_Framework_TestCase

Generic

The basic usage of this library is as follows:

$this->assert(1)->should()->be(1, "1 and 1 are the same!");

Here we call assert() on the FluentAssertions base class, passing in a result (1) that we want to check.

Then we call the function should(), which is simply syntatic sugar to make the code read nicely.

Finally, we call one of the many assertions available as part of this library (see below for a full list) passing in our expected result (1) and an optional reason for the assertion.


All types and variables support two main assertions:

be($expected) Assert that a variable is the same as another variable

notBe($expected) Assert that a variable is not the same as another variable

Reasons

All assertions take an optional "reason" parameter at the end allowing you to specify a reason for the assertion. To read fluidly on the test output, the provided reason should start with "because".

(An example output: "Expected false to be true because result is same type as expected")

Strings

When your result is a string, there are some special assertions that you can perform:

contain($searchValue) Assert that a string contains another string

notContain($searchValue) Assert a string does not contain another string

startWith($searchValue) Assert a string starts with another string

notStartWith($searchValue) Assert a string does not start with another string

endWith($searchValue) Assert a string ends with another string

notEndWith($searchValue) Assert a string does not end with another string

haveLength($count) Assert a string has a certain number of characters

notHaveLength($count) Assert a string's length is not the specified number of characters

Booleans

When your result is a bool, there are some special assertions that you can perform:

beTrue() Assert that a boolean is true

notBeTrue() Assert that a boolean is not true

beFalse() Assert that a boolean is false

notBeFalse() Assert that a boolean is not false

Type Checking

To check the type of the result variable, you can use one of the following assertions:

beBool()

beInt()

beFloat()

beString()

beArray()

beNull()

beResource()

beCallable()

beObject() Note: In PHP, only instances of classes are objects.

All of the above also have an opposite notBe<type> assertion as well.

Arrays

When your result is an array, there are some special assertions that you can perform:

haveCount($count) Assert that an array has a specified number of elements

notHaveCount($count) Assert that an array does not have a specified number of elements

containItem($item) Assert that an array contains a specified item

notContainItem($item) Assert that an array does not contain a specified item

Example usage:

$this->assert($myArray)->should()->containItem("Array item");
$this->assert($myArray[0])->should()->be("First item!");
$this->assert($myArray)->should()->haveCount(4);

Classes

When your result is a class instance, there are some special assertions that you can perform:

beInstanceOf($className) Assert that a class instance is of the type specified

implement($interfaceName) Assert that a class instance implements a given interface name

extend($className) Assert that a class instance extends a given class name

beSameAs($classInstance) Assert that a class instance is the same object in memory (same reference pointer)

All of the above also have an opposite notBe<assertion> as well.

Example usage:

$this->assert($myClassInstance)->should()->implement("IFirstInterface");
$this->assert($myClassInstance)->should()->extend("SubClassName");
$this->assert($myClassInstance)->should()->beSameAs($myClassInstance);
$this->assert($myClassInstance)->should()->notBeSameAs($myIdenticalClassInstance);

Exceptions

If you pass in a function call as the result, you can assert that an Exception is thrown:

throwException($exceptionName)

Example usage:

$this->assert($myClass->doWork())->should()->throwException("InvalidArgumentException");

PHP Errors

If you pass in a function call as the result, you can assert that a PHP Error, Warning or Notice is thrown:

throwError()

throwWarning()

throwNotice()

Example usage:

$this->assert($myClass->doWork())->should()->throwError();
$this->assert($myClass->doWork())->should()->throwWarning();

TODO LIST

Generic

  • be()
  • notBe()

Booleans

  • beTrue()
  • notBeTrue()
  • beFalse()
  • notBeFalse()

Types

  • beBool()
  • notBeBool()
  • beInt()
  • notBeInt()
  • beFloat()
  • notBeFloat()
  • beString()
  • notBeString()
  • beArray()
  • notBeArray()
  • beNull()
  • notBeNull()
  • beResource()
  • notBeResource()
  • beCallable()
  • notBeCallable()
  • beObject()
  • notBeObject()

Strings

  • contain()
  • notContain()
  • startWith()
  • notStartWith()
  • endWith()
  • notEndWith()
  • haveLength()
  • notHaveLength()

Integers

  • beGreaterThan()
  • beLessThan()
  • beGreaterThanOrEqualTo()
  • beLessThanOrEqualTo()
  • beInRange()
  • bePositive()
  • beNegative()

Arrays

  • haveCount()
  • notHaveCount()
  • containItem()
  • notContainItem()
  • More complex search cases (one match, exactly(x) matches, etc)
  • Even more complex search cases (check item is instance of class ?)
  • startWithItem()
  • endWithItem()
  • containSingleItem()
  • beEmpty()
  • beNullOrEmpty()

Classes

  • beInstanceOf()
  • notBeInstanceOf()
  • implement()
  • notImplement()
  • extend()
  • notExtend()
  • beSameAs() -- Exact same object in memory (pointer to same object)
  • notBeSameAs()

Exceptions

  • throwException() -- $this->setExpectedException("InvalidArgumentException");
  • notThrowException()

PHP Errors

Other

  • Get custom reason working (build up reason from inputs)
  • Drop support for PHP 5.3 to allow using traits to clean up the main FluentAssertions class
  • Get autoloader working (composer) to allow easy use