Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 8e5cfa9

Browse files
TavoNiievezTavoNiievez
committedMar 24, 2025·
Document new Symfony assertions
1 parent 12fdf09 commit 8e5cfa9

File tree

5 files changed

+225
-15
lines changed

5 files changed

+225
-15
lines changed
 

‎src/Codeception/Module/Symfony/BrowserAssertionsTrait.php

+85-1
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ trait BrowserAssertionsTrait
2525
{
2626
/**
2727
* Asserts that the given cookie in the test client is set to the expected value.
28+
*
29+
* ```php
30+
* <?php
31+
* $I->assertBrowserCookieValueSame('cookie_name', 'expected_value');
32+
* ```
2833
*/
2934
public function assertBrowserCookieValueSame(string $name, string $expectedValue, bool $raw = false, string $path = '/', ?string $domain = null, string $message = ''): void
3035
{
@@ -35,6 +40,10 @@ public function assertBrowserCookieValueSame(string $name, string $expectedValue
3540
/**
3641
* Asserts that the test client has the specified cookie set.
3742
* This indicates that the cookie was set by any response during the test.
43+
*
44+
* ```
45+
* $I->assertBrowserHasCookie('cookie_name');
46+
* ```
3847
*/
3948
public function assertBrowserHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
4049
{
@@ -44,6 +53,11 @@ public function assertBrowserHasCookie(string $name, string $path = '/', ?string
4453
/**
4554
* Asserts that the test client does not have the specified cookie set.
4655
* This indicates that the cookie was not set by any response during the test.
56+
*
57+
* ```php
58+
* <?php
59+
* $I->assertBrowserNotHasCookie('cookie_name');
60+
* ```
4761
*/
4862
public function assertBrowserNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
4963
{
@@ -52,6 +66,11 @@ public function assertBrowserNotHasCookie(string $name, string $path = '/', ?str
5266

5367
/**
5468
* Asserts that the specified request attribute matches the expected value.
69+
*
70+
* ```php
71+
* <?php
72+
* $I->assertRequestAttributeValueSame('attribute_name', 'expected_value');
73+
* ```
5574
*/
5675
public function assertRequestAttributeValueSame(string $name, string $expectedValue, string $message = ''): void
5776
{
@@ -60,6 +79,11 @@ public function assertRequestAttributeValueSame(string $name, string $expectedVa
6079

6180
/**
6281
* Asserts that the specified response cookie is present and matches the expected value.
82+
*
83+
* ```php
84+
* <?php
85+
* $I->assertResponseCookieValueSame('cookie_name', 'expected_value');
86+
* ```
6387
*/
6488
public function assertResponseCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = ''): void
6589
{
@@ -69,6 +93,11 @@ public function assertResponseCookieValueSame(string $name, string $expectedValu
6993

7094
/**
7195
* Asserts that the response format matches the expected format. This checks the format returned by the `Response::getFormat()` method.
96+
*
97+
* ```php
98+
* <?php
99+
* $I->assertResponseFormatSame('json');
100+
* ```
72101
*/
73102
public function assertResponseFormatSame(?string $expectedFormat, string $message = ''): void
74103
{
@@ -77,6 +106,11 @@ public function assertResponseFormatSame(?string $expectedFormat, string $messag
77106

78107
/**
79108
* Asserts that the specified cookie is present in the response. Optionally, it can check for a specific cookie path or domain.
109+
*
110+
* ```php
111+
* <?php
112+
* $I->assertResponseHasCookie('cookie_name');
113+
* ```
80114
*/
81115
public function assertResponseHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
82116
{
@@ -86,6 +120,11 @@ public function assertResponseHasCookie(string $name, string $path = '/', ?strin
86120
/**
87121
* Asserts that the specified header is available in the response.
88122
* For example, use `assertResponseHasHeader('content-type');`.
123+
*
124+
* ```php
125+
* <?php
126+
* $I->assertResponseHasHeader('content-type');
127+
* ```
89128
*/
90129
public function assertResponseHasHeader(string $headerName, string $message = ''): void
91130
{
@@ -95,6 +134,11 @@ public function assertResponseHasHeader(string $headerName, string $message = ''
95134
/**
96135
* Asserts that the specified header does not contain the expected value in the response.
97136
* For example, use `assertResponseHeaderNotSame('content-type', 'application/octet-stream');`.
137+
*
138+
* ```php
139+
* <?php
140+
* $I->assertResponseHeaderNotSame('content-type', 'application/json');
141+
* ```
98142
*/
99143
public function assertResponseHeaderNotSame(string $headerName, string $expectedValue, string $message = ''): void
100144
{
@@ -104,6 +148,11 @@ public function assertResponseHeaderNotSame(string $headerName, string $expected
104148
/**
105149
* Asserts that the specified header contains the expected value in the response.
106150
* For example, use `assertResponseHeaderSame('content-type', 'application/octet-stream');`.
151+
*
152+
* ```php
153+
* <?php
154+
* $I->assertResponseHeaderSame('content-type', 'application/json');
155+
* ```
107156
*/
108157
public function assertResponseHeaderSame(string $headerName, string $expectedValue, string $message = ''): void
109158
{
@@ -112,6 +161,11 @@ public function assertResponseHeaderSame(string $headerName, string $expectedVal
112161

113162
/**
114163
* Asserts that the response was successful (HTTP status code is in the 2xx range).
164+
*
165+
* ```php
166+
* <?php
167+
* $I->assertResponseIsSuccessful();
168+
* ```
115169
*/
116170
public function assertResponseIsSuccessful(string $message = '', bool $verbose = true): void
117171
{
@@ -120,6 +174,11 @@ public function assertResponseIsSuccessful(string $message = '', bool $verbose =
120174

121175
/**
122176
* Asserts that the response is unprocessable (HTTP status code is 422).
177+
*
178+
* ```php
179+
* <?php
180+
* $I->assertResponseIsUnprocessable();
181+
* ```
123182
*/
124183
public function assertResponseIsUnprocessable(string $message = '', bool $verbose = true): void
125184
{
@@ -128,6 +187,11 @@ public function assertResponseIsUnprocessable(string $message = '', bool $verbos
128187

129188
/**
130189
* Asserts that the specified cookie is not present in the response. Optionally, it can check for a specific cookie path or domain.
190+
*
191+
* ```php
192+
* <?php
193+
* $I->assertResponseNotHasCookie('cookie_name');
194+
* ```
131195
*/
132196
public function assertResponseNotHasCookie(string $name, string $path = '/', ?string $domain = null, string $message = ''): void
133197
{
@@ -136,7 +200,11 @@ public function assertResponseNotHasCookie(string $name, string $path = '/', ?st
136200

137201
/**
138202
* Asserts that the specified header is not available in the response.
139-
* For example, use `assertResponseNotHasHeader('content-type');`.
203+
*
204+
* ```php
205+
* <?php
206+
* $I->assertResponseNotHasHeader('content-type');
207+
* ```
140208
*/
141209
public function assertResponseNotHasHeader(string $headerName, string $message = ''): void
142210
{
@@ -146,6 +214,12 @@ public function assertResponseNotHasHeader(string $headerName, string $message =
146214
/**
147215
* Asserts that the response is a redirect. Optionally, you can check the target location and status code.
148216
* The expected location can be either an absolute or a relative path.
217+
*
218+
* ```php
219+
* <?php
220+
* // Check that '/admin' redirects to '/login' with status code 302
221+
* $I->assertResponseRedirects('/login', 302);
222+
* ```
149223
*/
150224
public function assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '', bool $verbose = true): void
151225
{
@@ -165,6 +239,11 @@ public function assertResponseRedirects(?string $expectedLocation = null, ?int $
165239

166240
/**
167241
* Asserts that the response status code matches the expected code.
242+
*
243+
* ```php
244+
* <?php
245+
* $I->assertResponseStatusCodeSame(200);
246+
* ```
168247
*/
169248
public function assertResponseStatusCodeSame(int $expectedCode, string $message = '', bool $verbose = true): void
170249
{
@@ -173,6 +252,11 @@ public function assertResponseStatusCodeSame(int $expectedCode, string $message
173252

174253
/**
175254
* Asserts the request matches the given route and optionally route parameters.
255+
*
256+
* ```php
257+
* <?php
258+
* $I->assertRouteSame('profile', ['id' => 123]);
259+
* ```
176260
*/
177261
public function assertRouteSame(string $expectedRoute, array $parameters = [], string $message = ''): void {
178262
$request = $this->getClient()->getRequest();

‎src/Codeception/Module/Symfony/DomCrawlerAssertionsTrait.php

+55
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ trait DomCrawlerAssertionsTrait
1515
{
1616
/**
1717
* Asserts that the checkbox with the given name is checked.
18+
*
19+
* ```php
20+
* <?php
21+
* $I->assertCheckboxChecked('agree_terms');
22+
* ```
1823
*/
1924
public function assertCheckboxChecked(string $fieldName, string $message = ''): void
2025
{
@@ -23,6 +28,11 @@ public function assertCheckboxChecked(string $fieldName, string $message = ''):
2328

2429
/**
2530
* Asserts that the checkbox with the given name is not checked.
31+
*
32+
* ```php
33+
* <?php
34+
* $I->assertCheckboxNotChecked('subscribe');
35+
* ```
2636
*/
2737
public function assertCheckboxNotChecked(string $fieldName, string $message = ''): void
2838
{
@@ -33,6 +43,11 @@ public function assertCheckboxNotChecked(string $fieldName, string $message = ''
3343

3444
/**
3545
* Asserts that the value of the form input with the given name does not equal the expected value.
46+
*
47+
* ```php
48+
* <?php
49+
* $I->assertInputValueNotSame('username', 'admin');
50+
* ```
3651
*/
3752
public function assertInputValueNotSame(string $fieldName, string $expectedValue, string $message = ''): void
3853
{
@@ -44,6 +59,11 @@ public function assertInputValueNotSame(string $fieldName, string $expectedValue
4459

4560
/**
4661
* Asserts that the value of the form input with the given name equals the expected value.
62+
*
63+
* ```php
64+
* <?php
65+
* $I->assertInputValueSame('username', 'johndoe');
66+
* ```
4767
*/
4868
public function assertInputValueSame(string $fieldName, string $expectedValue, string $message = ''): void
4969
{
@@ -56,6 +76,11 @@ public function assertInputValueSame(string $fieldName, string $expectedValue, s
5676

5777
/**
5878
* Asserts that the `<title>` element contains the given title.
79+
*
80+
* ```php
81+
* <?php
82+
* $I->assertPageTitleContains('Welcome');
83+
* ```
5984
*/
6085
public function assertPageTitleContains(string $expectedTitle, string $message = ''): void
6186
{
@@ -64,6 +89,11 @@ public function assertPageTitleContains(string $expectedTitle, string $message =
6489

6590
/**
6691
* Asserts that the `<title>` element equals the given title.
92+
*
93+
* ```php
94+
* <?php
95+
* $I->assertPageTitleSame('Home Page');
96+
* ```
6797
*/
6898
public function assertPageTitleSame(string $expectedTitle, string $message = ''): void
6999
{
@@ -72,6 +102,11 @@ public function assertPageTitleSame(string $expectedTitle, string $message = '')
72102

73103
/**
74104
* Asserts that the given selector matches at least one element in the response.
105+
*
106+
* ```php
107+
* <?php
108+
* $I->assertSelectorExists('.main-content');
109+
* ```
75110
*/
76111
public function assertSelectorExists(string $selector, string $message = ''): void
77112
{
@@ -80,6 +115,11 @@ public function assertSelectorExists(string $selector, string $message = ''): vo
80115

81116
/**
82117
* Asserts that the given selector does not match at least one element in the response.
118+
*
119+
* ```php
120+
* <?php
121+
* $I->assertSelectorNotExists('.error');
122+
* ```
83123
*/
84124
public function assertSelectorNotExists(string $selector, string $message = ''): void
85125
{
@@ -88,6 +128,11 @@ public function assertSelectorNotExists(string $selector, string $message = ''):
88128

89129
/**
90130
* Asserts that the first element matching the given selector contains the expected text.
131+
*
132+
* ```php
133+
* <?php
134+
* $I->assertSelectorTextContains('h1', 'Dashboard');
135+
* ```
91136
*/
92137
public function assertSelectorTextContains(string $selector, string $text, string $message = ''): void
93138
{
@@ -97,6 +142,11 @@ public function assertSelectorTextContains(string $selector, string $text, strin
97142

98143
/**
99144
* Asserts that the first element matching the given selector does not contain the expected text.
145+
*
146+
* ```php
147+
* <?php
148+
* $I->assertSelectorTextNotContains('p', 'error');
149+
* ```
100150
*/
101151
public function assertSelectorTextNotContains(string $selector, string $text, string $message = ''): void
102152
{
@@ -106,6 +156,11 @@ public function assertSelectorTextNotContains(string $selector, string $text, st
106156

107157
/**
108158
* Asserts that the text of the first element matching the given selector equals the expected text.
159+
*
160+
* ```php
161+
* <?php
162+
* $I->assertSelectorTextSame('h1', 'Dashboard');
163+
* ```
109164
*/
110165
public function assertSelectorTextSame(string $selector, string $text, string $message = ''): void
111166
{

‎src/Codeception/Module/Symfony/FormAssertionsTrait.php

+13-4
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ trait FormAssertionsTrait
1414
{
1515
/**
1616
* Asserts that value of the field of the first form matching the given selector does equal the expected value.
17+
*
18+
* ```php
19+
* <?php
20+
* $I->assertFormValue('#loginForm', 'username', 'john_doe');
21+
* ```
1722
*/
1823
public function assertFormValue(string $formSelector, string $fieldName, string $value, string $message = ''): void
1924
{
@@ -25,7 +30,12 @@ public function assertFormValue(string $formSelector, string $fieldName, string
2530
}
2631

2732
/**
28-
* Asserts that value of the field of the first form matching the given selector does equal the expected value.
33+
* Asserts that the field of the first form matching the given selector does not have a value.
34+
*
35+
* ```php
36+
* <?php
37+
* $I->assertNoFormValue('#registrationForm', 'middle_name');
38+
* ```
2939
*/
3040
public function assertNoFormValue(string $formSelector, string $fieldName, string $message = ''): void
3141
{
@@ -128,15 +138,14 @@ public function seeFormErrorMessage(string $field, ?string $message = null): voi
128138
* If you want to specify the error messages, you can do so
129139
* by sending an associative array instead, with the key being
130140
* the name of the field and the error message the value.
131-
*
132141
* This method will validate that the expected error message
133142
* is contained in the actual error message, that is,
134143
* you can specify either the entire error message or just a part of it:
135144
*
136145
* ```php
137146
* <?php
138147
* $I->seeFormErrorMessages([
139-
* 'address' => 'The address is too long'
148+
* 'address' => 'The address is too long',
140149
* 'telephone' => 'too short', // the full error message is 'The telephone is too short'
141150
* ]);
142151
* ```
@@ -191,4 +200,4 @@ protected function grabFormCollector(string $function): FormDataCollector
191200
{
192201
return $this->grabCollector('form', $function);
193202
}
194-
}
203+
}

‎src/Codeception/Module/Symfony/HttpClientAssertionsTrait.php

+22-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,18 @@ trait HttpClientAssertionsTrait
1212
{
1313
/**
1414
* Asserts that the given URL has been called using, if specified, the given method body and headers.
15-
* By default, it will check on the HttpClient, but you can also pass a specific HttpClient ID. (It will succeed if the request has been called multiple times.)
15+
* By default, it will check on the HttpClient, but you can also pass a specific HttpClient ID.
16+
* (It will succeed if the request has been called multiple times.)
17+
*
18+
* ```php
19+
* <?php
20+
* $I->assertHttpClientRequest(
21+
* 'https://example.com/api',
22+
* 'POST',
23+
* '{"data": "value"}',
24+
* ['Authorization' => 'Bearer token']
25+
* );
26+
* ```
1627
*/
1728
public function assertHttpClientRequest(string $expectedUrl, string $expectedMethod = 'GET', string|array|null $expectedBody = null, array $expectedHeaders = [], string $httpClientId = 'http_client'): void
1829
{
@@ -77,6 +88,11 @@ public function assertHttpClientRequest(string $expectedUrl, string $expectedMet
7788
/**
7889
* Asserts that the given number of requests has been made on the HttpClient.
7990
* By default, it will check on the HttpClient, but you can also pass a specific HttpClient ID.
91+
*
92+
* ```php
93+
* <?php
94+
* $I->assertHttpClientRequestCount(3);
95+
* ```
8096
*/
8197
public function assertHttpClientRequestCount(int $count, string $httpClientId = 'http_client'): void
8298
{
@@ -88,6 +104,11 @@ public function assertHttpClientRequestCount(int $count, string $httpClientId =
88104
/**
89105
* Asserts that the given URL has not been called using GET or the specified method.
90106
* By default, it will check on the HttpClient, but a HttpClient id can be specified.
107+
*
108+
* ```php
109+
* <?php
110+
* $I->assertNotHttpClientRequest('https://example.com/unexpected', 'GET');
111+
* ```
91112
*/
92113
public function assertNotHttpClientRequest(string $unexpectedUrl, string $expectedMethod = 'GET', string $httpClientId = 'http_client'): void
93114
{

‎src/Codeception/Module/Symfony/MailerAssertionsTrait.php

+50-9
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ trait MailerAssertionsTrait
1515
{
1616
/**
1717
* Asserts that the expected number of emails was sent.
18+
*
19+
* ```php
20+
* <?php
21+
* $I->assertEmailCount(2, 'smtp');
22+
* ```
1823
*/
1924
public function assertEmailCount(int $count, ?string $transport = null, string $message = ''): void
2025
{
@@ -24,6 +29,12 @@ public function assertEmailCount(int $count, ?string $transport = null, string $
2429
/**
2530
* Asserts that the given mailer event is not queued.
2631
* Use `getMailerEvent(int $index = 0, ?string $transport = null)` to retrieve a mailer event by index.
32+
*
33+
* ```php
34+
* <?php
35+
* $event = $I->getMailerEvent();
36+
* $I->assertEmailIsNotQueued($event);
37+
* ```
2738
*/
2839
public function assertEmailIsNotQueued(MessageEvent $event, string $message = ''): void
2940
{
@@ -33,6 +44,12 @@ public function assertEmailIsNotQueued(MessageEvent $event, string $message = ''
3344
/**
3445
* Asserts that the given mailer event is queued.
3546
* Use `getMailerEvent(int $index = 0, ?string $transport = null)` to retrieve a mailer event by index.
47+
*
48+
* ```php
49+
* <?php
50+
* $event = $I->getMailerEvent();
51+
* $I->assertEmailIsQueued($event);
52+
* ```
3653
*/
3754
public function assertEmailIsQueued(MessageEvent $event, string $message = ''): void
3855
{
@@ -41,6 +58,11 @@ public function assertEmailIsQueued(MessageEvent $event, string $message = ''):
4158

4259
/**
4360
* Asserts that the expected number of emails was queued (e.g. using the Messenger component).
61+
*
62+
* ```php
63+
* <?php
64+
* $I->assertQueuedEmailCount(1, 'smtp');
65+
* ```
4466
*/
4567
public function assertQueuedEmailCount(int $count, ?string $transport = null, string $message = ''): void
4668
{
@@ -50,7 +72,13 @@ public function assertQueuedEmailCount(int $count, ?string $transport = null, st
5072
/**
5173
* Checks that no email was sent.
5274
* The check is based on `\Symfony\Component\Mailer\EventListener\MessageLoggerListener`, which means:
53-
* If your app performs an HTTP redirect, you need to suppress it using [stopFollowingRedirects()](https://codeception.com/docs/modules/Symfony#stopFollowingRedirects) first; otherwise this check will *always* pass.
75+
* If your app performs an HTTP redirect, you need to suppress it using [stopFollowingRedirects()](https://codeception.com/docs/modules/Symfony#stopFollowingRedirects) first;
76+
* otherwise this check will *always* pass.
77+
*
78+
* ```php
79+
* <?php
80+
* $I->dontSeeEmailIsSent();
81+
* ```
5482
*/
5583
public function dontSeeEmailIsSent(): void
5684
{
@@ -114,18 +142,31 @@ public function seeEmailIsSent(int $expectedCount = 1): void
114142
$this->assertThat($this->getMessageMailerEvents(), new MailerConstraint\EmailCount($expectedCount));
115143
}
116144

145+
/**
146+
* Returns the mailer event at the specified index.
147+
*
148+
* ```php
149+
* <?php
150+
* $event = $I->getMailerEvent();
151+
* ```
152+
*/
153+
public function getMailerEvent(int $index = 0, ?string $transport = null): ?MessageEvent
154+
{
155+
$mailerEvents = $this->getMessageMailerEvents();
156+
$events = $mailerEvents->getEvents($transport);
157+
return $events[$index] ?? null;
158+
}
159+
117160
protected function getMessageMailerEvents(): MessageEvents
118161
{
119-
if ($messageLogger = $this->getService('mailer.message_logger_listener')) {
120-
/** @var MessageLoggerListener $messageLogger */
121-
return $messageLogger->getEvents();
162+
if ($mailer = $this->getService('mailer.message_logger_listener')) {
163+
/** @var MessageLoggerListener $mailer */
164+
return $mailer->getEvents();
122165
}
123-
124-
if ($messageLogger = $this->getService('mailer.logger_message_listener')) {
125-
/** @var MessageLoggerListener $messageLogger */
126-
return $messageLogger->getEvents();
166+
if ($mailer = $this->getService('mailer.logger_message_listener')) {
167+
/** @var MessageLoggerListener $mailer */
168+
return $mailer->getEvents();
127169
}
128-
129170
$this->fail("Emails can't be tested without Symfony Mailer service.");
130171
}
131172
}

0 commit comments

Comments
 (0)
Please sign in to comment.