Symfony控制器单元测试：如何编写控制器的单元测试？

嘿，我太懂这种感觉了——功能测试跟着请求流程走，上手快得很，但控制器的单元测试确实需要换个思路，核心是把控制器从框架环境里抽出来，只测试它自己的逻辑，而不是整个HTTP请求链路。下面我一步步给你拆解怎么搞：

先明确区别：

• 功能测试用WebTestCase，模拟完整HTTP请求，走路由、容器、模板渲染全流程，测的是“用户发起请求后系统整体能不能正常工作”
• 单元测试用普通的PHPUnit\Framework\TestCase，只实例化控制器类，把它依赖的所有服务（比如Repository、Twig、其他业务服务）都用Mock替代，测的是“控制器自己的逻辑是否正确”——比如参数处理、条件分支、异常抛出、调用服务后的返回处理这些。

假设我们有个简单的PostController，有个show方法根据ID返回帖子详情：

// src/Controller/PostController.php
namespace App\Controller;

use App\Repository\PostRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class PostController extends AbstractController
{
    public function show(int $id, PostRepository $postRepository): Response
    {
        $post = $postRepository->find($id);
        
        if (!$post) {
            throw $this->createNotFoundException('Post not found');
        }
        
        return $this->render('post/show.html.twig', [
            'post' => $post,
        ]);
    }
}

1. 准备测试文件 #

在tests/Unit/Controller目录下创建PostControllerTest.php，继承PHPUnit\Framework\TestCase（注意不是WebTestCase）。

2. Mock所有外部依赖 #

控制器依赖PostRepository和Twig（因为用了render方法），我们需要用PHPUnit的Mock功能模拟这些依赖，控制它们的返回值，这样就能测试控制器对不同场景的处理逻辑。

3. 编写测试用例 #

针对show方法的两个核心场景编写测试：

// tests/Unit/Controller/PostControllerTest.php
namespace App\Tests\Unit\Controller;

use App\Controller\PostController;
use App\Repository\PostRepository;
use App\Entity\Post;
use PHPUnit\Framework\MockObject\MockObject;
use PHPUnit\Framework\TestCase;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Twig\Environment;
use Symfony\Component\DependencyInjection\ContainerInterface;

class PostControllerTest extends TestCase
{
    private PostController $controller;
    private MockObject $postRepositoryMock;
    private MockObject $twigMock;

    protected function setUp(): void
    {
        // 1. Mock PostRepository
        $this->postRepositoryMock = $this->createMock(PostRepository::class);
        
        // 2. Mock Twig环境（因为AbstractController的render依赖Twig）
        $this->twigMock = $this->createMock(Environment::class);
        
        // 3. 为控制器设置容器，注入Twig的Mock
        $containerMock = $this->createMock(ContainerInterface::class);
        $containerMock->method('get')
            ->with('twig')
            ->willReturn($this->twigMock);
        
        // 4. 实例化控制器
        $this->controller = new PostController();
        $this->controller->setContainer($containerMock);
    }

    public function testShowReturnsValidResponseWhenPostExists(): void
    {
        // 准备测试数据
        $testPostId = 1;
        $mockPost = $this->createMock(Post::class);
        
        // 配置Mock：调用find($testPostId)时返回mockPost
        $this->postRepositoryMock->expects($this->once())
            ->method('find')
            ->with($testPostId)
            ->willReturn($mockPost);
        
        // 配置Twig：验证render方法被正确调用，并模拟返回模板内容
        $this->twigMock->expects($this->once())
            ->method('render')
            ->with(
                'post/show.html.twig',
                ['post' => $mockPost]
            )
            ->willReturn('Mocked post content');
        
        // 调用控制器方法
        $response = $this->controller->show($testPostId, $this->postRepositoryMock);
        
        // 断言结果
        $this->assertInstanceOf(Response::class, $response);
        $this->assertEquals(200, $response->getStatusCode());
        $this->assertEquals('Mocked post content', $response->getContent());
    }

    public function testShowThrowsNotFoundExceptionWhenPostDoesNotExist(): void
    {
        // 准备测试数据
        $nonExistentPostId = 999;
        
        // 配置Mock：find方法返回null
        $this->postRepositoryMock->expects($this->once())
            ->method('find')
            ->with($nonExistentPostId)
            ->willReturn(null);
        
        // 预期会抛出NotFoundException
        $this->expectException(NotFoundHttpException::class);
        $this->expectExceptionMessage('Post not found');
        
        // 调用控制器方法
        $this->controller->show($nonExistentPostId, $this->postRepositoryMock);
    }
}

• 别用WebTestCase：单元测试要完全隔离框架，不需要加载整个Symfony环境，否则就成了功能测试的变体
• Mock所有外部依赖：控制器依赖的任何服务、Repository、甚至框架组件（比如Router、Security）都要Mock，确保测试只关注控制器自身的逻辑
• 处理AbstractController的依赖：如果控制器继承了AbstractController，它依赖容器里的服务，所以需要Mock容器并注入所需服务的Mock；更推荐的方式是用构造函数注入，这样测试时不用处理容器，直接注入Mock（下面说这个技巧）
• 聚焦核心逻辑：不要测试框架的功能（比如路由是否匹配、模板渲染的具体HTML），那些是功能测试的范畴；单元测试只测控制器里的业务判断、参数处理、异常抛出这些自己写的逻辑

如果你的控制器改用构造函数注入依赖，测试会更简洁，也更符合Symfony的最佳实践：

修改控制器：

// src/Controller/PostController.php
namespace App\Controller;

use App\Repository\PostRepository;
use Symfony\Component\HttpFoundation\Response;
use Twig\Environment;

class PostController
{
    private PostRepository $postRepository;
    private Environment $twig;

    public function __construct(PostRepository $postRepository, Environment $twig)
    {
        $this->postRepository = $postRepository;
        $this->twig = $twig;
    }

    public function show(int $id): Response
    {
        $post = $this->postRepository->find($id);
        
        if (!$post) {
            throw new \Symfony\Component\HttpKernel\Exception\NotFoundHttpException('Post not found');
        }
        
        return new Response($this->twig->render('post/show.html.twig', [
            'post' => $post,
        ]));
    }
}

这样测试时就不用处理容器了，直接在setUp里注入Mock：

protected function setUp(): void
{
    $this->postRepositoryMock = $this->createMock(PostRepository::class);
    $this->twigMock = $this->createMock(Environment::class);
    $this->controller = new PostController($this->postRepositoryMock, $this->twigMock);
}

代码更清爽，测试逻辑也更清晰，强烈推荐这种方式！

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