Testing Kit

Testing Kit is a Laravel package that provides reusable testing infrastructure for Craftable-based projects. It supplies:

• A TestCase base (database refresh, translator mocking, dummy CSRF, snapshot helpers, download assertions, declarative actor resolution from PHP attributes)
• HttpTestCase, WebTestCase, ApiTestCase for HTTP / web / API integration tests
• Context PHP attribute for declarative customer | admin-user | anonymous setup per test method or class
• UserFactory and AdminUserFactory with the underlying model class pluggable via config (constructor-injected Hasher); AdminUserFactory also assigns the configured admin role
• HTML snapshot driver and SnapshotAsserts trait for view snapshot testing
• OpenApiValidationTrait and helper Util for asserting responses against an OpenAPI spec

This package is part of Craftable (dejwCake/craftable), an administration starter kit for Laravel.

Install

Add the path repository (or a Packagist version) and require as a dev dependency in your application:

"require-dev": {
    "dejwcake/testing-kit": "*"
}

The TestingKitServiceProvider is auto-discovered by Laravel.

Publish the config (optional) to override the user models, default emails, role name, or the OpenAPI spec path:

php artisan vendor:publish --tag=testing-kit-config

Config

config/testing-kit.php (after publishing):

Key	Default	Purpose
user_model	App\Models\User	Model class used by UserFactory
admin_user_model	Brackets\AdminAuth\Models\AdminUser	Model class used by AdminUserFactory
authenticated_user_id	123	Default id used by actingAsCustomer() / actingAsAdminUser() when none is passed
dummy_csrf_token	'csrf-token-mock'	Token put into the test session
default_locale	'en'	Locale set in createApplication()
default_user_email	'test@example.com'	Email pinned on customer fixtures
default_admin_user_email	'admin@example.com'	Email pinned on admin user fixtures
default_admin_role	'Administrator'	Role assigned to admin user fixtures via Spatie HasRoles
openapi.spec_path	storage_path('api-docs/openapi.json')	Spec file used by ApiTestCase
openapi.regenerate_command	'l5-swagger:generate'	Artisan command to regenerate the spec
openapi.regenerate_on_init	true	Whether ApiTestCase::setUp regenerates the spec

Usage

Web test (HTML snapshot + download assertion)

use DejwCake\TestingKit\Functional\WebTestCase;
use DejwCake\TestingKit\Attributes\Context;

final class InstructionsControllerTest extends WebTestCase
{
    #[Context(user: 'customer')]
    public function testCustomerCanDownloadInstruction(): void
    {
        $response = $this->get(route('web/instructions/show', ['legoSet' => 5]));

        $response->assertOk();
        $this->assertDownload($response, 'dummy.pdf');
    }
}

API test (OpenAPI validation)

use DejwCake\TestingKit\Functional\ApiTestCase;
use DejwCake\TestingKit\Attributes\Context;

final class PostsControllerTest extends ApiTestCase
{
    #[Context(user: 'customer')]
    public function testCustomerCanListPosts(): void
    {
        $response = $this->getJson(route('api/posts/index'));

        $response->assertOk();
        $this->assertValidOpenApiResponseForRoute('GET', 'api/posts/index', $response);
    }
}

Acting as an admin

#[Context(user: 'admin-user')] resolves the guard from admin-auth.defaults.guard (Spatie HasRoles then sees the admin guard, so the role lookup matches the admin-auth installation migration). The fixture admin user has id = testing-kit.authenticated_user_id.

Issues

If something is not working as expected, please open an issue in the main repository https://github.com/dejwCake/craftable.

How to develop this project

Composer

Update dependencies:

docker compose run -it --rm test composer update

Composer normalization:

docker compose run -it --rm php-qa composer normalize

Run tests

Run tests with pcov:

docker compose run -it --rm test ./vendor/bin/phpunit -d pcov.enabled=1

To regenerate snapshots use:

docker compose run -it --rm test ./vendor/bin/phpunit -d pcov.enabled=1 -d --update-snapshots

To switch between postgresql and mariadb change in docker-compose.yml DB_CONNECTION environmental variable:

- DB_CONNECTION: pgsql
+ DB_CONNECTION: mysql

Run code analysis tools (php-qa)

PHP compatibility:

docker compose run -it --rm php-qa phpcs --standard=.phpcs.compatibility.xml --cache=.phpcs.cache

Code style:

docker compose run -it --rm php-qa phpcs -s --colors --extensions=php

Fix style issues:

docker compose run -it --rm php-qa phpcbf -s --colors --extensions=php

Static analysis (phpstan):

docker compose run -it --rm php-qa phpstan analyse --configuration=phpstan.neon

Mess detector (phpmd):

docker compose run -it --rm php-qa phpmd ./config,./src,./tests ansi phpmd.xml --suffixes php --baseline-file phpmd.baseline.xml