Document new Symfony assertions (#208)

Author: TavoNiievez

src/Codeception/Module/Symfony/BrowserAssertionsTrait.php

@@ -25,6 +25,11 @@ trait BrowserAssertionsTrait
 {
     /**
      * Asserts that the given cookie in the test client is set to the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertBrowserCookieValueSame('cookie_name', 'expected_value');
+     * ```
      */
     public function assertBrowserCookieValueSame(string $name, string $expectedValue, bool $raw = false, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -35,6 +40,11 @@ public function assertBrowserCookieValueSame(string $name, string $expectedValue
     /**
      * Asserts that the test client has the specified cookie set.
      * This indicates that the cookie was set by any response during the test.
+     *
+     * ```
+     * <?php
+     * $I->assertBrowserHasCookie('cookie_name');
+     * ```
      */
     public function assertBrowserHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -44,6 +54,11 @@ public function assertBrowserHasCookie(string $name, string $path = '/', ?string
     /**
      * Asserts that the test client does not have the specified cookie set.
      * This indicates that the cookie was not set by any response during the test.
+     *
+     * ```php
+     * <?php
+     * $I->assertBrowserNotHasCookie('cookie_name');
+     * ```
      */
     public function assertBrowserNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -52,6 +67,11 @@ public function assertBrowserNotHasCookie(string $name, string $path = '/', ?str
 
     /**
      * Asserts that the specified request attribute matches the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertRequestAttributeValueSame('attribute_name', 'expected_value');
+     * ```
      */
     public function assertRequestAttributeValueSame(string $name, string $expectedValue, string $message = ''): void
     {
@@ -60,6 +80,11 @@ public function assertRequestAttributeValueSame(string $name, string $expectedVa
 
     /**
      * Asserts that the specified response cookie is present and matches the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseCookieValueSame('cookie_name', 'expected_value');
+     * ```
      */
     public function assertResponseCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -69,6 +94,11 @@ public function assertResponseCookieValueSame(string $name, string $expectedValu
 
     /**
      * Asserts that the response format matches the expected format. This checks the format returned by the `Response::getFormat()` method.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseFormatSame('json');
+     * ```
      */
     public function assertResponseFormatSame(?string $expectedFormat, string $message = ''): void
     {
@@ -77,6 +107,11 @@ public function assertResponseFormatSame(?string $expectedFormat, string $messag
 
     /**
      * Asserts that the specified cookie is present in the response. Optionally, it can check for a specific cookie path or domain.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseHasCookie('cookie_name');
+     * ```
      */
     public function assertResponseHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -86,6 +121,11 @@ public function assertResponseHasCookie(string $name, string $path = '/', ?strin
     /**
      * Asserts that the specified header is available in the response.
      * For example, use `assertResponseHasHeader('content-type');`.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseHasHeader('content-type');
+     * ```
      */
     public function assertResponseHasHeader(string $headerName, string $message = ''): void
     {
@@ -95,6 +135,11 @@ public function assertResponseHasHeader(string $headerName, string $message = ''
     /**
      * Asserts that the specified header does not contain the expected value in the response.
      * For example, use `assertResponseHeaderNotSame('content-type', 'application/octet-stream');`.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseHeaderNotSame('content-type', 'application/json');
+     * ```
      */
     public function assertResponseHeaderNotSame(string $headerName, string $expectedValue, string $message = ''): void
     {
@@ -104,6 +149,11 @@ public function assertResponseHeaderNotSame(string $headerName, string $expected
     /**
      * Asserts that the specified header contains the expected value in the response.
      * For example, use `assertResponseHeaderSame('content-type', 'application/octet-stream');`.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseHeaderSame('content-type', 'application/json');
+     * ```
      */
     public function assertResponseHeaderSame(string $headerName, string $expectedValue, string $message = ''): void
     {
@@ -112,6 +162,11 @@ public function assertResponseHeaderSame(string $headerName, string $expectedVal
 
     /**
      * Asserts that the response was successful (HTTP status code is in the 2xx range).
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseIsSuccessful();
+     * ```
      */
     public function assertResponseIsSuccessful(string $message = '', bool $verbose = true): void
     {
@@ -120,6 +175,11 @@ public function assertResponseIsSuccessful(string $message = '', bool $verbose =
 
     /**
      * Asserts that the response is unprocessable (HTTP status code is 422).
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseIsUnprocessable();
+     * ```
      */
     public function assertResponseIsUnprocessable(string $message = '', bool $verbose = true): void
     {
@@ -128,6 +188,11 @@ public function assertResponseIsUnprocessable(string $message = '', bool $verbos
 
     /**
      * Asserts that the specified cookie is not present in the response. Optionally, it can check for a specific cookie path or domain.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseNotHasCookie('cookie_name');
+     * ```
      */
     public function assertResponseNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
     {
@@ -136,7 +201,11 @@ public function assertResponseNotHasCookie(string $name, string $path = '/', ?st
 
     /**
      * Asserts that the specified header is not available in the response.
-     * For example, use `assertResponseNotHasHeader('content-type');`.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseNotHasHeader('content-type');
+     * ```
      */
     public function assertResponseNotHasHeader(string $headerName, string $message = ''): void
     {
@@ -146,6 +215,12 @@ public function assertResponseNotHasHeader(string $headerName, string $message =
     /**
      * Asserts that the response is a redirect. Optionally, you can check the target location and status code.
      * The expected location can be either an absolute or a relative path.
+     *
+     * ```php
+     * <?php
+     * // Check that '/admin' redirects to '/login' with status code 302
+     * $I->assertResponseRedirects('/login', 302);
+     * ```
      */
     public function assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '', bool $verbose = true): void
     {
@@ -165,6 +240,11 @@ public function assertResponseRedirects(?string $expectedLocation = null, ?int $
 
     /**
      * Asserts that the response status code matches the expected code.
+     *
+     * ```php
+     * <?php
+     * $I->assertResponseStatusCodeSame(200);
+     * ```
      */
     public function assertResponseStatusCodeSame(int $expectedCode, string $message = '', bool $verbose = true): void
     {
@@ -173,6 +253,11 @@ public function assertResponseStatusCodeSame(int $expectedCode, string $message
 
     /**
      * Asserts the request matches the given route and optionally route parameters.
+     *
+     * ```php
+     * <?php
+     * $I->assertRouteSame('profile', ['id' => 123]);
+     * ```
      */
     public function assertRouteSame(string $expectedRoute, array $parameters = [], string $message = ''): void {
         $request = $this->getClient()->getRequest();

src/Codeception/Module/Symfony/DomCrawlerAssertionsTrait.php

@@ -15,6 +15,11 @@ trait DomCrawlerAssertionsTrait
 {
     /**
      * Asserts that the checkbox with the given name is checked.
+     *
+     * ```php
+     * <?php
+     * $I->assertCheckboxChecked('agree_terms');
+     * ```
      */
     public function assertCheckboxChecked(string $fieldName, string $message = ''): void
     {
@@ -23,6 +28,11 @@ public function assertCheckboxChecked(string $fieldName, string $message = ''):
 
     /**
      * Asserts that the checkbox with the given name is not checked.
+     *
+     * ```php
+     * <?php
+     * $I->assertCheckboxNotChecked('subscribe');
+     * ```
      */
     public function assertCheckboxNotChecked(string $fieldName, string $message = ''): void
     {
@@ -33,6 +43,11 @@ public function assertCheckboxNotChecked(string $fieldName, string $message = ''
 
     /**
      * Asserts that the value of the form input with the given name does not equal the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertInputValueNotSame('username', 'admin');
+     * ```
      */
     public function assertInputValueNotSame(string $fieldName, string $expectedValue, string $message = ''): void
     {
@@ -44,6 +59,11 @@ public function assertInputValueNotSame(string $fieldName, string $expectedValue
 
     /**
      * Asserts that the value of the form input with the given name equals the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertInputValueSame('username', 'johndoe');
+     * ```
      */
     public function assertInputValueSame(string $fieldName, string $expectedValue, string $message = ''): void
     {
@@ -56,6 +76,11 @@ public function assertInputValueSame(string $fieldName, string $expectedValue, s
 
     /**
      * Asserts that the `<title>` element contains the given title.
+     *
+     * ```php
+     * <?php
+     * $I->assertPageTitleContains('Welcome');
+     * ```
      */
     public function assertPageTitleContains(string $expectedTitle, string $message = ''): void
     {
@@ -64,6 +89,11 @@ public function assertPageTitleContains(string $expectedTitle, string $message =
 
     /**
      * Asserts that the `<title>` element equals the given title.
+     *
+     * ```php
+     * <?php
+     * $I->assertPageTitleSame('Home Page');
+     * ```
      */
     public function assertPageTitleSame(string $expectedTitle, string $message = ''): void
     {
@@ -72,6 +102,11 @@ public function assertPageTitleSame(string $expectedTitle, string $message = '')
 
     /**
      * Asserts that the given selector matches at least one element in the response.
+     *
+     * ```php
+     * <?php
+     * $I->assertSelectorExists('.main-content');
+     * ```
      */
     public function assertSelectorExists(string $selector, string $message = ''): void
     {
@@ -80,6 +115,11 @@ public function assertSelectorExists(string $selector, string $message = ''): vo
 
     /**
      * Asserts that the given selector does not match at least one element in the response.
+     *
+     * ```php
+     * <?php
+     * $I->assertSelectorNotExists('.error');
+     * ```
      */
     public function assertSelectorNotExists(string $selector, string $message = ''): void
     {
@@ -88,6 +128,11 @@ public function assertSelectorNotExists(string $selector, string $message = ''):
 
     /**
      * Asserts that the first element matching the given selector contains the expected text.
+     *
+     * ```php
+     * <?php
+     * $I->assertSelectorTextContains('h1', 'Dashboard');
+     * ```
      */
     public function assertSelectorTextContains(string $selector, string $text, string $message = ''): void
     {
@@ -97,6 +142,11 @@ public function assertSelectorTextContains(string $selector, string $text, strin
 
     /**
      * Asserts that the first element matching the given selector does not contain the expected text.
+     *
+     * ```php
+     * <?php
+     * $I->assertSelectorTextNotContains('p', 'error');
+     * ```
      */
     public function assertSelectorTextNotContains(string $selector, string $text, string $message = ''): void
     {
@@ -106,6 +156,11 @@ public function assertSelectorTextNotContains(string $selector, string $text, st
 
     /**
      * Asserts that the text of the first element matching the given selector equals the expected text.
+     *
+     * ```php
+     * <?php
+     * $I->assertSelectorTextSame('h1', 'Dashboard');
+     * ```
      */
     public function assertSelectorTextSame(string $selector, string $text, string $message = ''): void
     {

src/Codeception/Module/Symfony/FormAssertionsTrait.php

@@ -14,6 +14,11 @@ trait FormAssertionsTrait
 {
     /**
      * Asserts that value of the field of the first form matching the given selector does equal the expected value.
+     *
+     * ```php
+     * <?php
+     * $I->assertFormValue('#loginForm', 'username', 'john_doe');
+     * ```
      */
     public function assertFormValue(string $formSelector, string $fieldName, string $value, string $message = ''): void
     {
@@ -25,7 +30,12 @@ public function assertFormValue(string $formSelector, string $fieldName, string
     }
 
     /**
-     * Asserts that value of the field of the first form matching the given selector does equal the expected value.
+     * Asserts that the field of the first form matching the given selector does not have a value.
+     *
+     * ```php
+     * <?php
+     * $I->assertNoFormValue('#registrationForm', 'middle_name');
+     * ```
      */
     public function assertNoFormValue(string $formSelector, string $fieldName, string $message = ''): void
     {
@@ -128,15 +138,14 @@ public function seeFormErrorMessage(string $field, ?string $message = null): voi
      * If you want to specify the error messages, you can do so
      * by sending an associative array instead, with the key being
      * the name of the field and the error message the value.
-     *
      * This method will validate that the expected error message
      * is contained in the actual error message, that is,
      * you can specify either the entire error message or just a part of it:
      *
      * ```php
      * <?php
      * $I->seeFormErrorMessages([
-     *     'address'   => 'The address is too long'
+     *     'address'   => 'The address is too long',
      *     'telephone' => 'too short', // the full error message is 'The telephone is too short'
      * ]);
      * ```
@@ -191,4 +200,4 @@ protected function grabFormCollector(string $function): FormDataCollector
     {
         return $this->grabCollector('form', $function);
     }
-}
+}