README

This repository contains an old version of PEST. A new and better version is being coded in private and will be out soon! Better be ready.

Pest was carefully crafted to bring the joy of testing with JEST to PHP. It was created by Nuno Maduro, and currently decorated by Caneco.

🚀 Installation & Usage

Requires PHP 7.2+ and phpunit 8.1+

First, Install Pest using Composer:

composer require nunomaduro/pest --dev

Then, create a file named tests/sum.php. This will contain our actual test:

test('adds 1 + 2 to equal 3', function () {
    assertEquals(3, Math::sum(1,2));
});

Then, as usual, if you don't have it yet, create your phpunit.xml.dist.

Finally, run vendor/bin/pest and pest will print this message:

PASS  ./sum.php
✓ adds 1 + 2 to equal 3 (5ms)

📚 Documentation

Pest aims to work out of the box, config free, on most PHP/PHPUnit projects.

Our goal is create a delightful PHP Testing Framework with a focus on simplicity - with ideas coming from a line between PHPUnit and Jest.

Writing tests

All you need in a test file is the test or it method which runs a test. For example, let's say there's a function inchesOfRain() that should be 0. Your whole test could be:

test('did not rain', function () {
    assertEquals(0, Weather::inchesOfRain());
});

// Or, also under the alias `it`
it('did not rain', function () {
    assertEquals(0, Weather::inchesOfRain());
});

Using Assertions

Pest uses "assertions" to let you test values in different ways.

it('has something', (function () {
    assertTrue(true);
    assertFalse(false);
    assertCount(1, ['foo']);
    assertEmpty([]);
    assertEquals('bar', 'bar');
    assertStringContainsString('bar', 'foobarbaz');
    // ...
});

For the full list, see the Assertions documentation from PHPUnit.

Setup and Teardown

Often while writing tests you have some setup work that needs to happen before tests run, and you have some finishing work that needs to happen after tests run. Pest provides helper functions to handle this.

// Runs before each test on this file
beforeEach(function () {
    Database::migrate();
});

// Runs after each test on this file
afterEach(function () {
    Database::delete();
});

test('city database has Vienna', function () {
    assertTrue(City::exists('Vienna'));
});

test('city database has San Juan', function () {
    assertTrue(City::exists('San Juan'));
});

One-Time Setup

In some cases, you only need to do setup once, at the beginning of a file. This can be especially bothersome when the setup is asynchronous, so you can't just do it inline. Pest provides beforeAll and afterAll to handle this situation.

// Runs before the first test of the file
beforeAll(function () {
    Database::migrate();
});

// Runs after the last test of the file
afterAll(function () {
    Database::delete();
});

test('city database has Vienna', function () {
    assertTrue(City::exists('Vienna'));
});

test('city database has San Juan', function () {
    assertTrue(City::exists('San Juan'));
});

This may help to illustrate the order of execution:

beforeAll(function () { echo 'beforeAll'); };
afterAll(function () { echo 'afterAll'); };
beforeEach(function () { echo 'beforeEach'); };
afterEach(function () { echo 'afterEach'); };
test('', function () { echo 'test 1'); };
test('', function () { echo 'test 2'); };
// beforeAll
// beforeEach
// test 1
// afterEach
// beforeEach
// test 2
// afterEach
// afterAll

Mocks

The given closure to the test|it method is bound to a typical PHPUnit\Framework\TestCase. For mocks, you can optionally create a mock using the $this->createMock method.

interface Foo
{
    public function bar(): int;
}

it('works fine with mocks', function () {
    $mock = $this->createMock(Foo::class);

    $mock->expects($this->once())->method('bar')->willReturn(2);

    assertEquals(2, $mock->bar());
});

Migrating to Pest from PHPUnit

No migration is needed. It just works.

Configuration

Pest uses your base phpunit.xml configuration file.

💖 Support the development

Do you like this project? Support it by donating

PayPal: Donate
Patreon: Donate

Pest is open-sourced software licensed under the MIT license.

nunomaduro / pest

Maintainers

Details