README

A testing suite for applications built with the Machinjiri Framework.

Advocate extends PHPUnit with a framework-aware test case and helpers for exercising HTTP endpoints, checking database state, faking external effects, and working with the application container. Write familiar PHPUnit tests while keeping common Machinjiri testing tasks close at hand.

Requirements

PHP 8.4 or later
Machinjiri Framework
Composer

Installation

Add Advocate to your application as a development dependency:

composer require --dev machinjiri/advocate phpunit/phpunit:^10

The framework is a required runtime dependency of Advocate. Composer does not install a library's development dependencies for applications that depend on it, so add Mockery and/or Faker to your application as development dependencies if you use those helpers:

composer require --dev mockery/mockery:^1.5 fakerphp/faker:^1.20

Quick start

Create a test that extends Machinjiri\Advocate\TestCase:

<?php

namespace App\Tests;

use Machinjiri\Advocate\TestCase;

final class HomePageTest extends TestCase
{
    public function test_home_page_returns_successfully(): void
    {
        $response = $this->get('/');

        $this->assertResponseOk($response);
        $this->assertSeeText('Welcome', $response);
    }
}

TestCase boots the Machinjiri application for each test. It uses the current working directory as the project root, loads bootstrap/app.php when present, and otherwise creates a framework container for that root.

Run PHPUnit from your application:

vendor/bin/phpunit

Configure PHPUnit in your application as usual, including its test directory and any required bootstrap settings. In the Advocate repository itself, composer test is also available.

What you can test

HTTP requests

Issue requests through the application and assert on the returned response:

$response = $this->post('/contact', [
    'name' => 'Amina',
    'email' => 'amina@example.test',
]);

$this->assertStatus(200, $response);
$this->assertSee('Thank you', $response);

Available request helpers are get, post, put, delete, and call. They return a Machinjiri HttpResponse. Response assertions include:

assertResponseOk($response) and assertStatus($status, $response)
assertSee($text, $response) and assertSeeText($text, $response)
assertRedirect($uri, $response)
assertJsonPath($path, $expected, $response) and assertExactJson($expected, $response)

Database

Advocate provides database assertions for checking records, counts, and deletions:

$this->assertDatabaseHas('users', ['email' => 'amina@example.test']);
$this->assertDatabaseMissing('users', ['email' => 'unknown@example.test']);
$this->assertDatabaseCount('users', 1);
$this->assertDeleted(User::class, ['email' => 'removed@example.test']);

The database setup helper configures in-memory SQLite. Call setUpDatabase() from your test setup when you need that database initialized:

protected function setUp(): void
{
    parent::setUp();
    $this->setUpDatabase();
}

The test case shuts down the database during teardown. Database configuration and query behavior are provided by the Machinjiri database connection.

Container, mocks, and factories

Use the application container through app(), or bind and resolve dependencies directly:

$this->singleton(PaymentGateway::class, $gateway);
$resolved = $this->resolve(PaymentGateway::class);

bind($abstract, $concrete, $shared = false) registers a binding. mock($class, $expectations = null), spy($class), and stub($class, $methodsReturns = []) create Mockery doubles and register them in the container. Factory helpers are also available: make($model, $attributes) creates without persisting, while create($model, $attributes, $count) persists one or more instances using the model's <Model>Factory.

Authentication, session, and middleware

The test case includes helpers to act as a user and assert authentication state:

$this->actingAs($user);
$this->assertAuthenticated();

Use be($user) as an alias for actingAs($user), or check unauthenticated state with assertGuest(). Session helpers include withSession($data) and assertSessionHas($key, $value). Call withoutMiddleware() in a test to bypass middleware for that test.

Fakes and other helpers

Advocate includes helpers for console commands, queued jobs, events, mail, time, snapshots, exceptions, and coverage. Fake setup is explicit: call setUpQueueFake(), setUpEventFake(), or setUpMailFake() in the test that needs the fake, then use assertJobPushed(), assertEventDispatched(), assertMailSent(), or assertMailCount() to verify effects. Use artisan($command, $parameters) to run a console command.

Additional helpers include:

freezeTime($timestamp), travel($seconds), and unfreezeTime()
assertMatchesSnapshot($value, $snapshotName)
expectExceptionType($class), expectExceptionMessageText($message), and expectExceptionCodeValue($code)
faker() after calling setUpFaker()

These are test-case helpers, not automatic test setup. Activate optional fakes or Faker explicitly in the tests that need them.

License

Advocate is released under the MIT License.

machinjiri / advocate

Package info

Security

Statistics