diff --git a/guides/assertion-system.rst b/guides/assertion-system.rst new file mode 100644 index 0000000..3c3784b --- /dev/null +++ b/guides/assertion-system.rst @@ -0,0 +1,367 @@ +Assertion system +================ + +The ``\Behat\Mink\WebAssert`` class provides a set of assertions. There are assertions +about the address of the page, the cookies, the status code, the response headers, +the content of the page, the page elements... + +.. note:: + + If an assertion evaluates to false, an exception ``Behat\Mink\Exception\ExpectationException`` + is thrown. + +Mink initialisation +------------------- + +.. code-block:: php + + // Choose a Mink driver. + $driver = new \Behat\Mink\Driver\GoutteDriver(); + $session = new \Behat\Mink\Session($driver); + $mink = new \Behat\Mink\Mink(array('goutte' => $session)); + $mink->setDefaultSessionName('goutte'); + +Checking address +---------------- + +``WebAssert::addressEquals`` + Checks that current session address is equals to provided one. + +``WebAssert::addressNotEquals`` + Checks that current session address is not equals to provided one. + +.. code-block:: php + + $mink->getSession()->visit('http://exemple.com'); + + $mink->assertSession()->addressEquals('http://example.com/'); + $mink->assertSession()->addressEquals('/'); + + $mink->assertSession()->addressNotEquals('http://example.com/not_found'); + $mink->assertSession()->addressNotEquals('/not_found'); + +``WebAssert::addressMatches`` + Checks that current session address matches regex. + +.. code-block:: php + + $mink->getSession()->visit('http://example.com/script.php/sub/url/foo/bar'); + + $mink->assertSession()->addressMatches('/sub.*bar/'); + +.. caution:: + Webassert compare only the path and the fragment (after the hashmark #). The scheme, + the host, the query (after the question mark ?) are not taken into account. + + These examples didn't throw exception: + + .. code-block:: php + + $mink->getSession()->visit('http://example.com'); + // different scheme + $mink->assertSession()->addressEquals('https://example.com'); + // different host + $mink->assertSession()->addressEquals('https://another.com'); + + + $mink->getSession()->visit('http://example.com/script.php/sub/url?param=true#webapp/nav'); + // Without query string + $mink->assertSession()->addressEquals('http://examyyyyyple.com/sub/url#webapp/nav'); + +Checking cookie +--------------- + +``WebAssert::cookieExists`` + Checks that specified cookie exists. + +``WebAssert::cookieEquals`` + Checks that specified cookie exists and its value. + +.. code-block:: php + + $mink->assertSession()->cookieExists('cookie_name'); + $mink->assertSession()->cookieEquals('cookie_name', 'foo_value'); + +Checking status code +-------------------- + +``WebAssert::statusCodeEquals`` + Checks that current response code equals to provided one. + +``WebAssert::statusCodeNotEquals`` + Checks that current response code not equals to provided one. + +.. code-block:: php + + $mink->assertSession()->statusCodeEquals(200); + $mink->assertSession()->statusCodeNotEquals(500); + +.. note:: + + See the :ref:`driver-feature-support` to see which driver supports this feature. + +Checking response headers +------------------------- + +``WebAssert::responseHeaderEquals`` + Checks that current response header equals value. + +``WebAssert::responseHeaderNotEquals`` + Checks that current response header does not equal value. + +``WebAssert::responseHeaderContains`` + Checks that current response header contains value. + +``WebAssert::responseHeaderNotContains`` + Checks that current response header does not contain value. + +.. code-block:: php + + $mink->assertSession()->responseHeaderEquals('Content-Type', 'text/html;charset=utf-8'); + $mink->assertSession()->responseHeaderNotEquals('Content-Type', 'application/json'); + $mink->assertSession()->responseHeaderContains('Content-Type', 'charset=utf-8'); + $mink->assertSession()->responseHeaderNotContains('Content-Type', 'application/json'); + +``WebAssert::responseHeaderMatches`` + Checks that current response header matches regex. + +``WebAssert::responseHeaderNotMatches`` + Checks that current response header does not match regex. + +.. code-block:: php + + $mink->assertSession()->responseHeaderMatches('Content-Type', '/text.*charset.*/'); + $mink->assertSession()->responseHeaderNotMatches('Content-Type', '/application.*charset.*/'); + +.. note:: + + See the :ref:`driver-feature-support` to see which driver supports this feature. + +Checking response text content +------------------------------ + +WebAssert can checks the text content of current page. The comparison is case-insensitive. + +``WebAssert::pageTextContains`` + Checks that current page contains text. + +``WebAssert::pageTextNotContains`` + Checks that current page does not contains text. + +.. code-block:: php + + $mink->assertSession()->pageTextContains('Example'); + $mink->assertSession()->pageTextNotContains('Examplefoobar'); + +``WebAssert::pageTextMatches`` + Checks that current page text matches regex. + +``WebAssert::pageTextNotMatches`` + Checks that current page text does not matches regex. + +.. code-block:: php + + $mink->assertSession()->pageTextMatches('/Example/'); + $mink->assertSession()->pageTextNotMatches('/Examplefoobar/'); + +Checking response HTML content +------------------------------ + +WebAssert can checks the HTML content of current page. The comparison is case-insensitive. + +``WebAssert::responseContains`` + Checks that page HTML (response content) contains text. + +``WebAssert::responseNotContains`` + Checks that page HTML (response content) does not contains text. + +.. code-block:: php + + $mink->assertSession()->responseContains('

Example Domain

'); + $mink->assertSession()->responseNotContains('

Example Domain

'); + +``WebAssert::responseMatches`` + Checks that page HTML (response content) matches regex. + +``WebAssert::responseNotMatches`` + Checks that page HTML (response content) does not matches regex. + +.. code-block:: php + + $mink->assertSession()->responseMatches('/

Example.*<\/h1>/'); + $mink->assertSession()->responseNotMatches('/

ExampleFooBar.*<\/h1>/'); + +Checking elements +----------------- + +``WebAssert::element*`` supports same :ref:`selectors ` that the +``ElementInterface::find`` and ``ElementInterface::findAll`` methods. + +``WebAssert::elementsCount`` + Checks that there is specified number of specific elements on the page. + +.. code-block:: php + + $mink->assertSession()->elementsCount('css', 'h1', 1); + +``WebAssert::elementExists`` + Checks that specific element exists on the current page. + +.. code-block:: php + + $titleNodeElement = $mink->assertSession()->elementExists('css', 'h1'); + +``WebAssert::elementNotExists`` + Checks that specific element does not exists on the current page. + +.. code-block:: php + + $mink->assertSession()->elementNotExists('css', 'h5'); + +``WebAssert::elementTextContains`` + Checks that specific element contains text. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->elementTextContains('css', 'h1', 'Example Domain'); + +``WebAssert::elementTextNotContains`` + Checks that specific element does not contains text. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->elementTextNotContains('css', 'h1', 'ExampleFooBar'); + +``WebAssert::elementContains`` + Checks that specific element contains HTML. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->elementContains('css', 'div', '

Example Domain

'); + +``WebAssert::elementNotContains`` + Checks that specific element does not contains HTML. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->elementNotContains('css', 'div', '

ExampleFooBar

'); + +``Webassert::elementAttributeExists`` + Checks that an attribute exists in an element. + +.. code-block:: php + + $mink->assertSession()->elementAttributeExists('css', 'a', 'href'); + +``Webassert::elementAttributeContains`` + Checks that an attribute of a specific elements contains text. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->elementAttributeContains('css', 'a', 'href', 'http://'); + +``Webassert::elementAttributeNotContains`` + Checks that an attribute of a specific elements does not contain text. + +.. code-block:: php + + $mink->assertSession()->elementAttributeNotContains('css', 'a', 'href', 'https://'); + +All ``Webassert::field*`` use the :ref:`field named selector `. + +``Webassert::fieldExists`` + Checks that specific field exists on the current page. + +.. code-block:: php + + $mink->assertSession()->fieldExists('username'); + +``Webassert::fieldNotExists`` + Checks that specific field does not exists on the current page. + +.. code-block:: php + + $mink->assertSession()->fieldNotExists('not_exists'); + +``Webassert::fieldValueEquals`` + Checks that specific field have provided value. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->fieldValueEquals('username', 'foo'); + +``Webassert::fieldValueNotEquals`` + Checks that specific field have provided value. The comparison is case-insensitive. + +.. code-block:: php + + $mink->assertSession()->fieldValueEquals('username', 'foo'); + +All ``Webassert::checkbox*`` use the :ref:`checkbox named selector `. + +``Webassert::checkboxChecked`` + Checks that specific checkbox is checked. + +.. code-block:: php + + $mink->assertSession()->checkboxChecked('remember_me'); + +``Webassert::checkboxNotChecked`` + Checks that specific checkbox is unchecked. + +.. code-block:: php + + $mink->assertSession()->checkboxNotChecked('remember_me'); + +Nested Traversing +----------------- + +Every ``WebAssert::*Exists`` method return a ``Behat\Mink\Element\NodeElement`` +(Except of course ``WebAssert::*NotExists`` methods). + +``WebAssert::elementsCount``, ``WebAssert::elementExists``, ``WebAssert::elementNotExists``, +``Webassert::field*``, ``Webassert::checkbox*``methods support an ``ElementInterface`` +argument in order to not search on all the page but only in an element of the page. + +So, instead of that: + +.. code-block:: php + + $registerForm = $page->find('css', 'form.register'); + + if (null === $registerForm) { + throw new \Exception('The element is not found'); + } + + $field = $registerForm->findField('Email'); + + if (null === $field) { + throw new \Exception('The element is not found'); + } + + $field->setValue('foo@example.com'); + +you can do: + +.. code-block:: php + + // Throw exception when not found instead of returning null. + $registerForm = $mink->assertSession()->elementExists('css', 'form.register'); + + $field = $mink->assertSession()->fieldExists('Email', $registerForm); + + $field->setValue('foo@example.com'); + +This can improve code readability or avoid having a fatal error in method chaining. + +Webassert and multisessions +--------------------------- + +You could use an another session by calling ``assertSession`` with a session name +or an instance of ``\Behat\Mink\Session``. + +.. code-block:: php + + $mink->assertSession()->elementExists('css', 'form.register'); + $mink->assertSession('goutte')->elementExists('css', 'form.register'); + $mink->assertSession($mink->getSession('goutte'))->elementExists('css', 'form.register'); diff --git a/index.rst b/index.rst index 57b6351..6c084d2 100644 --- a/index.rst +++ b/index.rst @@ -74,6 +74,7 @@ Learn Mink with the topical guides: guides/interacting-with-pages guides/drivers guides/managing-sessions + guides/assertion-system contributing Testing Tools Integration