Download the PHP package marko/testing without Composer

marko/testing

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

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:

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:

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:

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

FakeMailer

FakeQueue

FakeSession

FakeCookieJar

FakeLogger

FakeConfigRepository

FakeAuthenticatable

FakeUserProvider

FakeGuard

FakeHttpClient

FakeEncryptor

KnownDriversValidator

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.

Documentation

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