Testing TruCMS Core and Plugins with Pest

TruCMS uses Pest. Tests run against an SQLite database with every external service switched off, so they are fast and need no built front end or network. This page covers the setup, the helpers, and how to test a plugin the way the bundled modules are tested.

Running tests

php artisan test --compact                                   # everything
php artisan test --compact tests/Feature/ResponseCacheTest.php
php artisan test --compact Modules/Testimonials              # one plugin
php artisan test --compact --filter="stores the testimonials settings"
vendor/bin/pest --filter=TestimonialsTest                    # the runner directly

Run the narrowest set that covers your change while you work, then the plugin's whole folder before you ship.

The test environment

tests/TestCase.php also marks the app as installed, creates the Booking roles the suite expects, calls withoutVite() (views render without a build) and Http::preventStrayRequests() (any real HTTP call fails the test; fake it with Http::fake()).

Testing a plugin

tests/Pest.php binds the base TestCase and RefreshDatabase to the core test folders and to each bundled module's tests/Feature and tests/Unit. Your plugin is not on that list, so opt in at the top of each test file:

Modules/Testimonials/tests/Feature/TestimonialsTest.php

<?php

declare(strict_types=1);

use Illuminate\Foundation\Testing\RefreshDatabase;
use Modules\Testimonials\Models\Testimonial;
use Tests\TestCase;

uses(TestCase::class, RefreshDatabase::class);

it('hides the admin screens from users without the permission', function (): void {
    $this->actingAs(regularUser())
        ->get(route('admin.testimonials.index'))
        ->assertForbidden();
});

it('lists testimonials for a user who may manage them', function (): void {
    Testimonial::factory()->create(['author_name' => 'Ada Lovelace']);

    $this->actingAs(userWithPermissions(['manage testimonials']))
        ->get(route('admin.testimonials.index'))
        ->assertOk()
        ->assertSee('Ada Lovelace');
});

• The plugin must be enabled (modules_statuses.json) for its provider, routes and migrations to load. RefreshDatabase then runs its migrations with the core's.
• Add the PSR-4 test namespace (Modules\\Testimonials\\Tests\\ → tests/) under autoload-dev in the plugin's composer.json, then composer dump-autoload.
• The complete sample plugin's tests are in the tutorial.

Helpers from tests/Pest.php

Prefer userWithPermissions() over superAdmin(): a super admin passes every check, so a test with one never notices a missing ->can().

Patterns that work well

Authorisation on every route

it('protects every testimonials admin route', function (string $name): void {
    $route = pluginRoute($name);

    expect(collect($route->gatherMiddleware())->contains(
        fn ($middleware) => str_starts_with((string) $middleware, 'can:')
    ))->toBeTrue();
})->with(['admin.testimonials.index', 'admin.testimonials.store', 'admin.testimonials.destroy']);

Registries are per request

The sidebar, settings and dashboard registries are singletons that are filled during a request. Assert on what a request renders (assertSee() on the dashboard or the sidebar), not on the registry after the request, and use nextVisitor() between two users in one test.

Shortcodes and page content

use Illuminate\Support\Facades\Blade;

it('renders the testimonials block', function (): void {
    Testimonial::factory()->create(['author_name' => 'Grace Hopper']);

    $html = Blade::render('<x-shortcode-testimonials></x-shortcode-testimonials>');

    expect($html)->toContain('Grace Hopper');
});

That is exactly how a saved page renders the tag, so the test covers the real path.

Files, mail and outside services

• Fake storage with Storage::fake('public') before anything that writes media, including seeders.
• Fake mail and notifications with Mail::fake() and Notification::fake().
• Fake external APIs with Http::fake([...]); unfaked calls fail by design.

Style and static analysis