README

Testing utilities for Marko---reusable fakes with built-in assertions, and an in-process HTTP test client for feature tests.

Overview

marko/testing provides a set of in-memory fakes that replace real infrastructure dependencies during tests. Instead of mocking interfaces by hand or spinning up real services, you drop in a fake, run your code, and call assertion methods directly on the fake. This removes hundreds of lines of boilerplate and keeps tests focused on behavior.

Installation

composer require marko/testing --dev

Pest Base Test Case

TestCase registers PSR-4 autoloaders for app/* and modules/* before tests run, so module classes resolve without per-project Composer classmap configuration. No container or application boot is performed.

Wire it as the global base in tests/Pest.php:

use Marko\Testing\TestCase;

uses(TestCase::class)->in(__DIR__);

After that, every Pest test in the project can reference module and app classes directly---no additional Composer path repos or classmaps required.

HTTP Tests

TestClient sends requests through your application in process (real router, middleware and controllers) and boots the application once for many requests:

use Marko\Testing\Http\TestClient;

$client = TestClient::boot(dirname(__DIR__));

$client->postJson('/api/shows/42/events', ['type' => 'view'])
    ->assertStatus(202)
    ->assertJsonPath('data.type', 'view');

$client->actingAs($user)->get('/dashboard')->assertOk();

Cookies persist across requests like a browser's, so session-backed flows work. Assertions on the returned TestResponse throw AssertionFailedException with the status and a body excerpt. See the HTTP tests docs.

Database Tests

With marko/database and a driver installed, TestDatabase boots and migrates your application once per process, and RefreshDatabase wraps each test in a transaction that is rolled back afterwards:

use Marko\Testing\Database\RefreshDatabase;
use Marko\Testing\Database\TestDatabase;

beforeEach(function () {
    $this->database = TestDatabase::boot(dirname(__DIR__));
    $this->refresh = new RefreshDatabase($this->database);
    $this->refresh->begin();
    $this->http = $this->database->client(); // shares the test transaction
});

afterEach(fn () => $this->refresh->rollback());

TruncateDatabase empties the entity tables instead, for code that must see committed data. Both refuse to run in production, and TruncateDatabase runs only in a testing environment (testing, test); set APP_ENV=testing. See the database tests docs.

Available Fakes

FakeEventDispatcher, FakeBroadcaster, FakeMailer, FakeQueue, FakeSession, FakeCookieJar, FakeLogger, FakeConfigRepository, FakeAuthenticatable, FakeUserProvider, FakeGuard, FakeHttpClient, FakeEncryptor, FakeClock, FakeSleeper, FakeConfirmationPrompter

Usage

FakeEventDispatcher

use Marko\Testing\Fake\FakeEventDispatcher;

$dispatcher = new FakeEventDispatcher();
$dispatcher->dispatch(new OrderPlaced($order));

$dispatcher->assertDispatched(OrderPlaced::class);
$dispatcher->assertDispatchedCount(OrderPlaced::class, 1);
$dispatcher->assertNotDispatched(OrderShipped::class);

FakeMailer

use Marko\Testing\Fake\FakeMailer;

$mailer = new FakeMailer();
$mailer->send($message);

$mailer->assertSent(WelcomeEmail::class);
$mailer->assertSentCount(WelcomeEmail::class, 1);
$mailer->assertNothingSent();

FakeQueue

use Marko\Testing\Fake\FakeQueue;

$queue = new FakeQueue();
$queue->push(new ProcessOrder($order));

$queue->assertPushed(ProcessOrder::class);
$queue->assertPushedCount(ProcessOrder::class, 1);
$queue->assertNotPushed(SendInvoice::class);
$queue->assertNothingPushed();

FakeSession

use Marko\Testing\Fake\FakeSession;

$session = new FakeSession();
$session->put('user_id', 42);

$value = $session->get('user_id'); // 42
$session->forget('user_id');

FakeCookieJar

use Marko\Testing\Fake\FakeCookieJar;

$cookies = new FakeCookieJar();
$cookies->set('token', 'abc123');

$value = $cookies->get('token'); // 'abc123'

FakeLogger

use Marko\Testing\Fake\FakeLogger;

$logger = new FakeLogger();
$logger->info('User logged in');
$logger->error('Something failed');

$logger->assertLogged('User logged in');
$logger->assertNothingLogged();

FakeConfigRepository

use Marko\Testing\Fake\FakeConfigRepository;

$config = new FakeConfigRepository([
    'auth.defaults.guard' => 'web',
    'app.name' => 'Marko',
]);

$value = $config->get('auth.defaults.guard'); // 'web'

FakeAuthenticatable

use Marko\Testing\Fake\FakeAuthenticatable;

$user = new FakeAuthenticatable(id: 1, password: 'hashed-secret');

$user->getAuthIdentifier(); // 1
$user->getAuthPassword();   // 'hashed-secret'

FakeUserProvider

use Marko\Testing\Fake\FakeUserProvider;
use Marko\Testing\Fake\FakeAuthenticatable;

$user = new FakeAuthenticatable(id: 1);
$provider = new FakeUserProvider($user);

$found = $provider->retrieveById(1); // returns $user

FakeGuard

use Marko\Testing\Fake\FakeGuard;
use Marko\Testing\Fake\FakeAuthenticatable;

$guard = new FakeGuard(name: 'web', attemptResult: true);

// Set a user directly
$user = new FakeAuthenticatable(id: 1);
$guard->setUser($user);
$guard->assertAuthenticated();

// Test login attempt
$guard->attempt(['email' => 'user@example.com', 'password' => 'secret']);
$guard->assertAttempted();

// Assert no user logged in
$guard->logout();
$guard->assertGuest();
$guard->assertLoggedOut();

FakeHttpClient

use Marko\Http\HttpResponse;
use Marko\Testing\Fake\FakeHttpClient;
use Marko\Testing\Fake\Http\RecordedRequest;

$http = new FakeHttpClient();
$http->stub('https://api.example.com/orders/*', new HttpResponse(200, '{"id":1}'));

$service = new OrderSync($http);
$service->push($order);

$http->assertSent(fn (RecordedRequest $r) => $r->method === 'POST');
$http->assertSentCount(1);

FakeEncryptor

use Marko\Testing\Fake\FakeEncryptor;

$encryptor = new FakeEncryptor();
$encrypted = $encryptor->encrypt('123-45-6789', 'users.ssn');

$encryptor->decrypt($encrypted, 'users.ssn');   // '123-45-6789'
$encryptor->decrypt($encrypted, 'users.email'); // throws DecryptionException: AAD mismatch

$encryptor->assertEncrypted('123-45-6789', 'users.ssn');
$encryptor->assertDecrypted(aad: 'users.ssn');

KnownDriversValidator

use Marko\Testing\KnownDrivers\KnownDriversValidator;

KnownDriversValidator::assertDocsUrlsResolveToValidPattern(
    __DIR__ . '/../known-drivers.php',
);

KnownDriversValidator::assertSkeletonSuggestContainsAll(
    __DIR__ . '/../known-drivers.php',
    __DIR__ . '/../../skeleton/composer.json',
);

API Reference

TestCase

setUp(): void — Calls registerModuleAutoloaders() before each test
registerModuleAutoloaders(): void — Registers PSR-4 autoloaders for app/* and modules/*; safe to call multiple times (skips already-registered roots)
projectRoot(): string — Walks up the directory tree from cwd to find the nearest ancestor containing vendor/

FakeEventDispatcher

dispatch($event): void — Record a dispatched event
dispatched(string $class): array — Return all dispatched events of a class
assertDispatched(string $class): void — Assert an event was dispatched
assertNotDispatched(string $class): void — Assert an event was not dispatched
assertDispatchedCount(string $class, int $count): void — Assert exact dispatch count

FakeMailer

send($message): void — Record a sent message
assertSent(string $class): void — Assert a message was sent
assertNothingSent(): void — Assert no messages were sent
assertSentCount(string $class, int $count): void — Assert exact sent count

FakeQueue

push($job): void — Record a pushed job
assertPushed(string $class): void — Assert a job was pushed
assertNotPushed(string $class): void — Assert a job was not pushed
assertPushedCount(string $class, int $count): void — Assert exact pushed count
assertNothingPushed(): void — Assert no jobs were pushed

FakeLogger

info(string $message): void, error(), warning(), etc. — Record log entries
assertLogged(string $message): void — Assert a message was logged
assertNothingLogged(): void — Assert nothing was logged

FakeGuard

new FakeGuard(string $name, bool $attemptResult) — Create guard; $attemptResult controls what attempt() returns
setUser(?AuthenticatableInterface $user): void — Set the current authenticated user
attempt(array $credentials): bool — Record credentials attempt and return configured result
login(AuthenticatableInterface $user): void — Log in a user directly
logout(): void — Clear current user and record logout
assertAuthenticated(): void — Assert a user is currently authenticated
assertGuest(): void — Assert no user is authenticated
assertAttempted(?callable $callback = null): void — Assert attempt() was called, optionally matching credentials via callback
assertNotAttempted(): void — Assert attempt() was never called
assertLoggedOut(): void — Assert logout() was called

FakeHttpClient

stub(string $urlPattern, HttpResponse|HttpException $response): self — Respond to matching URLs (* wildcard)
queue(HttpResponse|HttpException ...$responses): self — Sequential responses for unmatched URLs
preventStrayRequests(bool $prevent = true): self — Throw on unmatched requests (default on)
assertSent(?callable $callback = null): void, assertNotSent(callable $callback): void, assertSentCount(int $expected): void, assertNothingSent(): void

TestClient

TestClient::boot(string $basePath): self, TestClient::forApplication(Application $app): self — Boot once, serve many requests
get(), post(), put(), patch(), delete(), options(), head(), getJson(), postJson(), putJson(), patchJson(), deleteJson(), call() — Send a request, return a TestResponse
withHeaders(), withServerVariables(), withCookie(), withoutCookies(), withFile(), withFiles(), actingAs($user, ?string $guard = null) — Client state for later requests
cookies(), cookieJar() — The cookie jar, scoped by path, domain, Secure, expiry and SameSite like a browser
withoutResetting(ResettableInterface ...$services): static — Services the client must not reset between requests

TestDatabase, RefreshDatabase, TruncateDatabase

TestDatabase::boot(string $basePath, bool $fresh = false): self — Boot and migrate once per process; refuses production, and fresh: true runs only in a testing environment
application(), connection(), transaction(), client(), seedTable(), getTableRowCount(), appliedMigrations()
new RefreshDatabase(TestDatabase $database) — begin(), rollback(), runAfterCommitCallbacks()
new TruncateDatabase(TestDatabase $database) — truncate(), tables()

TestResponse

assertStatus(), assertOk(), assertCreated(), assertNoContent(), assertNotFound(), assertForbidden(), assertUnauthorized(), assertUnprocessable(), assertRedirect(?string $to = null)
assertHeader(), assertHeaderMissing(), assertCookie(), assertCookieMissing(), assertSee(), assertDontSee()
assertJson(), assertExactJson(), assertJsonPath(), assertJsonCount(), assertJsonMissingPath()
status(), body(), header(), json(), response()

KnownDriversValidator

assertDocsUrlsResolveToValidPattern(string $knownDriversPath): void — Assert every key in known-drivers.php follows the marko/* prefix pattern
assertSkeletonSuggestContainsAll(string $knownDriversPath, string $skeletonComposerPath): void — Assert the skeleton's suggest block contains every entry from known-drivers.php with matching descriptions

Pest Expectations

marko/testing ships Pest custom expectations. They register automatically through a Pest plugin (extra.pest.plugins), so Pest.php needs no require. Pest 4 is required for the expectations; the fakes and their assert*() methods work without it.

use Marko\Testing\Fake\FakeEventDispatcher;
use Marko\Testing\Fake\FakeGuard;
use Marko\Testing\Fake\FakeMailer;
use Marko\Testing\Fake\FakeQueue;
use Marko\Testing\Fake\FakeLogger;

// FakeEventDispatcher
expect($dispatcher)->toHaveDispatched(OrderPlaced::class);

// FakeMailer
expect($mailer)->toHaveSent();
expect($mailer)->toHaveSent(fn ($msg) => $msg instanceof WelcomeEmail);

// FakeQueue
expect($queue)->toHavePushed(ProcessOrder::class);

// FakeLogger
expect($logger)->toHaveLogged('User logged in');

// FakeGuard
expect($guard)->toHaveAttempted();
expect($guard)->toHaveAttempted(fn ($creds) => $creds['email'] === 'user@example.com');
expect($guard)->toBeAuthenticated();

// FakeHttpClient
expect($http)->toHaveSentRequest(fn ($request) => $request->method === 'POST');

// TestResponse
expect($response)->toHaveStatus(201);
expect($response)->toHaveJsonPath('data.status', 'live');

Documentation

Full usage, API reference, and examples: marko/testing

marko / testing

Package info

Security

Statistics

README

Overview

Installation

Pest Base Test Case

HTTP Tests

Database Tests

Available Fakes

Usage

FakeEventDispatcher

FakeMailer

FakeQueue

FakeSession

FakeCookieJar

FakeLogger

FakeConfigRepository

FakeAuthenticatable

FakeUserProvider

FakeGuard

FakeHttpClient

FakeEncryptor

KnownDriversValidator

API Reference

TestCase

FakeEventDispatcher

FakeMailer

FakeQueue

FakeLogger

FakeGuard

FakeHttpClient

TestClient

TestDatabase, RefreshDatabase, TruncateDatabase

TestResponse

KnownDriversValidator

Pest Expectations

Documentation