Laravel单元测试无法识别导入的Keycloak服务类

问题重现 #

执行php artisan test运行Keycloak服务类的单元测试时，出现如下错误：

Class "App\Services\Keycloak" not found

  at tests\Unit\KeycloakTest.php:23
     19▕         $base_realm = env('KEYCLOAK_REALM');
     20▕         $base_client_id = env('KEYCLOAK_CLIENT_ID');
     21▕         $base_client_secret= env('KEYCLOAK_CLIENT_SECRET');
     22▕
  ➜  23▕         $keycloak = new \App\Services\Keycloak($base_url, $base_realm, $base_client_id, $base_client_secret);
     24▕
     25▕
     26▕
     27▕         $this->keycloak = $keycloak->getAdminToken();

  1   tests\Unit\KeycloakTest.php:23

问题根源及解决方案 #

1. 文件名与类名大小写不匹配（PSR-4规范要求） #

你的Keycloak服务类文件路径为app/Services/keycloak.php，但类名是Keycloak（首字母大写）。根据PSR-4自动加载规范，类名必须和文件名完全一致（包括大小写），否则Composer无法正确映射类到文件。

解决步骤：

• 将app/Services/keycloak.php重命名为app/Services/Keycloak.php

2. PHP标签不规范 #

服务类开头使用了<?短标签，部分PHP环境可能未开启短标签支持，导致类定义无法被解析。

解决步骤：

• 将服务类开头的<?替换为标准的<?php标签

修改后的服务类开头示例：

<?php

namespace App\Services;
use Illuminate\Support\Facades\Http;
use Exception;

class Keycloak {
    // ... 类实现代码
}

3. 刷新Composer自动加载缓存 #

即使配置正确，旧的自动加载缓存可能导致类无法被找到，需要重新生成缓存。

执行命令：

composer dump-autoload

4. 可选优化：单元测试隔离外部依赖 #

你的单元测试直接调用了真实的Keycloak API，建议使用Mock隔离外部服务，避免测试受外部环境影响。示例代码如下：

<?php

namespace Tests\Unit;

use App\Services\Keycloak;
use PHPUnit\Framework\TestCase;
use Mockery;

class KeycloakTest extends TestCase
{
    protected function tearDown(): void
    {
        Mockery::close();
        parent::tearDown();
    }

    public function test_get_token(): void
    {
        // 创建Mock实例
        $keycloakMock = Mockery::mock(Keycloak::class);
        // 模拟getToken方法返回预期结果
        $keycloakMock->shouldReceive('getToken')
            ->with('test', 'Test123@!', 'dummy@outlook.com')
            ->andReturn(['access_token' => 'fake_token']);

        $response = $keycloakMock->getToken('test', 'Test123@!', 'dummy@outlook.com');

        $this->assertIsArray($response);
        $this->assertArrayHasKey('access_token', $response);
        $this->assertEquals('fake_token', $response['access_token']);
    }
}

内容的提问来源于stack exchange，提问作者user23317965