Merge pull request #5993 from kenjis/fix-docs-testing/response.rst

docs: improve testing/response.rst

Author: kenjis

user_guide_src/source/testing/response.rst

@@ -14,211 +14,249 @@ create your own directly using any ``ResponseInterface``:
     :depth: 2
 
 Testing the Response
-====================
+********************
 
 Whether you have received a ``TestResponse`` as a result of your tests or created one yourself,
 there are a number of new assertions that you can use in your tests.
 
 Accessing Request/Response
---------------------------
+==========================
 
-**request()**
+request()
+---------
 
 You can access directly the Request object, if it was set during testing:
 
 .. literalinclude:: response/002.php
 
-**response()**
+response()
+----------
 
 This allows you direct access to the response object:
 
 .. literalinclude:: response/003.php
 
 Checking Response Status
-------------------------
+========================
 
-**isOK()**
+isOK()
+------
 
 Returns a boolean true/false based on whether the response is perceived to be "ok". This is primarily determined by
 a response status code in the 200 or 300's. An empty body is not considered valid, unless in redirects.
 
 .. literalinclude:: response/004.php
 
-**assertOK()**
+assertOK()
+----------
 
-This assertion simply uses the **isOK()** method to test a response. **assertNotOK** is the inverse of this assertion.
+This assertion simply uses the ``isOK()`` method to test a response. ``assertNotOK()`` is the inverse of this assertion.
 
 .. literalinclude:: response/005.php
 
-**isRedirect()**
+isRedirect()
+------------
 
 Returns a boolean true/false based on whether the response is a redirected response.
 
 .. literalinclude:: response/006.php
 
-**assertRedirect()**
+assertRedirect()
+----------------
 
-Asserts that the Response is an instance of RedirectResponse. **assertNotRedirect** is the inverse of this assertion.
+Asserts that the Response is an instance of RedirectResponse. ``assertNotRedirect()`` is the inverse of this assertion.
 
 .. literalinclude:: response/007.php
 
-**assertRedirectTo()**
+assertRedirectTo()
+------------------
 
 Asserts that the Response is an instance of RedirectResponse and the destination
 matches the uri given.
 
 .. literalinclude:: response/008.php
 
-**getRedirectUrl()**
+getRedirectUrl()
+----------------
 
 Returns the URL set for a RedirectResponse, or null for failure.
 
 .. literalinclude:: response/009.php
 
-**assertStatus(int $code)**
+assertStatus(int $code)
+-----------------------
 
 Asserts that the HTTP status code returned matches $code.
 
 .. literalinclude:: response/010.php
 
 Session Assertions
-------------------
+==================
 
-**assertSessionHas(string $key, $value = null)**
+assertSessionHas(string $key, $value = null)
+--------------------------------------------
 
 Asserts that a value exists in the resulting session. If $value is passed, will also assert that the variable's value
 matches what was specified.
 
 .. literalinclude:: response/011.php
 
-**assertSessionMissing(string $key)**
+assertSessionMissing(string $key)
+---------------------------------
 
 Asserts that the resulting session does not include the specified $key.
 
 .. literalinclude:: response/012.php
 
 Header Assertions
------------------
+=================
 
-**assertHeader(string $key, $value = null)**
+assertHeader(string $key, $value = null)
+----------------------------------------
 
-Asserts that a header named **$key** exists in the response. If **$value** is not empty, will also assert that
+Asserts that a header named ``$key`` exists in the response. If ``$value`` is not empty, will also assert that
 the values match.
 
 .. literalinclude:: response/013.php
 
-**assertHeaderMissing(string $key)**
+assertHeaderMissing(string $key)
+--------------------------------
 
-Asserts that a header name **$key** does not exist in the response.
+Asserts that a header name ``$key`` does not exist in the response.
 
 .. literalinclude:: response/014.php
 
 Cookie Assertions
------------------
+=================
 
-**assertCookie(string $key, $value = null, string $prefix = '')**
+assertCookie(string $key, $value = null, string $prefix = '')
+-------------------------------------------------------------
 
-Asserts that a cookie named **$key** exists in the response. If **$value** is not empty, will also assert that
+Asserts that a cookie named ``$key`` exists in the response. If ``$value`` is not empty, will also assert that
 the values match. You can set the cookie prefix, if needed, by passing it in as the third parameter.
 
 .. literalinclude:: response/015.php
 
-**assertCookieMissing(string $key)**
+assertCookieMissing(string $key)
+--------------------------------
 
-Asserts that a cookie named **$key** does not exist in the response.
+Asserts that a cookie named ``$key`` does not exist in the response.
 
 .. literalinclude:: response/016.php
 
-**assertCookieExpired(string $key, string $prefix = '')**
+assertCookieExpired(string $key, string $prefix = '')
+-----------------------------------------------------
 
-Asserts that a cookie named **$key** exists, but has expired. You can set the cookie prefix, if needed, by passing it
+Asserts that a cookie named ``$key`` exists, but has expired. You can set the cookie prefix, if needed, by passing it
 in as the second parameter.
 
 .. literalinclude:: response/017.php
 
 DOM Helpers
------------
+===========
 
 The response you get back contains a number of helper methods to inspect the HTML output within the response. These
 are useful for using within assertions in your tests.
 
-The **see()** method checks the text on the page to see if it exists either by itself, or more specifically within
+see()
+-----
+
+The ``see()`` method checks the text on the page to see if it exists either by itself, or more specifically within
 a tag, as specified by type, class, or id:
 
 .. literalinclude:: response/018.php
 
-The **dontSee()** method is the exact opposite:
+The ``dontSee()`` method is the exact opposite:
 
 .. literalinclude:: response/019.php
 
-The **seeElement()** and **dontSeeElement()** are very similar to the previous methods, but do not look at the
+seeElement()
+------------
+
+The ``seeElement()`` and ``dontSeeElement()`` are very similar to the previous methods, but do not look at the
 values of the elements. Instead, they simply check that the elements exist on the page:
 
 .. literalinclude:: response/020.php
 
-You can use **seeLink()** to ensure that a link appears on the page with the specified text:
+seeLink()
+---------
+
+You can use ``seeLink()`` to ensure that a link appears on the page with the specified text:
 
 .. literalinclude:: response/021.php
 
-The **seeInField()** method checks for any input tags exist with the name and value:
+seeInField()
+------------
+
+The ``seeInField()`` method checks for any input tags exist with the name and value:
 
 .. literalinclude:: response/022.php
 
-Finally, you can check if a checkbox exists and is checked with the **seeCheckboxIsChecked()** method:
+seeCheckboxIsChecked()
+----------------------
+
+Finally, you can check if a checkbox exists and is checked with the ``seeCheckboxIsChecked()`` method:
 
 .. literalinclude:: response/023.php
 
 DOM Assertions
---------------
+==============
 
 You can perform tests to see if specific elements/text/etc exist with the body of the response with the following
 assertions.
 
-**assertSee(string $search = null, string $element = null)**
+assertSee(string $search = null, string $element = null)
+--------------------------------------------------------
 
 Asserts that text/HTML is on the page, either by itself or - more specifically - within
 a tag, as specified by type, class, or id:
 
 .. literalinclude:: response/024.php
 
-**assertDontSee(string $search = null, string $element = null)**
+assertDontSee(string $search = null, string $element = null)
+------------------------------------------------------------
 
-Asserts the exact opposite of the **assertSee()** method:
+Asserts the exact opposite of the ``assertSee()`` method:
 
 .. literalinclude:: response/025.php
 
-**assertSeeElement(string $search)**
+assertSeeElement(string $search)
+--------------------------------
 
-Similar to **assertSee()**, however this only checks for an existing element. It does not check for specific text:
+Similar to ``assertSee()``, however this only checks for an existing element. It does not check for specific text:
 
 .. literalinclude:: response/026.php
 
-**assertDontSeeElement(string $search)**
+assertDontSeeElement(string $search)
+------------------------------------
 
-Similar to **assertSee()**, however this only checks for an existing element that is missing. It does not check for
+Similar to ``assertSee()``, however this only checks for an existing element that is missing. It does not check for
 specific text:
 
 .. literalinclude:: response/027.php
 
-**assertSeeLink(string $text, string $details=null)**
+assertSeeLink(string $text, string $details = null)
+---------------------------------------------------
 
-Asserts that an anchor tag is found with matching **$text** as the body of the tag:
+Asserts that an anchor tag is found with matching ``$text`` as the body of the tag:
 
 .. literalinclude:: response/028.php
 
-**assertSeeInField(string $field, string $value=null)**
+assertSeeInField(string $field, string $value = null)
+-----------------------------------------------------
 
 Asserts that an input tag exists with the name and value:
 
 .. literalinclude:: response/029.php
 
 Working With JSON
------------------
+=================
 
 Responses will frequently contain JSON responses, especially when working with API methods. The following methods
 can help to test the responses.
 
-**getJSON()**
+getJSON()
+---------
 
 This method will return the body of the response as a JSON string:
 
@@ -230,19 +268,22 @@ You can use this method to determine if ``$response`` actually holds JSON conten
 
 .. note:: Be aware that the JSON string will be pretty-printed in the result.
 
-**assertJSONFragment(array $fragment)**
+assertJSONFragment(array $fragment)
+-----------------------------------
 
 Asserts that $fragment is found within the JSON response. It does not need to match the entire JSON value.
 
 .. literalinclude:: response/032.php
 
-**assertJSONExact($test)**
+assertJSONExact($test)
+----------------------
 
-Similar to **assertJSONFragment()**, but checks the entire JSON response to ensure exact matches.
+Similar to ``assertJSONFragment()``, but checks the entire JSON response to ensure exact matches.
 
 Working With XML
-----------------
+================
 
-**getXML()**
+getXML()
+--------
 
 If your application returns XML, you can retrieve it through this method.