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

docs: improve testing/response.rst

Author: samsonasik

user_guide_src/source/testing/response.rst

@@ -8,6 +8,7 @@ from your test cases. Usually a ``TestResponse`` will be provided for you as a r
 create your own directly using any ``ResponseInterface``:
 
 .. literalinclude:: response/001.php
+   :lines: 2-
 
 .. contents::
     :local:
@@ -28,13 +29,15 @@ request()
 You can access directly the Request object, if it was set during testing:
 
 .. literalinclude:: response/002.php
+   :lines: 2-
 
 response()
 ----------
 
 This allows you direct access to the response object:
 
 .. literalinclude:: response/003.php
+   :lines: 2-
 
 Checking Response Status
 ========================
@@ -46,27 +49,31 @@ Returns a boolean true/false based on whether the response is perceived to be "o
 a response status code in the 200 or 300's. An empty body is not considered valid, unless in redirects.
 
 .. literalinclude:: response/004.php
+   :lines: 2-
 
 assertOK()
 ----------
 
 This assertion simply uses the ``isOK()`` method to test a response. ``assertNotOK()`` is the inverse of this assertion.
 
 .. literalinclude:: response/005.php
+   :lines: 2-
 
 isRedirect()
 ------------
 
 Returns a boolean true/false based on whether the response is a redirected response.
 
 .. literalinclude:: response/006.php
+   :lines: 2-
 
 assertRedirect()
 ----------------
 
 Asserts that the Response is an instance of RedirectResponse. ``assertNotRedirect()`` is the inverse of this assertion.
 
 .. literalinclude:: response/007.php
+   :lines: 2-
 
 assertRedirectTo()
 ------------------
@@ -75,20 +82,23 @@ Asserts that the Response is an instance of RedirectResponse and the destination
 matches the uri given.
 
 .. literalinclude:: response/008.php
+   :lines: 2-
 
 getRedirectUrl()
 ----------------
 
 Returns the URL set for a RedirectResponse, or null for failure.
 
 .. literalinclude:: response/009.php
+   :lines: 2-
 
 assertStatus(int $code)
 -----------------------
 
 Asserts that the HTTP status code returned matches $code.
 
 .. literalinclude:: response/010.php
+   :lines: 2-
 
 Session Assertions
 ==================
@@ -100,13 +110,15 @@ Asserts that a value exists in the resulting session. If $value is passed, will
 matches what was specified.
 
 .. literalinclude:: response/011.php
+   :lines: 2-
 
 assertSessionMissing(string $key)
 ---------------------------------
 
 Asserts that the resulting session does not include the specified $key.
 
 .. literalinclude:: response/012.php
+   :lines: 2-
 
 Header Assertions
 =================
@@ -118,13 +130,15 @@ Asserts that a header named ``$key`` exists in the response. If ``$value`` is no
 the values match.
 
 .. literalinclude:: response/013.php
+   :lines: 2-
 
 assertHeaderMissing(string $key)
 --------------------------------
 
 Asserts that a header name ``$key`` does not exist in the response.
 
 .. literalinclude:: response/014.php
+   :lines: 2-
 
 Cookie Assertions
 =================
@@ -136,13 +150,15 @@ Asserts that a cookie named ``$key`` exists in the response. If ``$value`` is no
 the values match. You can set the cookie prefix, if needed, by passing it in as the third parameter.
 
 .. literalinclude:: response/015.php
+   :lines: 2-
 
 assertCookieMissing(string $key)
 --------------------------------
 
 Asserts that a cookie named ``$key`` does not exist in the response.
 
 .. literalinclude:: response/016.php
+   :lines: 2-
 
 assertCookieExpired(string $key, string $prefix = '')
 -----------------------------------------------------
@@ -151,6 +167,7 @@ Asserts that a cookie named ``$key`` exists, but has expired. You can set the co
 in as the second parameter.
 
 .. literalinclude:: response/017.php
+   :lines: 2-
 
 DOM Helpers
 ===========
@@ -161,14 +178,17 @@ are useful for using within assertions in your tests.
 see()
 -----
 
-The ``see()`` method checks the text on the page to see if it exists either by itself, or more specifically within
+Returns a boolean true/false based on whether the text on the page exists either
+by itself, or more specifically within
 a tag, as specified by type, class, or id:
 
 .. literalinclude:: response/018.php
+   :lines: 2-
 
 The ``dontSee()`` method is the exact opposite:
 
 .. literalinclude:: response/019.php
+   :lines: 2-
 
 seeElement()
 ------------
@@ -177,27 +197,31 @@ The ``seeElement()`` and ``dontSeeElement()`` are very similar to the previous m
 values of the elements. Instead, they simply check that the elements exist on the page:
 
 .. literalinclude:: response/020.php
+   :lines: 2-
 
 seeLink()
 ---------
 
 You can use ``seeLink()`` to ensure that a link appears on the page with the specified text:
 
 .. literalinclude:: response/021.php
+   :lines: 2-
 
 seeInField()
 ------------
 
 The ``seeInField()`` method checks for any input tags exist with the name and value:
 
 .. literalinclude:: response/022.php
+   :lines: 2-
 
 seeCheckboxIsChecked()
 ----------------------
 
 Finally, you can check if a checkbox exists and is checked with the ``seeCheckboxIsChecked()`` method:
 
 .. literalinclude:: response/023.php
+   :lines: 2-
 
 DOM Assertions
 ==============
@@ -212,20 +236,23 @@ Asserts that text/HTML is on the page, either by itself or - more specifically -
 a tag, as specified by type, class, or id:
 
 .. literalinclude:: response/024.php
+   :lines: 2-
 
 assertDontSee(string $search = null, string $element = null)
 ------------------------------------------------------------
 
 Asserts the exact opposite of the ``assertSee()`` method:
 
 .. literalinclude:: response/025.php
+   :lines: 2-
 
 assertSeeElement(string $search)
 --------------------------------
 
 Similar to ``assertSee()``, however this only checks for an existing element. It does not check for specific text:
 
 .. literalinclude:: response/026.php
+   :lines: 2-
 
 assertDontSeeElement(string $search)
 ------------------------------------
@@ -234,20 +261,23 @@ Similar to ``assertSee()``, however this only checks for an existing element tha
 specific text:
 
 .. literalinclude:: response/027.php
+   :lines: 2-
 
 assertSeeLink(string $text, string $details = null)
 ---------------------------------------------------
 
 Asserts that an anchor tag is found with matching ``$text`` as the body of the tag:
 
 .. literalinclude:: response/028.php
+   :lines: 2-
 
 assertSeeInField(string $field, string $value = null)
 -----------------------------------------------------
 
 Asserts that an input tag exists with the name and value:
 
 .. literalinclude:: response/029.php
+   :lines: 2-
 
 Working with JSON
 =================
@@ -261,19 +291,22 @@ getJSON()
 This method will return the body of the response as a JSON string:
 
 .. literalinclude:: response/030.php
+   :lines: 2-
 
 You can use this method to determine if ``$response`` actually holds JSON content:
 
 .. literalinclude:: response/031.php
+   :lines: 2-
 
 .. note:: Be aware that the JSON string will be pretty-printed in the result.
 
 assertJSONFragment(array $fragment)
 -----------------------------------
 
-Asserts that $fragment is found within the JSON response. It does not need to match the entire JSON value.
+Asserts that ``$fragment`` is found within the JSON response. It does not need to match the entire JSON value.
 
 .. literalinclude:: response/032.php
+   :lines: 2-
 
 assertJSONExact($test)
 ----------------------

user_guide_src/source/testing/response/018.php

@@ -1,10 +1,21 @@
 <?php
 
 // Check that "Hello World" is on the page
-$results->see('Hello World');
+if ($results->see('Hello World')) {
+    // ...
+}
+
 // Check that "Hello World" is within an h1 tag
-$results->see('Hello World', 'h1');
+if ($results->see('Hello World', 'h1')) {
+    // ...
+}
+
 // Check that "Hello World" is within an element with the "notice" class
-$results->see('Hello World', '.notice');
+if ($results->see('Hello World', '.notice')) {
+    // ...
+}
+
 // Check that "Hello World" is within an element with id of "title"
-$results->see('Hello World', '#title');
+if ($results->see('Hello World', '#title')) {
+    // ...
+}

user_guide_src/source/testing/response/019.php

@@ -1,6 +1,11 @@
 <?php
 
 // Checks that "Hello World" does NOT exist on the page
-$results->dontSee('Hello World');
+if ($results->dontSee('Hello World')) {
+    // ...
+}
+
 // Checks that "Hellow World" does NOT exist within any h1 tag
-$results->dontSee('Hello World', 'h1');
+if ($results->dontSee('Hello World', 'h1')) {
+    // ...
+}

user_guide_src/source/testing/response/020.php

@@ -1,8 +1,16 @@
 <?php
 
 // Check that an element with class 'notice' exists
-$results->seeElement('.notice');
+if ($results->seeElement('.notice')) {
+    // ...
+}
+
 // Check that an element with id 'title' exists
-$results->seeElement('#title');
+if ($results->seeElement('#title')) {
+    // ...
+}
+
 // Verify that an element with id 'title' does NOT exist
-$results->dontSeeElement('#title');
+if ($results->dontSeeElement('#title')) {
+    // ...
+}

user_guide_src/source/testing/response/021.php

@@ -1,6 +1,11 @@
 <?php
 
 // Check that a link exists with 'Upgrade Account' as the text::
-$results->seeLink('Upgrade Account');
+if ($results->seeLink('Upgrade Account')) {
+    // ...
+}
+
 // Check that a link exists with 'Upgrade Account' as the text, AND a class of 'upsell'
-$results->seeLink('Upgrade Account', '.upsell');
+if ($results->seeLink('Upgrade Account', '.upsell')) {
+    // ...
+}

user_guide_src/source/testing/response/022.php

@@ -1,6 +1,11 @@
 <?php
 
 // Check that an input exists named 'user' with the value 'John Snow'
-$results->seeInField('user', 'John Snow');
+if ($results->seeInField('user', 'John Snow')) {
+    // ...
+}
+
 // Check a multi-dimensional input
-$results->seeInField('user[name]', 'John Snow');
+if ($results->seeInField('user[name]', 'John Snow')) {
+    // ...
+}

user_guide_src/source/testing/response/023.php

@@ -1,6 +1,11 @@
 <?php
 
 // Check if checkbox is checked with class of 'foo'
-$results->seeCheckboxIsChecked('.foo');
+if ($results->seeCheckboxIsChecked('.foo')) {
+    // ...
+}
+
 // Check if checkbox with id of 'bar' is checked
-$results->seeCheckboxIsChecked('#bar');
+if ($results->seeCheckboxIsChecked('#bar')) {
+    // ...
+}

user_guide_src/source/testing/response/024.php

@@ -1,10 +1,13 @@
 <?php
 
-// Check that "Hello World" is on the page
+// Verify that "Hello World" is on the page
 $result->assertSee('Hello World');
-// Check that "Hello World" is within an h1 tag
+
+// Verify that "Hello World" is within an h1 tag
 $result->assertSee('Hello World', 'h1');
-// Check that "Hello World" is within an element with the "notice" class
+
+// Verify that "Hello World" is within an element with the "notice" class
 $result->assertSee('Hello World', '.notice');
-// Check that "Hello World" is within an element with id of "title"
+
+// Verify that "Hello World" is within an element with id of "title"
 $result->assertSee('Hello World', '#title');

user_guide_src/source/testing/response/025.php

@@ -1,6 +1,7 @@
 <?php
 
-// Checks that "Hello World" does NOT exist on the page
-$results->dontSee('Hello World');
-// Checks that "Hello World" does NOT exist within any h1 tag
-$results->dontSee('Hello World', 'h1');
+// Verify that "Hello World" does NOT exist on the page
+$results->assertDontSee('Hello World');
+
+// Verify that "Hello World" does NOT exist within any h1 tag
+$results->assertDontSee('Hello World', 'h1');