symfony · wouterj · Apr 7, 2019 · Apr 2, 2019 · wouterj · Apr 6, 2019
diff --git a/testing.rst b/testing.rst
@@ -204,12 +204,29 @@ component, run:
    $ composer require --dev symfony/css-selector

 Now you can use CSS selectors with the crawler. To assert that the phrase
-"Hello World" is on the page at least once, you can use this assertion::
+"Hello World" is present in the page's main title, you can use this assertion::

-    $this->assertGreaterThan(
-        0,
-        $crawler->filter('html:contains("Hello World")')->count()
-    );
+    $this->assertSelectorTextContains('html h1.title', 'Hello World');
+
+This assertion will internally call ``$crawler->filter('html h1.title')``, which allows
+you to use CSS selectors to filter any HTML element in the page and check for
+its existence, attributes, text, etc.
+
+The ``assertSelectorTextContains`` method is not a native PHPUnit assertion and is
+available thanks to the ``WebTestCase`` class.
+
+.. versionadded:: 4.3
+
+    The ``WebTestCase`` assertions were introduced in Symfony 4.3
+
+.. seealso::
+
+    Using native PHPUnit methods, the same assertion would look like this::
+
+        $this->assertGreaterThan(
+            0,
+            $crawler->filter('html h1.title:contains("Hello World")')->count()
+        );

 The crawler can also be used to interact with the page. Click on a link by first
 selecting it with the crawler using either an XPath expression or a CSS selector,

diff --git a/testing/functional_tests_assertions.rst b/testing/functional_tests_assertions.rst
@@ -0,0 +1,83 @@
+.. index::
+   single: Tests; Assertions
+
+Functional Test specific Assertions
+===================================
+
+.. versionadded:: 4.3
+
+    The shortcut methods for assertions using ``WebTestCase`` were introduced
+    in Symfony 4.3.
+
+When doing functional tests, sometimes you need to make complex assertions in
+order to check whether the ``Request``, the ``Response`` or the ``Crawler``
+contain the expected information to make your test succeed.
+
+Here is an example with plain PHPUnit::
+
+    $this->assertGreaterThan(
+        0,
+        $crawler->filter('html:contains("Hello World")')->count()
+    );
+
+Now here is the example with the assertions specific to Symfony::
+
+    $this->assertSelectorTextContains('html', 'Hello World');
+
+.. note::
+
+    These assertions only work if a request has been made with the ``Client``
+    in a test case extending the ``WebTestCase`` class.
+
+Assertions Reference
+---------------------
+
+Response
+~~~~~~~~
+
+- ``assertResponseIsSuccessful()``
+- ``assertResponseStatusCodeSame()``
+- ``assertResponseRedirects()``
+- ``assertResponseHasHeader()``
+- ``assertResponseNotHasHeader()``
+- ``assertResponseHeaderSame()``
+- ``assertResponseHeaderNotSame()``
+- ``assertResponseHasCookie()``
+- ``assertResponseNotHasCookie()``
+- ``assertResponseCookieValueSame()``
+
+Request
+~~~~~~~
+
+- ``assertRequestAttributeValueSame()``
+- ``assertRouteSame()``
+
+Browser
+~~~~~~~
+
+- ``assertBrowserHasCookie()``
+- ``assertBrowserNotHasCookie()``
+- ``assertBrowserCookieValueSame()``
+
+Crawler
+~~~~~~~
+
+- ``assertSelectorExists()``
+- ``assertSelectorNotExists()``
+- ``assertSelectorTextContains()``
+- ``assertSelectorTextSame()``
+- ``assertSelectorTextNotContains()``
+- ``assertPageTitleSame()``
+- ``assertPageTitleContains()``
+- ``assertInputValueSame()``
+- ``assertInputValueNotSame()``
+
+Troubleshooting
+---------------
+
+These assertions will not work with `symfony/panther`_ as they use the
+``Request`` and ``Response`` objects from the ``HttpFoundation``
+component, and the ``KernelBrowser`` from the ``FrameworkBundle``.
+Panther only uses the ``BrowserKit`` component.
+
+.. _`symfony/panther`: https://github.com/symfony/panther