diff --git a/testing.rst b/testing.rst index d92d71a463b..d1844bed94d 100644 --- 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 new file mode 100644 index 00000000000..63482dd046b --- /dev/null +++ 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