Documented KernelBrowser::loginUser()

Author: wouterj

.doctor-rst.yaml

@@ -85,3 +85,4 @@ whitelist:
         - ".. _`Deploying Symfony 4 Apps on Heroku`: https://devcenter.heroku.com/articles/deploying-symfony4"
         - "//                  224, 165, 141, 224, 164, 164, 224, 165, 135])"
         - '.. versionadded:: 0.2' # MercureBundle
+        - 'provides a ``loginUser()`` method to simulate logging in in your functional'

_build/redirection_map

@@ -480,3 +480,4 @@
 /components/translation/custom_formats https://github.com/symfony/translation
 /components/translation/custom_message_formatter https://github.com/symfony/translation
 /components/notifier https://github.com/symfony/notifier
+/testing/http_authentication /testing

security.rst

@@ -172,6 +172,8 @@ Now that Symfony knows *how* you want to encode the passwords, you can use the
 ``UserPasswordEncoderInterface`` service to do this before saving your users to
 the database.
 
+.. _user-data-fixture:
+
 For example, by using :ref:`DoctrineFixturesBundle <doctrine-fixtures>`, you can
 create dummy database users:
 

testing.rst

@@ -567,6 +567,62 @@ command.
     If the information you need to check is available from the profiler, use
     it instead.
 
+Logging in Users (Authentication)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.1
+
+    The ``loginUser()`` method was introduced in Symfony 5.1.
+
+When you want to add functional tests for protected pages, you have to
+first "login" as a user. Reproducing the actual steps - such as
+submitting a login form - make a test very slow. For this reason, Symfony
+provides a ``loginUser()`` method to simulate logging in in your functional
+tests.
+
+Instead of login in with real users, it's recommended to create a user only for
+tests. You can do that with Doctrine :ref:`data fixtures <user-data-fixture>`,
+to load the testing users only in the test database.
+
+After loading users in your database, use your user repository to fetch
+this user and use
+:method:`$client->loginUser() <Symfony\\Bundle\\FrameworkBundle\\KernelBrowser::loginUser>`
+to simulate a login request::
+
+    // tests/Controller/ProfileControllerTest.php
+    namespace App\Tests\Controller;
+
+    use App\Repository\UserRepository;
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+    class ProfileControllerTest extends WebTestCase
+    {
+        // ...
+
+        public function testVisitingWhileLoggedIn()
+        {
+            $client = static::createClient();
+            $userRepository = static::$container->get(UserRepository::class);
+
+            // retrieve the test user
+            $testUser = $userRepository->findOneByEmail('john.doe@example.com');
+
+            // simulate $testUser being logged in
+            $client->loginUser($testUser);
+
+            // test e.g. the profile page
+            $client->request('GET', '/profile');
+            $this->assertResponseIsSuccessful();
+            $this->assertSelectorTextContains('h1', 'Hello John!');
+        }
+    }
+
+You can pass any
+:class:`Symfony\\Component\\Security\\Core\\User\\UserInterface` instance to
+``loginUser()``. This method creates a special
+:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\TestBrowserToken` object and
+stores in the session of the test client.
+
 Accessing the Profiler Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~