Testing Permissions

Test Setup

Always reset the permission cache before each test to ensure clean state.

use Spatie\Permission\PermissionRegistrar;

beforeEach(function () {
    // Reset permission cache
    app(PermissionRegistrar::class)->forgetCachedPermissions();
    
    // Create test user and permissions
    $this->user = User::create(['email' => 'test@example.com']);
    $this->permission = Permission::create(['name' => 'edit-articles']);
    $this->role = Role::create(['name' => 'editor']);
});

Use Pest’s beforeEach() or PHPUnit’s setUp() to establish a consistent test environment:

protected function setUp(): void
{
    parent::setUp();
    
    $this->artisan('permission:cache-reset');
}

Testing Permission Assignment

Verify permissions can be assigned and checked correctly.

it('can assign a permission to a user', function () {
    $user = User::create(['email' => 'test@example.com']);
    $permission = Permission::create(['name' => 'edit-articles']);
    
    $user->givePermissionTo($permission);
    
    expect($user->hasPermissionTo('edit-articles'))->toBeTrue();
    expect($user->hasDirectPermission('edit-articles'))->toBeTrue();
});

it('can revoke a permission from a user', function () {
    $user = User::create(['email' => 'test@example.com']);
    $permission = Permission::create(['name' => 'edit-articles']);
    
    $user->givePermissionTo($permission);
    expect($user->hasPermissionTo($permission))->toBeTrue();
    
    $user->revokePermissionTo($permission);
    expect($user->hasPermissionTo($permission))->toBeFalse();
});

Always test both positive and negative cases to ensure permissions work as expected.

Testing with Multiple Guards

Test that guard separation is properly enforced.

use Spatie\Permission\Exceptions\GuardDoesNotMatch;
use Spatie\Permission\Exceptions\PermissionDoesNotExist;

it('throws exception when assigning permission from different guard', function () {
    $user = User::create(['email' => 'test@example.com']);
    $adminPermission = Permission::create([
        'name' => 'admin-permission',
        'guard_name' => 'admin'
    ]);
    
    expect(fn() => $user->givePermissionTo($adminPermission))
        ->toThrow(GuardDoesNotMatch::class);
});

it('can check permissions for non-default guard', function () {
    $permission = Permission::create([
        'name' => 'edit-articles',
        'guard_name' => 'api'
    ]);
    
    $user->givePermissionTo($permission);
    
    expect($user->hasPermissionTo($permission))->toBeTrue();
});

Always create permissions with the correct guard before testing:

// ❌ This will fail - permission doesn't exist for 'web' guard
expect(fn() => $user->hasPermissionTo('admin-permission'))
    ->toThrow(PermissionDoesNotExist::class);

Testing Role Permissions

Test that permissions work correctly through role assignment.

it('can determine if user has permission through roles', function () {
    $user = User::create(['email' => 'test@example.com']);
    $role = Role::create(['name' => 'editor']);
    $permission = Permission::create(['name' => 'edit-articles']);
    
    $role->givePermissionTo($permission);
    $user->assignRole($role);
    
    expect($user->hasPermissionTo($permission))->toBeTrue();
    expect($user->hasDirectPermission($permission))->toBeFalse();
    expect($user->hasPermissionViaRole($permission))->toBeTrue();
});

it('can list all permissions via roles', function () {
    $user = User::create(['email' => 'test@example.com']);
    $role1 = Role::create(['name' => 'editor']);
    $role2 = Role::create(['name' => 'author']);
    
    $role1->givePermissionTo('edit-articles');
    $role2->givePermissionTo('edit-news');
    
    $user->assignRole('editor', 'author');
    
    expect($user->getPermissionsViaRoles()->pluck('name')->sort()->values())
        ->toEqual(collect(['edit-articles', 'edit-news']));
});

Testing with Laravel Gates

Verify that permissions integrate correctly with Laravel’s authorization Gate.

use Illuminate\Support\Facades\Gate;

it('can determine if user does not have permission', function () {
    $user = User::create(['email' => 'test@example.com']);
    Permission::create(['name' => 'edit-articles']);
    
    expect($user->can('edit-articles'))->toBeFalse();
});

it('can determine if user has direct permission', function () {
    $user = User::create(['email' => 'test@example.com']);
    $permission = Permission::create(['name' => 'edit-articles']);
    
    $user->givePermissionTo($permission);
    
    expect($user->can('edit-articles'))->toBeTrue();
    expect($user->can('non-existing-permission'))->toBeFalse();
});

it('allows gate before callback to override permissions', function () {
    $user = User::create(['email' => 'test@example.com']);
    Permission::create(['name' => 'edit-articles']);
    
    expect($user->can('edit-articles'))->toBeFalse();
    
    // Super admin gate
    Gate::before(function () {
        return true; // Override for super admin
    });
    
    expect($user->can('edit-articles'))->toBeTrue();
});

Gate callbacks allow you to test super-admin scenarios:

Gate::before(function ($user, $ability) {
    return $user->hasRole('super-admin') ? true : null;
});

Testing Middleware

Test route protection with permission middleware.

use Spatie\Permission\Middleware\PermissionMiddleware;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

it('guest cannot access protected route', function () {
    $middleware = new PermissionMiddleware();
    
    $request = Request::create('/admin', 'GET');
    
    expect(function () use ($middleware, $request) {
        $middleware->handle($request, fn() => new Response(), 'edit-articles');
    })->toThrow(UnauthorizedException::class);
});

it('user can access route with correct permission', function () {
    $user = User::create(['email' => 'test@example.com']);
    $user->givePermissionTo('edit-articles');
    
    Auth::login($user);
    
    $response = $this->get('/admin/articles');
    $response->assertStatus(200);
});

it('user cannot access route without permission', function () {
    $user = User::create(['email' => 'test@example.com']);
    Auth::login($user);
    
    $response = $this->get('/admin/articles');
    $response->assertStatus(403);
});

Testing OR Permissions in Middleware

it('user can access route with one of multiple permissions', function () {
    $user = User::create(['email' => 'test@example.com']);
    $user->givePermissionTo('edit-articles');
    
    Auth::login($user);
    
    // Route protected with: permission:edit-articles|edit-news
    $response = $this->get('/admin/content');
    $response->assertStatus(200);
});

Testing Query Scopes

Test that database query scopes filter users correctly.

it('can scope users using permission', function () {
    User::create(['email' => 'user1@test.com'])
        ->givePermissionTo(['edit-articles', 'edit-news']);
    
    $role = Role::create(['name' => 'editor']);
    $role->givePermissionTo('edit-articles');
    
    User::create(['email' => 'user2@test.com'])
        ->assignRole('editor');
    
    User::create(['email' => 'user3@test.com']);
    
    $editors = User::permission('edit-articles')->get();
    $withoutNews = User::withoutPermission('edit-news')->get();
    
    expect($editors->count())->toEqual(2);
    expect($withoutNews->count())->toEqual(2);
});

it('can scope users by multiple permissions', function () {
    User::create(['email' => 'user1@test.com'])
        ->givePermissionTo(['edit-articles', 'edit-news']);
    
    User::create(['email' => 'user2@test.com'])
        ->givePermissionTo('edit-articles');
    
    $scopedUsers = User::permission(['edit-articles', 'edit-news'])->get();
    
    expect($scopedUsers->count())->toEqual(2);
});

Testing Cache Behavior

Verify that cache is properly managed during permission operations.

use Illuminate\Support\Facades\DB;

beforeEach(function () {
    $this->registrar = app(PermissionRegistrar::class);
    $this->registrar->forgetCachedPermissions();
    
    DB::enableQueryLog();
});

function resetQueryCount(): void
{
    DB::flushQueryLog();
}

function assertQueryCount(int $expected): void
{
    expect(DB::getQueryLog())->toHaveCount($expected);
}

it('caches permissions after first load', function () {
    resetQueryCount();
    $this->registrar->getPermissions();
    $initialQueries = count(DB::getQueryLog());
    
    resetQueryCount();
    $this->registrar->getPermissions();
    
    assertQueryCount(0); // No queries - loaded from cache
});

it('flushes cache when creating permission', function () {
    $this->registrar->getPermissions(); // Load cache
    
    Permission::create(['name' => 'new-permission']);
    
    resetQueryCount();
    $this->registrar->getPermissions(); // Cache was flushed
    
    expect(count(DB::getQueryLog()))->toBeGreaterThan(0);
});

it('does not flush cache when assigning permission to user', function () {
    $user = User::create(['email' => 'test@example.com']);
    $this->registrar->getPermissions(); // Load cache
    
    $user->givePermissionTo('edit-articles');
    
    resetQueryCount();
    $this->registrar->getPermissions();
    
    assertQueryCount(0); // Cache not flushed - optimization
});

From CacheTest.php:98: User-level permission changes don’t flush the global cache because they don’t affect the permission structure itself. This is a performance optimization.