README

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):

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