Chief Testing

Reusable test utilities to validate a Laravel project's Chief setup.

What it tests

• All registered Chief resources and fragments.
• Two test modes:
  • generated: create/update/delete flows where possible.
  • existing: read-only checks on existing database records.
• Unsupported scenarios are skipped with a clear reason.

Install

In your Laravel project:

composer require --dev thinktomorrow/chief-testing

When working locally from a path repository, add this in your project's composer.json first:

{
  "repositories": [
    {
      "type": "path",
      "url": "../../packages/chief-testing",
      "options": { "symlink": true }
    }
  ]
}

Then install:

composer require --dev thinktomorrow/chief-testing:dev-main

Usage in a project

Run the installer command in your project:

php artisan chief-testing:install

This generates:

• tests/Feature/Chief/ChiefResourceSetupTest.php
• tests/Feature/Chief/ChiefFragmentSetupTest.php

Available options:

php artisan chief-testing:install --force
php artisan chief-testing:install --path=tests/Feature/Chief --namespace="Tests\\Feature\\Chief"

If you prefer, you can also create the two test files manually.

tests/Feature/Chief/ChiefResourceSetupTest.php:

<?php

declare(strict_types=1);

namespace Tests\Feature\Chief;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\CreatesApplication;
use Thinktomorrow\Chief\Testing\Feature\ChiefResourceSetupTestCase;

final class ChiefResourceSetupTest extends ChiefResourceSetupTestCase
{
    use CreatesApplication;
    use RefreshDatabase;

    protected function authenticateChiefAdmin(): void
    {
        // Optional: login a chief admin user when routes are protected.
        // Example:
        // $admin = \App\Models\User::factory()->create();
        // $this->actingAs($admin, 'chief');
    }
}

tests/Feature/Chief/ChiefFragmentSetupTest.php:

<?php

declare(strict_types=1);

namespace Tests\Feature\Chief;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\CreatesApplication;
use Thinktomorrow\Chief\Testing\Feature\ChiefFragmentSetupTestCase;

final class ChiefFragmentSetupTest extends ChiefFragmentSetupTestCase
{
    use CreatesApplication;
    use RefreshDatabase;

    protected function authenticateChiefAdmin(): void
    {
        // Optional: login a chief admin user when routes are protected.
    }
}

Run tests

Run both suites:

php artisan test --compact tests/Feature/Chief

Run only resources:

php artisan test --compact tests/Feature/Chief/ChiefResourceSetupTest.php

Run only fragments:

php artisan test --compact tests/Feature/Chief/ChiefFragmentSetupTest.php

Modes and configuration

Environment variables:

• CHIEF_TEST_MODE=generated|existing
• CHIEF_EXISTING_DB_CONNECTION=<connection-name>
• CHIEF_EXISTING_LIMIT_PER_RESOURCE=5
• CHIEF_EXISTING_LIMIT_PER_FRAGMENT=10

Database connection resolution in existing mode:

1. CHIEF_EXISTING_DB_CONNECTION
2. DB_CONNECTION from .env.testing
3. DB_CONNECTION from .env

Run read-only checks on real existing data:

CHIEF_TEST_MODE=existing php artisan test --compact tests/Feature/Chief

Notes

• Existing mode enforces a read-only SQL guard and blocks write queries.
• Generated mode uses available factories/setup and skips unsupported resources/fragments with reason.
• Base test cases provided by this package:
  • Thinktomorrow\Chief\Testing\Feature\ChiefResourceSetupTestCase
  • Thinktomorrow\Chief\Testing\Feature\ChiefFragmentSetupTestCase