✅ Unit-Tests (KeycloakUser, KeycloakUserProvider) + CI

.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+# file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC
+name: Tests
+
+on:
+  push:
+    branches: [main, master, "feature/**"]
+  pull_request:
+
+jobs:
+  phpunit:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.3", "8.4"]
+    name: PHPUnit (PHP ${{ matrix.php }})
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+      - run: composer install --no-interaction --no-progress
+      - run: vendor/bin/phpunit

.gitignore

@@ -0,0 +1,4 @@
+# file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC
+/vendor/
+/composer.lock
+/.phpunit.cache/

composer.json

@@ -15,6 +15,9 @@
         "symfony/security-bundle": "^7.0",
         "lexik/jwt-authentication-bundle": "^3.0"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^12.0"
+    },
     "autoload": {
         "psr-4": {
             "Dmstr\\KeycloakSecurity\\": "src/"

docker-compose.yml

@@ -0,0 +1,15 @@
+# file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC
+# CLI-only test runner for this bundle — no MySQL/FPM required.
+# Usage (on host):
+#   docker compose run --rm php
+# Runs `composer install` then PHPUnit against tests/.
+services:
+  php:
+    build:
+      dockerfile_inline: |
+        FROM php:8.4-cli-alpine
+        COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
+    working_dir: /repo
+    volumes:
+      - .:/repo
+    command: sh -c "composer install --no-interaction --no-progress && vendor/bin/phpunit"

phpunit.dist.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         cacheDirectory=".phpunit.cache">
+    <testsuites>
+        <testsuite name="default">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

tests/Security/KeycloakUserProviderTest.php

@@ -0,0 +1,99 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\KeycloakSecurity\Tests\Security;
+
+use Dmstr\KeycloakSecurity\Security\KeycloakUser;
+use Dmstr\KeycloakSecurity\Security\KeycloakUserProvider;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for {@see KeycloakUserProvider}.
+ *
+ * Exercises the realm_access.roles → ROLE_* mapping (uppercasing, filtering of
+ * Keycloak-internal roles) and claim extraction via the public
+ * loadUserByIdentifierAndPayload() entry point.
+ */
+final class KeycloakUserProviderTest extends TestCase
+{
+    private KeycloakUserProvider $provider;
+
+    protected function setUp(): void
+    {
+        $this->provider = new KeycloakUserProvider();
+    }
+
+    public function testMapsRealmRolesToUppercasedSymfonyRoles(): void
+    {
+        $user = $this->provider->loadUserByIdentifierAndPayload('alice', [
+            'realm_access' => ['roles' => ['admin', 'editor']],
+        ]);
+
+        $roles = array_values($user->getRoles());
+        self::assertContains('ROLE_ADMIN', $roles);
+        self::assertContains('ROLE_EDITOR', $roles);
+        self::assertContains('ROLE_USER', $roles);
+    }
+
+    public function testFiltersKeycloakInternalRoles(): void
+    {
+        $user = $this->provider->loadUserByIdentifierAndPayload('alice', [
+            'realm_access' => ['roles' => [
+                'admin',
+                'default-roles-myrealm',
+                'offline_access',
+                'uma_authorization',
+            ]],
+        ]);
+
+        // Only ROLE_ADMIN survives the filter; ROLE_USER is added by the user.
+        self::assertEqualsCanonicalizing(['ROLE_ADMIN', 'ROLE_USER'], array_values($user->getRoles()));
+    }
+
+    public function testExtractsEmailAndName(): void
+    {
+        $user = $this->provider->loadUserByIdentifierAndPayload('alice', [
+            'email' => 'alice@example.com',
+            'given_name' => 'Alice',
+            'family_name' => 'Anderson',
+        ]);
+
+        self::assertInstanceOf(KeycloakUser::class, $user);
+        self::assertSame('alice', $user->getUserIdentifier());
+        self::assertSame('alice@example.com', $user->getEmail());
+        self::assertSame('Alice', $user->getGivenName());
+        self::assertSame('Anderson', $user->getFamilyName());
+    }
+
+    public function testMissingClaimsDefaultToEmpty(): void
+    {
+        $user = $this->provider->loadUserByIdentifierAndPayload('alice', []);
+
+        self::assertSame('', $user->getEmail());
+        self::assertSame('', $user->getGivenName());
+        self::assertSame('', $user->getFamilyName());
+        self::assertSame(['ROLE_USER'], array_values($user->getRoles()));
+    }
+
+    public function testLoadUserByIdentifierFallbackHasNoRealmRoles(): void
+    {
+        $user = $this->provider->loadUserByIdentifier('alice');
+
+        self::assertSame('alice', $user->getUserIdentifier());
+        self::assertSame(['ROLE_USER'], array_values($user->getRoles()));
+    }
+
+    public function testRefreshUserReturnsSameInstance(): void
+    {
+        $user = new KeycloakUser('alice', ['ROLE_ADMIN']);
+        self::assertSame($user, $this->provider->refreshUser($user));
+    }
+
+    public function testSupportsOnlyKeycloakUserClass(): void
+    {
+        self::assertTrue($this->provider->supportsClass(KeycloakUser::class));
+        self::assertFalse($this->provider->supportsClass(\stdClass::class));
+    }
+}

tests/Security/KeycloakUserTest.php

@@ -0,0 +1,70 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-06-13 23:14:54 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\KeycloakSecurity\Tests\Security;
+
+use Dmstr\KeycloakSecurity\Security\KeycloakUser;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for {@see KeycloakUser} — the immutable DTO wrapping a Keycloak
+ * JWT identity. Verifies the mandatory ROLE_USER guarantee, deduplication and
+ * the plain getters.
+ */
+final class KeycloakUserTest extends TestCase
+{
+    public function testGetRolesAlwaysAddsRoleUser(): void
+    {
+        $user = new KeycloakUser('alice', ['ROLE_ADMIN']);
+
+        $roles = array_values($user->getRoles());
+        self::assertContains('ROLE_ADMIN', $roles);
+        self::assertContains('ROLE_USER', $roles);
+    }
+
+    public function testGetRolesDeduplicatesRoleUser(): void
+    {
+        $user = new KeycloakUser('alice', ['ROLE_USER', 'ROLE_ADMIN']);
+
+        self::assertSame(
+            ['ROLE_USER', 'ROLE_ADMIN'],
+            array_values($user->getRoles()),
+            'ROLE_USER must not be duplicated when already present.'
+        );
+    }
+
+    public function testEmptyRolesYieldOnlyRoleUser(): void
+    {
+        self::assertSame(['ROLE_USER'], array_values((new KeycloakUser('alice'))->getRoles()));
+    }
+
+    public function testGettersExposeConstructorValues(): void
+    {
+        $user = new KeycloakUser('alice', [], 'alice@example.com', 'Alice', 'Anderson');
+
+        self::assertSame('alice', $user->getUserIdentifier());
+        self::assertSame('alice@example.com', $user->getEmail());
+        self::assertSame('Alice', $user->getGivenName());
+        self::assertSame('Anderson', $user->getFamilyName());
+    }
+
+    public function testGettersDefaultToEmptyStrings(): void
+    {
+        $user = new KeycloakUser('alice');
+
+        self::assertSame('', $user->getEmail());
+        self::assertSame('', $user->getGivenName());
+        self::assertSame('', $user->getFamilyName());
+    }
+
+    public function testEraseCredentialsIsNoop(): void
+    {
+        $user = new KeycloakUser('alice', ['ROLE_ADMIN'], 'alice@example.com');
+        $user->eraseCredentials();
+
+        self::assertSame('alice', $user->getUserIdentifier());
+        self::assertSame('alice@example.com', $user->getEmail());
+    }
+}