Download the PHP package sirbrillig/corretto without Composer

Corretto

Corretto is a simple and expressive PHP test runner.

Modeled after mocha, Corretto provides a DSL (domain-specific language) that makes writing tests easy. No need for classes and long function names; just say what your code does in plain words. After all, wouldn't you rather spend most of your time working on code rather than writing tests?

Installing

First you'll need Composer. Then, in your project:

Or, to install globally:

Just make sure your global vendor binaries directory is in your $PATH. See the docs on global installs for more info.

Assertions

Corretto has built-in support for basic assertions:

• assertTrue()
• assertFalse()
• assertEquals()
• assertNotEquals()

It also supports expect syntax, which is recommended:

• expect( $actual )->toBeTrue()
• expect( $actual )->toBeFalse()
• expect( $actual )->toEqual( $expected )
• expect( $actual )->toNotEqual( $expected )
• expect( $actual )->toBeGreaterThan( $expected )
• expect( $actual )->toBeLessThan( $expected )
• expect( $actual )->toContain( $expected )
• expect( $actual )->toNotContain( $expected )

Custom Assertions

Writing custom assertions is easy. Any function that throws an Exception counts as a test failure!

(You can also throw \Corretto\AssertionFailure which will provide slightly less noisy failures.)

To add new methods to expect(), you'll need to create a class that extends Corretto\Expectation. Within the class, add methods that test the value of $this->actual, which is the value passed to expect(). Then pass the class to the function Corretto\extendExpectation().

For example, to add the method toBeFoo(), you would write the following:

It is then possible to use this method in your tests, like this:

Tests

A test is defined by the function it( string $name, callable $callable ). This function is also aliased as test( string $name, callable $callable ) and specify( string $name, callable $callable ).

The callable should be an anonymous function that contains at least one assertion.

You can skip a test by simply omitting its callable, like this:

You can also skip a test by adding the string SKIP as its first argument:

Suites

Tests can be organized into suites using a similar syntax to tests: describe( string $name, callable $callable ). This is also aliased as suite( string $name, callable $callable ) and context( string $name, callable $callable ).

There is a default "root" suite always defined, so tests can exist by themselves.

Suites can be nested as deep as you like.

You can skip all the tests in a suite by adding the string SKIP as its first argument:

Before, After

Suites can each have a before( callable $callable ) which will be called before all the tests are run in that suite. Similarly after( callable $callable ) will be run after all the tests have completed.

There is also beforeEach( callable $callable ) and afterEach( callable $callable ) which run their callables before/after each test in the suite (or any nested suite). These can be used to set up and restore data that is shared between each test.

Passing variables to closures with the use expression in PHP is verbose, and it's likely that this pattern will be used frequently in tests. To make this easier, each test and each beforeEach/afterEach/before/after function receives a shared object that can be used to pass data between functions. Here is that same series of tests with the object used instead of closures.

Runner

The corretto command-line tool is used to execute the tests. It can be provided with a test file or a directory of test files. If no files are provided, it will default to looking for a directory called tests in the current directory.

The tool has several output options called Reporters that can be changed using the -R or --reporter options. The default Reporter is spec but there is also base, which is simpler, and dots which is more like the default output of PHPUnit.

It's possible to write a custom reporter very easily by extending Corretto\Reporters\Base. The Runner will emit events whenever something happens and a reporter can use those events as it likes.

Examples