[Testing] Reorganized "Application Tests" section

wouterj · wouterj · commit e02b52127746 · 2021-04-17T15:07:01.000+02:00
diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml
@@ -95,3 +95,4 @@ whitelist:
         - ".. _`Deploying Symfony 4 Apps on Heroku`: https://devcenter.heroku.com/articles/deploying-symfony4"
         - '.. versionadded:: 0.2' # MercureBundle
         - '.. code-block:: twig'
+        - 'End to End Tests (E2E)'
diff --git a/testing.rst b/testing.rst
@@ -15,12 +15,13 @@ Symfony integrates with an independent library called `PHPUnit`_ to give
 you a rich testing framework. This article won't cover PHPUnit itself,
 which has its own excellent `documentation`_.
 
-Before creating your first test, install PHPUnit with the following
-command:
+Before creating your first test, install ``phpunit/phpunit`` and the
+``symfony/test-pack``, which installs some other packages providing useful
+Symfony test utilities:
 
 .. code-block:: terminal
 
-    $ composer require --dev phpunit/phpunit
+    $ composer require --dev phpunit/phpunit symfony/test-pack
 
 After the library is installed, try running PHPUnit:
 
@@ -95,7 +96,9 @@ You can run tests using the ``./vendor/bin/phpunit`` command:
 .. tip::
 
     In large test suites, it can make sense to create subdirectories for
-    each type of tests (e.g. ``tests/unit/`` and ``test/functional/``).
+    each type of tests (e.g. ``tests/Unit/`` and ``test/Functional/``).
+
+.. _integration-tests:
 
 Integration Tests
 -----------------
@@ -198,7 +201,15 @@ method::
 .. tip::
 
     It is recommended to run your test with ``debug`` set to ``false`` on
-    your CI server, as it significantly improves test performance.
+    your CI server, as it significantly improves test performance. This
+    disables clearing the cache. If your tests don't run in a clean
+    environment each time, you have to manually clear it using for instance
+    this code in ``tests/bootstrap.php``::
+
+        // ...
+
+        // ensure a fresh cache when debug mode is disabled
+        (new \Symfony\Component\Filesystem\Filesystem())->remove(__DIR__.'/../var/cache/test');
 
 Customizing Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -243,7 +254,7 @@ the container is stored in ``self::$container``::
     {
         public function testSomething()
         {
-            // boot the Symfony kernel
+            // (1) boot the Symfony kernel
             self::bootKernel();
 
             // (2) use self::$container to access the service container
@@ -267,6 +278,8 @@ It gives you access to both the public services and the non-removed
     are not used by any other services), you need to declare those private
     services as public in the ``config/services_test.yaml`` file.
 
+.. _testing-databases:
+
 Configuring a Database for Tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -410,21 +423,35 @@ have a very specific workflow:
 #. Test the response;
 #. Rinse and repeat.
 
-Before creating your first test, install the ``symfony/test-pack`` which
-requires multiple packages providing some of the utilities used in the
-tests:
-
-.. code-block:: terminal
+.. note::
 
-    $ composer require --dev symfony/test-pack
+    The tools used in this section can be installed via the ``symfony/test-pack``,
+    use ``composer require symfony/test-pack`` if you haven't done so already.
 
 Write Your First Application Test
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Application tests are PHP files that typically live in the ``tests/Controller``
-directory of your application. If you want to test the pages handled by your
-``PostController`` class, start by creating a new ``PostControllerTest.php``
-file that extends a special ``WebTestCase`` class::
+directory of your application. They often extend
+:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase`. This class
+adds special logic on top of the ``KernelTestCase``. You can read more
+about that in the above :ref:`section on integration tests <integration-tests>`.
+
+If you want to test the pages handled by your
+``PostController`` class, start by creating a new ``PostControllerTest``
+using the ``make:test`` command of the `SymfonyMakerBundle`_:
+
+.. code-block:: terminal
+
+    $ php bin/console make:test
+
+     Which test type would you like?:
+     > WebTestCase
+
+     The name of the test class (e.g. BlogPostTest):
+     > Controller\PostControllerTest
+
+This creates the following test class::
 
     // tests/Controller/PostControllerTest.php
     namespace App\Tests\Controller;
@@ -433,87 +460,36 @@ file that extends a special ``WebTestCase`` class::
 
     class PostControllerTest extends WebTestCase
     {
-        public function testShowPost()
+        public function testSomething(): void
         {
+            // This calls KernelTestCase::bootKernel(), and creates a
+            // "client" that is acting as the browser
             $client = static::createClient();
 
-            $client->request('GET', '/post/hello-world');
+            // Request a specific page
+            $crawler = $client->request('GET', '/');
 
-            $this->assertEquals(200, $client->getResponse()->getStatusCode());
+            // Validate a successful response and some content
+            $this->assertResponseIsSuccessful();
+            $this->assertSelectorTextContains('h1', 'Hello World');
         }
     }
 
-In the above example, you validated that the HTTP response was successful. The
-next step is to validate that the page actually contains the expected content.
-The ``createClient()`` method returns a client, which is like a browser that
-you'll use to crawl your site::
+In the above example, the test validates that the HTTP response was successful
+and the request body contains a ``<h1>`` tag with ``"Hello world"``. The
+``createClient()`` method also returns a client, which is like a browser
+that you can use to crawl your site::
 
     $crawler = $client->request('GET', '/post/hello-world');
 
+    // for instance, count the number of ``.comment`` elements on the page
+    $this->assertCount(4, $crawler->filter('.comment'));
+
 The ``request()`` method (read
 :ref:`more about the request method <testing-request-method-sidebar>`)
 returns a :class:`Symfony\\Component\\DomCrawler\\Crawler` object which can
 be used to select elements in the response, click on links and submit forms.
 
-Useful Assertions
-~~~~~~~~~~~~~~~~~
-
-To get you started faster, here is a list of the most common and
-useful test assertions::
-
-    use Symfony\Component\HttpFoundation\Response;
-
-    // ...
-
-    // asserts that there is at least one h2 tag with the class "subtitle"
-    // the third argument is an optional message shown on failed tests
-    $this->assertGreaterThan(0, $crawler->filter('h2.subtitle')->count(),
-        'There is at least one subtitle'
-    );
-
-    // asserts that there are exactly 4 h2 tags on the page
-    $this->assertCount(4, $crawler->filter('h2'));
-
-    // asserts that the "Content-Type" header is "application/json"
-    $this->assertResponseHeaderSame('Content-Type', 'application/json');
-    // equivalent to:
-    $this->assertTrue($client->getResponse()->headers->contains(
-        'Content-Type', 'application/json'
-    ));
-
-    // asserts that the response content contains a string
-    $this->assertContains('foo', $client->getResponse()->getContent());
-    // ...or matches a regex
-    $this->assertRegExp('/foo(bar)?/', $client->getResponse()->getContent());
-
-    // asserts that the response status code is 2xx
-    $this->assertResponseIsSuccessful();
-    // equivalent to:
-    $this->assertTrue($client->getResponse()->isSuccessful());
-
-    // asserts that the response status code is 404 Not Found
-    $this->assertTrue($client->getResponse()->isNotFound());
-
-    // asserts a specific status code
-    $this->assertResponseStatusCodeSame(201);
-    // HTTP status numbers are available as constants too:
-    // e.g. 201 === Symfony\Component\HttpFoundation\Response::HTTP_CREATED
-    // equivalent to:
-    $this->assertEquals(201, $client->getResponse()->getStatusCode());
-
-    // asserts that the response is a redirect to /demo/contact
-    $this->assertResponseRedirects('/demo/contact');
-    // equivalent to:
-    $this->assertTrue($client->getResponse()->isRedirect('/demo/contact'));
-    // ...or check that the response is a redirect to any URL
-    $this->assertResponseRedirects();
-
-.. versionadded:: 4.3
-
-    The ``assertResponseHeaderSame()``, ``assertResponseIsSuccessful()``,
-    ``assertResponseStatusCodeSame()``, ``assertResponseRedirects()`` and other
-    related methods were introduced in Symfony 4.3.
-
 Working with the Test Client
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -527,41 +503,9 @@ returns a ``Crawler`` instance.
 
 .. tip::
 
-    Hardcoding the request URLs is a best practice for application tests. If the
-    test generates URLs using the Symfony router, it won't detect any change
-    made to the application URLs which may impact the end users.
-
-.. _testing-request-method-sidebar:
-
-.. sidebar:: More about the ``request()`` Method:
-
-    The full signature of the ``request()`` method is::
-
-        request(
-            $method,
-            $uri,
-            array $parameters = [],
-            array $files = [],
-            array $server = [],
-            $content = null,
-            $changeHistory = true
-        )
-
-    The ``server`` array is the raw values that you'd expect to normally
-    find in the PHP `$_SERVER`_ superglobal. For example, to set the
-    ``Content-Type`` and ``Referer`` HTTP headers, you'd pass the following (mind
-    the ``HTTP_`` prefix for non standard headers)::
-
-        $client->request(
-            'GET',
-            '/post/hello-world',
-            [],
-            [],
-            [
-                'CONTENT_TYPE' => 'application/json',
-                'HTTP_REFERER' => '/foo/bar',
-            ]
-        );
+    Hardcoding the request URLs is a best practice for application tests.
+    If the test generates URLs using the Symfony router, it won't detect
+    any change made to the application URLs which may impact the end users.
 
 Use the crawler to find DOM elements in the response. These elements can then
 be used to click on links and submit forms::
@@ -622,6 +566,38 @@ script::
 
     $client->insulate();
 
+.. _testing-request-method-sidebar:
+
+.. sidebar:: More about the ``request()`` Method:
+
+    The full signature of the ``request()`` method is::
+
+        request(
+            $method,
+            $uri,
+            array $parameters = [],
+            array $files = [],
+            array $server = [],
+            $content = null,
+            $changeHistory = true
+        )
+
+    The ``server`` array is the raw values that you'd expect to normally
+    find in the PHP `$_SERVER`_ superglobal. For example, to set the
+    ``Content-Type`` and ``Referer`` HTTP headers, you'd pass the following (mind
+    the ``HTTP_`` prefix for non standard headers)::
+
+        $client->request(
+            'GET',
+            '/post/hello-world',
+            [],
+            [],
+            [
+                'CONTENT_TYPE' => 'application/json',
+                'HTTP_REFERER' => '/foo/bar',
+            ]
+        );
+
 AJAX Requests
 .............
 
@@ -757,6 +733,65 @@ to be reported by PHPUnit::
 
     $client->catchExceptions(false);
 
+Useful Assertions
+~~~~~~~~~~~~~~~~~
+
+To get you started faster, here is a list of the most common and
+useful test assertions::
+
+    use Symfony\Component\HttpFoundation\Response;
+
+    // ...
+
+    // asserts that there is at least one h2 tag with the class "subtitle"
+    // the third argument is an optional message shown on failed tests
+    $this->assertGreaterThan(0, $crawler->filter('h2.subtitle')->count(),
+        'There is at least one subtitle'
+    );
+
+    // asserts that there are exactly 4 h2 tags on the page
+    $this->assertCount(4, $crawler->filter('h2'));
+
+    // asserts that the "Content-Type" header is "application/json"
+    $this->assertResponseHeaderSame('Content-Type', 'application/json');
+    // equivalent to:
+    $this->assertTrue($client->getResponse()->headers->contains(
+        'Content-Type', 'application/json'
+    ));
+
+    // asserts that the response content contains a string
+    $this->assertContains('foo', $client->getResponse()->getContent());
+    // ...or matches a regex
+    $this->assertRegExp('/foo(bar)?/', $client->getResponse()->getContent());
+
+    // asserts that the response status code is 2xx
+    $this->assertResponseIsSuccessful();
+    // equivalent to:
+    $this->assertTrue($client->getResponse()->isSuccessful());
+
+    // asserts that the response status code is 404 Not Found
+    $this->assertTrue($client->getResponse()->isNotFound());
+
+    // asserts a specific status code
+    $this->assertResponseStatusCodeSame(201);
+    // HTTP status numbers are available as constants too:
+    // e.g. 201 === Symfony\Component\HttpFoundation\Response::HTTP_CREATED
+    // equivalent to:
+    $this->assertEquals(201, $client->getResponse()->getStatusCode());
+
+    // asserts that the response is a redirect to /demo/contact
+    $this->assertResponseRedirects('/demo/contact');
+    // equivalent to:
+    $this->assertTrue($client->getResponse()->isRedirect('/demo/contact'));
+    // ...or check that the response is a redirect to any URL
+    $this->assertResponseRedirects();
+
+.. versionadded:: 4.3
+
+    The ``assertResponseHeaderSame()``, ``assertResponseIsSuccessful()``,
+    ``assertResponseStatusCodeSame()``, ``assertResponseRedirects()`` and other
+    related methods were introduced in Symfony 4.3.
+
 .. index::
    single: Tests; Crawler
 
@@ -988,10 +1023,10 @@ their type::
         $client->submit($form, [], ['HTTP_ACCEPT_LANGUAGE' => 'es']);
         $client->submitForm($button, [], 'POST', ['HTTP_ACCEPT_LANGUAGE' => 'es']);
 
-End to End Tests (E2E)
-----------------------
-
 .. TODO
+    End to End Tests (E2E)
+    ----------------------
+
     * panther
     * testing javascript
     * UX or form collections as example?
@@ -1042,8 +1077,8 @@ configuration adds tests from a custom ``lib/tests`` directory:
         <!-- ... -->
     </phpunit>
 
-To include other directories in the code coverage, also edit the ``<filter>``
-section:
+To include other directories in the `code coverage analysis`, also edit the
+``<filter>`` section:
 
 .. code-block:: xml
 
@@ -1078,6 +1113,8 @@ Learn more
 .. _`documentation`: https://phpunit.readthedocs.io/
 .. _`Writing Tests for PHPUnit`: https://phpunit.readthedocs.io/en/stable/writing-tests-for-phpunit.html
 .. _`unit test`: https://en.wikipedia.org/wiki/Unit_testing
+.. _`DAMADoctrineTestBundle`: https://github.com/dmaicher/doctrine-test-bundle
+.. _`DoctrineFixturesBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
 .. _`$_SERVER`: https://www.php.net/manual/en/reserved.variables.server.php
 .. _`SymfonyMakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
 .. _`code coverage analysis`: https://phpunit.readthedocs.io/en/9.1/code-coverage-analysis.html
diff --git a/testing/database.rst b/testing/database.rst
