feature #40366 [FrameworkBundle] Add KernelTestCase::getContainer() (Nyholm)

This PR was squashed before being merged into the 5.3-dev branch.

Discussion
----------

[FrameworkBundle] Add KernelTestCase::getContainer()

| Q             | A
| ------------- | ---
| Branch?       | 5.x
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | yes
| Tickets       |
| License       | MIT
| Doc PR        | symfony/symfony-docs#14731

There are at least 3 ways to get the container in a test class:

```php
class FooTest extends WebTestCase
{
    public function testGetContainerA()
    {
        $kernel = self::bootKernel();
        $container = $kernel->getContainer();
    }

    public function testGetContainerB()
    {
        self::bootKernel();
        $container = self::$container;
    }

    public function testGetContainerC()
    {
        $client = self::createClient();
        $container = $client->getContainer();
    }
}
```

I suggest to add a fourth =)

Basically, in tests you should always use the `test.service_container`. It is hard to remove A and C, but I can deprecate C and add a helper function.

```php
class FooTest extends WebTestCase
{
    public function testGetContainerTheOnlyWayYouShouldUse()
    {
        $container = $this->getContainer();
    }
}
```

This new way will also boot your kernel if it is not already booted.

Commits
-------

f4c9724 [FrameworkBundle] Add KernelTestCase::getContainer()

Author: fabpot

UPGRADE-5.3.md

@@ -35,6 +35,7 @@ FrameworkBundle
  * Deprecate the `session.storage` alias and `session.storage.*` services, use the `session.storage.factory` alias and `session.storage.factory.*` services instead
  * Deprecate the `framework.session.storage_id` configuration option, use the `framework.session.storage_factory_id` configuration option instead
  * Deprecate the `session` service and the `SessionInterface` alias, use the `\Symfony\Component\HttpFoundation\Request::getSession()` or the new `\Symfony\Component\HttpFoundation\RequestStack::getSession()` methods instead
+ * Deprecate the `KernelTestCase::$container` property, use `KernelTestCase::getContainer()` instead
 
 HttpFoundation
 --------------

UPGRADE-6.0.md

@@ -78,6 +78,7 @@ FrameworkBundle
  * The `form.factory`, `form.type.file`, `translator`, `security.csrf.token_manager`, `serializer`,
    `cache_clearer`, `filesystem` and `validator` services are now private.
  * Removed the `lock.RESOURCE_NAME` and `lock.RESOURCE_NAME.store` services and the `lock`, `LockInterface`, `lock.store` and `PersistingStoreInterface` aliases, use `lock.RESOURCE_NAME.factory`, `lock.factory` or `LockFactory` instead.
+ * Remove the `KernelTestCase::$container` property, use `KernelTestCase::getContainer()` instead
 
 HttpFoundation
 --------------

src/Symfony/Bundle/FrameworkBundle/CHANGELOG.md

@@ -16,6 +16,7 @@ CHANGELOG
  * Add tag `assets.package` to register asset packages
  * Add support to use a PSR-6 compatible cache for Doctrine annotations
  * Deprecate all other values than "none", "php_array" and "file" for `framework.annotation.cache`
+ * Add `KernelTestCase::getContainer()` as the best way to get a container in tests
 
 5.2.0
 -----

src/Symfony/Bundle/FrameworkBundle/Test/KernelTestCase.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\DependencyInjection\ContainerInterface;
+use Symfony\Component\DependencyInjection\Exception\ServiceNotFoundException;
 use Symfony\Component\HttpKernel\KernelInterface;
 use Symfony\Contracts\Service\ResetInterface;
 
@@ -34,6 +35,8 @@ abstract class KernelTestCase extends TestCase
 
     /**
      * @var ContainerInterface
+     *
+     * @deprecated since Symfony 5.3, use static::getContainer() instead
      */
     protected static $container;
 
@@ -86,6 +89,27 @@ protected static function bootKernel(array $options = [])
         return static::$kernel;
     }
 
+    /**
+     * Provides a dedicated test container with access to both public and private
+     * services. The container will not include private services that has been
+     * inlined or removed. Private services will be removed when they are not
+     * used by other services.
+     *
+     * Using this method is the best way to get a container from your test code.
+     */
+    protected static function getContainer(): ContainerInterface
+    {
+        if (!static::$booted) {
+            static::bootKernel();
+        }
+
+        try {
+            return self::$kernelContainer->get('test.service_container');
+        } catch (ServiceNotFoundException $e) {
+            throw new \LogicException('Could not find service "test.service_container". Try updating the "framework.test" config to "true".', 0, $e);
+        }
+    }
+
     /**
      * Creates a Kernel.
      *

src/Symfony/Bundle/FrameworkBundle/Test/MailerAssertionsTrait.php

@@ -118,12 +118,13 @@ public static function getMailerMessage(int $index = 0, string $transport = null
 
     private static function getMessageMailerEvents(): MessageEvents
     {
-        if (self::$container->has('mailer.message_logger_listener')) {
-            return self::$container->get('mailer.message_logger_listener')->getEvents();
+        $container = static::getContainer();
+        if ($container->has('mailer.message_logger_listener')) {
+            return $container->get('mailer.message_logger_listener')->getEvents();
         }
 
-        if (self::$container->has('mailer.logger_message_listener')) {
-            return self::$container->get('mailer.logger_message_listener')->getEvents();
+        if ($container->has('mailer.logger_message_listener')) {
+            return $container->get('mailer.logger_message_listener')->getEvents();
         }
 
         static::fail('A client must have Mailer enabled to make email assertions. Did you forget to require symfony/mailer?');

src/Symfony/Bundle/FrameworkBundle/Test/TestContainer.php

@@ -17,6 +17,11 @@
 use Symfony\Component\HttpKernel\KernelInterface;
 
 /**
+ * A special container used in tests. This gives access to both public and
+ * private services. The container will not include private services that has
+ * been inlined or removed. Private services will be removed when they are not
+ * used by other services.
+ *
  * @author Nicolas Grekas <[email protected]>
  *
  * @internal

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/AutowiringTypesTest.php

@@ -25,36 +25,36 @@ public function testAnnotationReaderAutowiring()
     {
         static::bootKernel(['root_config' => 'no_annotations_cache.yml', 'environment' => 'no_annotations_cache']);
 
-        $annotationReader = static::$container->get('test.autowiring_types.autowired_services')->getAnnotationReader();
+        $annotationReader = self::getContainer()->get('test.autowiring_types.autowired_services')->getAnnotationReader();
         $this->assertInstanceOf(AnnotationReader::class, $annotationReader);
     }
 
     public function testCachedAnnotationReaderAutowiring()
     {
         static::bootKernel();
 
-        $annotationReader = static::$container->get('test.autowiring_types.autowired_services')->getAnnotationReader();
+        $annotationReader = self::getContainer()->get('test.autowiring_types.autowired_services')->getAnnotationReader();
         $this->assertInstanceOf(class_exists(PsrCachedReader::class) ? PsrCachedReader::class : CachedReader::class, $annotationReader);
     }
 
     public function testEventDispatcherAutowiring()
     {
         static::bootKernel(['debug' => false]);
 
-        $autowiredServices = static::$container->get('test.autowiring_types.autowired_services');
+        $autowiredServices = self::getContainer()->get('test.autowiring_types.autowired_services');
         $this->assertInstanceOf(EventDispatcher::class, $autowiredServices->getDispatcher(), 'The event_dispatcher service should be injected if the debug is not enabled');
 
         static::bootKernel(['debug' => true]);
 
-        $autowiredServices = static::$container->get('test.autowiring_types.autowired_services');
+        $autowiredServices = self::getContainer()->get('test.autowiring_types.autowired_services');
         $this->assertInstanceOf(TraceableEventDispatcher::class, $autowiredServices->getDispatcher(), 'The debug.event_dispatcher service should be injected if the debug is enabled');
     }
 
     public function testCacheAutowiring()
     {
         static::bootKernel();
 
-        $autowiredServices = static::$container->get('test.autowiring_types.autowired_services');
+        $autowiredServices = self::getContainer()->get('test.autowiring_types.autowired_services');
         $this->assertInstanceOf(FilesystemAdapter::class, $autowiredServices->getCachePool());
     }
 

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/BundlePathsTest.php

@@ -40,8 +40,8 @@ public function testBundlePublicDir()
     public function testBundleTwigTemplatesDir()
     {
         static::bootKernel(['test_case' => 'BundlePaths']);
-        $twig = static::$container->get('twig.alias');
-        $bundlesMetadata = static::$container->getParameter('kernel.bundles_metadata');
+        $twig = static::getContainer()->get('twig.alias');
+        $bundlesMetadata = static::getContainer()->getParameter('kernel.bundles_metadata');
 
         $this->assertSame([$bundlesMetadata['LegacyBundle']['path'].'/Resources/views'], $twig->getLoader()->getPaths('Legacy'));
         $this->assertSame("OK\n", $twig->render('@Legacy/index.html.twig'));
@@ -53,7 +53,7 @@ public function testBundleTwigTemplatesDir()
     public function testBundleTranslationsDir()
     {
         static::bootKernel(['test_case' => 'BundlePaths']);
-        $translator = static::$container->get('translator.alias');
+        $translator = static::getContainer()->get('translator.alias');
 
         $this->assertSame('OK', $translator->trans('ok_label', [], 'legacy'));
         $this->assertSame('OK', $translator->trans('ok_label', [], 'modern'));
@@ -62,7 +62,7 @@ public function testBundleTranslationsDir()
     public function testBundleValidationConfigDir()
     {
         static::bootKernel(['test_case' => 'BundlePaths']);
-        $validator = static::$container->get('validator.alias');
+        $validator = static::getContainer()->get('validator.alias');
 
         $this->assertTrue($validator->hasMetadataFor(LegacyPerson::class));
         $this->assertCount(1, $constraintViolationList = $validator->validate(new LegacyPerson('john', 5)));
@@ -76,7 +76,7 @@ public function testBundleValidationConfigDir()
     public function testBundleSerializationConfigDir()
     {
         static::bootKernel(['test_case' => 'BundlePaths']);
-        $serializer = static::$container->get('serializer.alias');
+        $serializer = static::getContainer()->get('serializer.alias');
 
         $this->assertEquals(['full_name' => 'john', 'age' => 5], $serializer->normalize(new LegacyPerson('john', 5), 'json'));
         $this->assertEquals(['full_name' => 'john', 'age' => 5], $serializer->normalize(new ModernPerson('john', 5), 'json'));

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolClearCommandTest.php

@@ -80,7 +80,7 @@ public function testClearFailed()
     {
         $tester = $this->createCommandTester();
         /** @var FilesystemAdapter $pool */
-        $pool = static::$container->get('cache.public_pool');
+        $pool = static::getContainer()->get('cache.public_pool');
         $item = $pool->getItem('foo');
         $item->set('baz');
         $pool->save($item);
@@ -108,7 +108,7 @@ public function testClearFailed()
     private function createCommandTester()
     {
         $application = new Application(static::$kernel);
-        $application->add(new CachePoolClearCommand(static::$container->get('cache.global_clearer')));
+        $application->add(new CachePoolClearCommand(static::getContainer()->get('cache.global_clearer')));
 
         return new CommandTester($application->find('cache:pool:clear'));
     }

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/CachePoolsTest.php

@@ -78,7 +78,7 @@ public function testRedisCustomCachePools()
     private function doTestCachePools($options, $adapterClass)
     {
         static::bootKernel($options);
-        $container = static::$container;
+        $container = static::getContainer();
 
         $pool1 = $container->get('cache.pool1');
         $this->assertInstanceOf($adapterClass, $pool1);

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ContainerDebugCommandTest.php

@@ -27,12 +27,12 @@ public function testDumpContainerIfNotExists()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container']);
 
-        $this->assertFileExists(static::$container->getParameter('debug.container.dump'));
+        $this->assertFileExists(static::getContainer()->getParameter('debug.container.dump'));
     }
 
     public function testNoDebug()
@@ -91,7 +91,7 @@ public function testDescribeEnvVars()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container', '--env-vars' => true], ['decorated' => false]);
@@ -128,7 +128,7 @@ public function testDescribeEnvVar()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container', '--env-var' => 'js'], ['decorated' => false]);
@@ -156,7 +156,7 @@ public function testGetDeprecation()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container', '--deprecations' => true]);
@@ -176,7 +176,7 @@ public function testGetDeprecationNone()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container', '--deprecations' => true]);
@@ -194,7 +194,7 @@ public function testGetDeprecationNoFile()
         $application = new Application(static::$kernel);
         $application->setAutoExit(false);
 
-        @unlink(static::$container->getParameter('debug.container.dump'));
+        @unlink(static::getContainer()->getParameter('debug.container.dump'));
 
         $tester = new ApplicationTester($application);
         $tester->run(['command' => 'debug:container', '--deprecations' => true]);

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/ContainerDumpTest.php

@@ -20,13 +20,13 @@ public function testContainerCompilationInDebug()
     {
         $this->createClient(['test_case' => 'ContainerDump', 'root_config' => 'config.yml']);
 
-        $this->assertTrue(static::$container->has('serializer'));
+        $this->assertTrue(static::getContainer()->has('serializer'));
     }
 
     public function testContainerCompilation()
     {
         $this->createClient(['test_case' => 'ContainerDump', 'root_config' => 'config.yml', 'debug' => false]);
 
-        $this->assertTrue(static::$container->has('serializer'));
+        $this->assertTrue(static::getContainer()->has('serializer'));
     }
 }

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/KernelTestCaseTest.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bundle\FrameworkBundle\Tests\Functional;
+
+use Symfony\Bundle\FrameworkBundle\Test\TestContainer;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestServiceContainer\NonPublicService;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestServiceContainer\PrivateService;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestServiceContainer\PublicService;
+use Symfony\Bundle\FrameworkBundle\Tests\Functional\Bundle\TestBundle\TestServiceContainer\UnusedPrivateService;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+class KernelTestCaseTest extends AbstractWebTestCase
+{
+    public function testThatPrivateServicesAreUnavailableIfTestConfigIsDisabled()
+    {
+        static::bootKernel(['test_case' => 'TestServiceContainer', 'root_config' => 'test_disabled.yml', 'environment' => 'test_disabled']);
+
+        $this->expectException(\LogicException::class);
+        static::getContainer();
+    }
+
+    public function testThatPrivateServicesAreAvailableIfTestConfigIsEnabled()
+    {
+        static::bootKernel(['test_case' => 'TestServiceContainer']);
+
+        $container = static::getContainer();
+        $this->assertInstanceOf(ContainerInterface::class, $container);
+        $this->assertInstanceOf(TestContainer::class, $container);
+        $this->assertTrue($container->has(PublicService::class));
+        $this->assertTrue($container->has(NonPublicService::class));
+        $this->assertTrue($container->has(PrivateService::class));
+        $this->assertTrue($container->has('private_service'));
+        $this->assertFalse($container->has(UnusedPrivateService::class));
+    }
+}

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/MailerTest.php

@@ -28,8 +28,8 @@ public function testEnvelopeListener()
             $this->assertEquals('[email protected]', $envelope->getSender()->getAddress());
         };
 
-        $eventDispatcher = self::$container->get(EventDispatcherInterface::class);
-        $logger = self::$container->get('logger');
+        $eventDispatcher = self::getContainer()->get(EventDispatcherInterface::class);
+        $logger = self::getContainer()->get('logger');
 
         $testTransport = new class($eventDispatcher, $logger, $onDoSend) extends AbstractTransport {
             /**

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/PropertyInfoTest.php

@@ -19,7 +19,7 @@ public function testPhpDocPriority()
     {
         static::bootKernel(['test_case' => 'Serializer']);
 
-        $this->assertEquals([new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true, new Type(Type::BUILTIN_TYPE_INT), new Type(Type::BUILTIN_TYPE_INT))], static::$container->get('property_info')->getTypes('Symfony\Bundle\FrameworkBundle\Tests\Functional\Dummy', 'codes'));
+        $this->assertEquals([new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true, new Type(Type::BUILTIN_TYPE_INT), new Type(Type::BUILTIN_TYPE_INT))], static::getContainer()->get('property_info')->getTypes('Symfony\Bundle\FrameworkBundle\Tests\Functional\Dummy', 'codes'));
     }
 }
 

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/SerializerTest.php

@@ -20,7 +20,7 @@ public function testDeserializeArrayOfObject()
     {
         static::bootKernel(['test_case' => 'Serializer']);
 
-        $result = static::$container->get('serializer.alias')->deserialize('{"bars": [{"id": 1}, {"id": 2}]}', Foo::class, 'json');
+        $result = static::getContainer()->get('serializer.alias')->deserialize('{"bars": [{"id": 1}, {"id": 2}]}', Foo::class, 'json');
 
         $bar1 = new Bar();
         $bar1->id = 1;

src/Symfony/Bundle/FrameworkBundle/Tests/Functional/TestServiceContainerTest.php

@@ -20,6 +20,9 @@
 
 class TestServiceContainerTest extends AbstractWebTestCase
 {
+    /**
+     * @group legacy
+     */
     public function testThatPrivateServicesAreUnavailableIfTestConfigIsDisabled()
     {
         static::bootKernel(['test_case' => 'TestServiceContainer', 'root_config' => 'test_disabled.yml', 'environment' => 'test_disabled']);
@@ -33,6 +36,9 @@ public function testThatPrivateServicesAreUnavailableIfTestConfigIsDisabled()
         $this->assertFalse(static::$container->has(UnusedPrivateService::class));
     }
 
+    /**
+     * @group legacy
+     */
     public function testThatPrivateServicesAreAvailableIfTestConfigIsEnabled()
     {
         static::bootKernel(['test_case' => 'TestServiceContainer']);

src/Symfony/Bundle/SecurityBundle/Tests/Functional/AutowiringTypesTest.php

@@ -21,12 +21,12 @@ public function testAccessDecisionManagerAutowiring()
     {
         static::bootKernel(['debug' => false]);
 
-        $autowiredServices = static::$container->get('test.autowiring_types.autowired_services');
+        $autowiredServices = static::getContainer()->get('test.autowiring_types.autowired_services');
         $this->assertInstanceOf(AccessDecisionManager::class, $autowiredServices->getAccessDecisionManager(), 'The security.access.decision_manager service should be injected in debug mode');
 
         static::bootKernel(['debug' => true]);
 
-        $autowiredServices = static::$container->get('test.autowiring_types.autowired_services');
+        $autowiredServices = static::getContainer()->get('test.autowiring_types.autowired_services');
         $this->assertInstanceOf(TraceableAccessDecisionManager::class, $autowiredServices->getAccessDecisionManager(), 'The debug.security.access.decision_manager service should be injected in non-debug mode');
     }