最新服务器上的版本，以后用这个
view | history | commit | commitdiff
wangzhenxin
2023-11-19 bc164b8bdbfbdf1d8229a5ced6b08d7cb8db7361
commit | author | age
2207d6 1 # Lumen
W 2
3
4
5 This module allows you to run functional tests for Lumen.
6 Please try it and leave your feedback.
7
8 ## Demo project
9 <https://github.com/janhenkgerritsen/codeception-lumen-sample>
10
11 ## Status
12
13 * Maintainer: **Jan-Henk Gerritsen**
14 * Stability: **dev**
15 * Contact: janhenkgerritsen@gmail.com
16
17 ## Config
18
19 * cleanup: `boolean`, default `true` - all database queries will be run in a transaction,
20   which will be rolled back at the end of each test.
21 * bootstrap: `string`, default `bootstrap/app.php` - relative path to app.php config file.
22 * root: `string`, default `` - root path of the application.
23 * packages: `string`, default `workbench` - root path of application packages (if any).
24 * url: `string`, default `http://localhost` - the application URL
25
26 ## API
27
28 * app - `\Laravel\Lumen\Application`
29 * config - `array`
30
31 ## Parts
32
33 * ORM - only include the database methods of this module:
34     * have
35     * haveMultiple
36     * haveRecord
37     * grabRecord
38     * seeRecord
39     * dontSeeRecord
40
41 ## Actions
42
43 ### _findElements
44
45 *hidden API method, expected to be used from Helper classes*
46  
47 Locates element using available Codeception locator types:
48
49 * XPath
50 * CSS
51 * Strict Locator
52
53 Use it in Helpers or GroupObject or Extension classes:
54
55 ```php
56 <?php
57 $els = $this->getModule('Lumen')->_findElements('.items');
58 $els = $this->getModule('Lumen')->_findElements(['name' => 'username']);
59
60 $editLinks = $this->getModule('Lumen')->_findElements(['link' => 'Edit']);
61 // now you can iterate over $editLinks and check that all them have valid hrefs
62 ```
63
64 WebDriver module returns `Facebook\WebDriver\Remote\RemoteWebElement` instances
65 PhpBrowser and Framework modules return `Symfony\Component\DomCrawler\Crawler` instances
66
67  * `param` $locator
68  * `return` array of interactive elements
69
70
71 ### _getResponseContent
72
73 *hidden API method, expected to be used from Helper classes*
74  
75 Returns content of the last response
76 Use it in Helpers when you want to retrieve response of request performed by another module.
77
78 ```php
79 <?php
80 // in Helper class
81 public function seeResponseContains($text)
82 {
83    $this->assertContains($text, $this->getModule('Lumen')->_getResponseContent(), "response contains");
84 }
85 ?>
86 ```
87
88  * `return` string
89 @throws ModuleException
90
91
92 ### _loadPage
93
94 *hidden API method, expected to be used from Helper classes*
95  
96 Opens a page with arbitrary request parameters.
97 Useful for testing multi-step forms on a specific step.
98
99 ```php
100 <?php
101 // in Helper class
102 public function openCheckoutFormStep2($orderId) {
103     $this->getModule('Lumen')->_loadPage('POST', '/checkout/step2', ['order' => $orderId]);
104 }
105 ?>
106 ```
107
108  * `param` $method
109  * `param` $uri
110  * `param array` $parameters
111  * `param array` $files
112  * `param array` $server
113  * `param null` $content
114
115
116 ### _request
117
118 *hidden API method, expected to be used from Helper classes*
119  
120 Send custom request to a backend using method, uri, parameters, etc.
121 Use it in Helpers to create special request actions, like accessing API
122 Returns a string with response body.
123
124 ```php
125 <?php
126 // in Helper class
127 public function createUserByApi($name) {
128     $userData = $this->getModule('Lumen')->_request('POST', '/api/v1/users', ['name' => $name]);
129     $user = json_decode($userData);
130     return $user->id;
131 }
132 ?>
133 ```
134 Does not load the response into the module so you can't interact with response page (click, fill forms).
135 To load arbitrary page for interaction, use `_loadPage` method.
136
137  * `param` $method
138  * `param` $uri
139  * `param array` $parameters
140  * `param array` $files
141  * `param array` $server
142  * `param null` $content
143  * `return` mixed|Crawler
144 @throws ExternalUrlException
145 @see `_loadPage`
146
147
148 ### _savePageSource
149
150 *hidden API method, expected to be used from Helper classes*
151  
152 Saves page source of to a file
153
154 ```php
155 $this->getModule('Lumen')->_savePageSource(codecept_output_dir().'page.html');
156 ```
157  * `param` $filename
158
159
160 ### amHttpAuthenticated
161  
162 Authenticates user for HTTP_AUTH
163
164  * `param` $username
165  * `param` $password
166
167
168 ### amLoggedAs
169  
170 Set the authenticated user for the next request.
171 This will not persist between multiple requests.
172
173  * `param`  \Illuminate\Contracts\Auth\Authenticatable
174  * `param`  string|null $driver The authentication driver for Lumen <= 5.1.*, guard name for Lumen >= 5.2
175  * `return` void
176
177
178 ### amOnPage
179  
180 Opens the page for the given relative URI.
181
182 ``` php
183 <?php
184 // opens front page
185 $I->amOnPage('/');
186 // opens /register page
187 $I->amOnPage('/register');
188 ```
189
190  * `param string` $page
191
192
193 ### amOnRoute
194  
195 Opens web page using route name and parameters.
196
197 ```php
198 <?php
199 $I->amOnRoute('homepage');
200 ?>
201 ```
202
203  * `param` $routeName
204  * `param array` $params
205
206
207 ### attachFile
208  
209 Attaches a file relative to the Codeception `_data` directory to the given file upload field.
210
211 ``` php
212 <?php
213 // file is stored in 'tests/_data/prices.xls'
214 $I->attachFile('input[@type="file"]', 'prices.xls');
215 ?>
216 ```
217
218  * `param` $field
219  * `param` $filename
220
221
222 ### checkOption
223  
224 Ticks a checkbox. For radio buttons, use the `selectOption` method instead.
225
226 ``` php
227 <?php
228 $I->checkOption('#agree');
229 ?>
230 ```
231
232  * `param` $option
233
234
235 ### clearApplicationHandlers
236  
237 Clear the registered application handlers.
238
239 ``` php
240 <?php
241 $I->clearApplicationHandlers();
242 ?>
243 ```
244
245
246
247 ### click
248  
249 Perform a click on a link or a button, given by a locator.
250 If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
251 For buttons, the "value" attribute, "name" attribute, and inner text are searched.
252 For links, the link text is searched.
253 For images, the "alt" attribute and inner text of any parent links are searched.
254
255 The second parameter is a context (CSS or XPath locator) to narrow the search.
256
257 Note that if the locator matches a button of type `submit`, the form will be submitted.
258
259 ``` php
260 <?php
261 // simple link
262 $I->click('Logout');
263 // button of form
264 $I->click('Submit');
265 // CSS button
266 $I->click('#form input[type=submit]');
267 // XPath
268 $I->click('//form/*[@type=submit]');
269 // link in context
270 $I->click('Logout', '#nav');
271 // using strict locator
272 $I->click(['link' => 'Login']);
273 ?>
274 ```
275
276  * `param` $link
277  * `param` $context
278
279
280 ### deleteHeader
281  
282 Deletes the header with the passed name.  Subsequent requests
283 will not have the deleted header in its request.
284
285 Example:
286 ```php
287 <?php
288 $I->haveHttpHeader('X-Requested-With', 'Codeception');
289 $I->amOnPage('test-headers.php');
290 // ...
291 $I->deleteHeader('X-Requested-With');
292 $I->amOnPage('some-other-page.php');
293 ?>
294 ```
295
296  * `param string` $name the name of the header to delete.
297
298
299 ### dontSee
300  
301 Checks that the current page doesn't contain the text specified (case insensitive).
302 Give a locator as the second parameter to match a specific region.
303
304 ```php
305 <?php
306 $I->dontSee('Login');                         // I can suppose user is already logged in
307 $I->dontSee('Sign Up','h1');                  // I can suppose it's not a signup page
308 $I->dontSee('Sign Up','//body/h1');           // with XPath
309 $I->dontSee('Sign Up', ['css' => 'body h1']); // with strict CSS locator
310 ```
311
312 Note that the search is done after stripping all HTML tags from the body,
313 so `$I->dontSee('strong')` will fail on strings like:
314
315   - `<p>I am Stronger than thou</p>`
316   - `<script>document.createElement('strong');</script>`
317
318 But will ignore strings like:
319
320   - `<strong>Home</strong>`
321   - `<div class="strong">Home</strong>`
322   - `<!-- strong -->`
323
324 For checking the raw source code, use `seeInSource()`.
325
326  * `param string` $text
327  * `param string` $selector optional
328
329
330 ### dontSeeAuthentication
331  
332 Check that user is not authenticated.
333
334
335 ### dontSeeCheckboxIsChecked
336  
337 Check that the specified checkbox is unchecked.
338
339 ``` php
340 <?php
341 $I->dontSeeCheckboxIsChecked('#agree'); // I suppose user didn't agree to terms
342 $I->seeCheckboxIsChecked('#signup_form input[type=checkbox]'); // I suppose user didn't check the first checkbox in form.
343 ?>
344 ```
345
346  * `param` $checkbox
347
348
349 ### dontSeeCookie
350  
351 Checks that there isn't a cookie with the given name.
352 You can set additional cookie params like `domain`, `path` as array passed in last argument.
353
354  * `param` $cookie
355
356  * `param array` $params
357
358
359 ### dontSeeCurrentUrlEquals
360  
361 Checks that the current URL doesn't equal the given string.
362 Unlike `dontSeeInCurrentUrl`, this only matches the full URL.
363
364 ``` php
365 <?php
366 // current url is not root
367 $I->dontSeeCurrentUrlEquals('/');
368 ?>
369 ```
370
371  * `param string` $uri
372
373
374 ### dontSeeCurrentUrlMatches
375  
376 Checks that current url doesn't match the given regular expression.
377
378 ``` php
379 <?php
380 // to match root url
381 $I->dontSeeCurrentUrlMatches('~^/users/(\d+)~');
382 ?>
383 ```
384
385  * `param string` $uri
386
387
388 ### dontSeeElement
389  
390 Checks that the given element is invisible or not present on the page.
391 You can also specify expected attributes of this element.
392
393 ``` php
394 <?php
395 $I->dontSeeElement('.error');
396 $I->dontSeeElement('//form/input[1]');
397 $I->dontSeeElement('input', ['name' => 'login']);
398 $I->dontSeeElement('input', ['value' => '123456']);
399 ?>
400 ```
401
402  * `param` $selector
403  * `param array` $attributes
404
405
406 ### dontSeeInCurrentUrl
407  
408 Checks that the current URI doesn't contain the given string.
409
410 ``` php
411 <?php
412 $I->dontSeeInCurrentUrl('/users/');
413 ?>
414 ```
415
416  * `param string` $uri
417
418
419 ### dontSeeInField
420  
421 Checks that an input field or textarea doesn't contain the given value.
422 For fuzzy locators, the field is matched by label text, CSS and XPath.
423
424 ``` php
425 <?php
426 $I->dontSeeInField('Body','Type your comment here');
427 $I->dontSeeInField('form textarea[name=body]','Type your comment here');
428 $I->dontSeeInField('form input[type=hidden]','hidden_value');
429 $I->dontSeeInField('#searchform input','Search');
430 $I->dontSeeInField('//form/*[@name=search]','Search');
431 $I->dontSeeInField(['name' => 'search'], 'Search');
432 ?>
433 ```
434
435  * `param` $field
436  * `param` $value
437
438
439 ### dontSeeInFormFields
440  
441 Checks if the array of form parameters (name => value) are not set on the form matched with
442 the passed selector.
443
444 ``` php
445 <?php
446 $I->dontSeeInFormFields('form[name=myform]', [
447      'input1' => 'non-existent value',
448      'input2' => 'other non-existent value',
449 ]);
450 ?>
451 ```
452
453 To check that an element hasn't been assigned any one of many values, an array can be passed
454 as the value:
455
456 ``` php
457 <?php
458 $I->dontSeeInFormFields('.form-class', [
459      'fieldName' => [
460          'This value shouldn\'t be set',
461          'And this value shouldn\'t be set',
462      ],
463 ]);
464 ?>
465 ```
466
467 Additionally, checkbox values can be checked with a boolean.
468
469 ``` php
470 <?php
471 $I->dontSeeInFormFields('#form-id', [
472      'checkbox1' => true,        // fails if checked
473      'checkbox2' => false,       // fails if unchecked
474 ]);
475 ?>
476 ```
477
478  * `param` $formSelector
479  * `param` $params
480
481
482 ### dontSeeInSource
483  
484 Checks that the current page contains the given string in its
485 raw source code.
486
487 ```php
488 <?php
489 $I->dontSeeInSource('<h1>Green eggs &amp; ham</h1>');
490 ```
491
492  * `param`      $raw
493
494
495 ### dontSeeInTitle
496  
497 Checks that the page title does not contain the given string.
498
499  * `param` $title
500
501
502
503 ### dontSeeLink
504  
505 Checks that the page doesn't contain a link with the given string.
506 If the second parameter is given, only links with a matching "href" attribute will be checked.
507
508 ``` php
509 <?php
510 $I->dontSeeLink('Logout'); // I suppose user is not logged in
511 $I->dontSeeLink('Checkout now', '/store/cart.php');
512 ?>
513 ```
514
515  * `param string` $text
516  * `param string` $url optional
517
518
519 ### dontSeeOptionIsSelected
520  
521 Checks that the given option is not selected.
522
523 ``` php
524 <?php
525 $I->dontSeeOptionIsSelected('#form input[name=payment]', 'Visa');
526 ?>
527 ```
528
529  * `param` $selector
530  * `param` $optionText
531
532
533
534 ### dontSeeRecord
535  
536 Checks that record does not exist in database.
537 You can pass the name of a database table or the class name of an Eloquent model as the first argument.
538
539 ``` php
540 <?php
541 $I->dontSeeRecord('users', array('name' => 'davert'));
542 $I->dontSeeRecord('App\User', array('name' => 'davert'));
543 ?>
544 ```
545
546  * `param string` $table
547  * `param array` $attributes
548  * `[Part]` orm
549
550
551 ### dontSeeResponseCodeIs
552  
553 Checks that response code is equal to value provided.
554
555 ```php
556 <?php
557 $I->dontSeeResponseCodeIs(200);
558
559 // recommended \Codeception\Util\HttpCode
560 $I->dontSeeResponseCodeIs(\Codeception\Util\HttpCode::OK);
561 ```
562  * `param` $code
563
564
565 ### fillField
566  
567 Fills a text field or textarea with the given string.
568
569 ``` php
570 <?php
571 $I->fillField("//input[@type='text']", "Hello World!");
572 $I->fillField(['name' => 'email'], 'jon@mail.com');
573 ?>
574 ```
575
576  * `param` $field
577  * `param` $value
578
579
580 ### getApplication
581  
582 Provides access the Lumen application object.
583
584  * `return` \Laravel\Lumen\Application
585
586
587 ### grabAttributeFrom
588  
589 Grabs the value of the given attribute value from the given element.
590 Fails if element is not found.
591
592 ``` php
593 <?php
594 $I->grabAttributeFrom('#tooltip', 'title');
595 ?>
596 ```
597
598  * `param` $cssOrXpath
599  * `param` $attribute
600
601
602
603 ### grabCookie
604  
605 Grabs a cookie value.
606 You can set additional cookie params like `domain`, `path` in array passed as last argument.
607
608  * `param` $cookie
609
610  * `param array` $params
611
612
613 ### grabFromCurrentUrl
614  
615 Executes the given regular expression against the current URI and returns the first capturing group.
616 If no parameters are provided, the full URI is returned.
617
618 ``` php
619 <?php
620 $user_id = $I->grabFromCurrentUrl('~^/user/(\d+)/~');
621 $uri = $I->grabFromCurrentUrl();
622 ?>
623 ```
624
625  * `param string` $uri optional
626
627
628
629 ### grabMultiple
630  
631 Grabs either the text content, or attribute values, of nodes
632 matched by $cssOrXpath and returns them as an array.
633
634 ```html
635 <a href="#first">First</a>
636 <a href="#second">Second</a>
637 <a href="#third">Third</a>
638 ```
639
640 ```php
641 <?php
642 // would return ['First', 'Second', 'Third']
643 $aLinkText = $I->grabMultiple('a');
644
645 // would return ['#first', '#second', '#third']
646 $aLinks = $I->grabMultiple('a', 'href');
647 ?>
648 ```
649
650  * `param` $cssOrXpath
651  * `param` $attribute
652  * `return` string[]
653
654
655 ### grabPageSource
656  
657 Grabs current page source code.
658
659 @throws ModuleException if no page was opened.
660
661  * `return` string Current page source code.
662
663
664 ### grabRecord
665  
666 Retrieves record from database
667 If you pass the name of a database table as the first argument, this method returns an array.
668 You can also pass the class name of an Eloquent model, in that case this method returns an Eloquent model.
669
670 ``` php
671 <?php
672 $record = $I->grabRecord('users', array('name' => 'davert')); // returns array
673 $record = $I->grabRecord('App\User', array('name' => 'davert')); // returns Eloquent model
674 ?>
675 ```
676
677  * `param string` $table
678  * `param array` $attributes
679  * `return` array|EloquentModel
680  * `[Part]` orm
681
682
683 ### grabService
684  
685 Return an instance of a class from the IoC Container.
686
687 Example
688 ``` php
689 <?php
690 // In Lumen
691 App::bind('foo', function($app)
692 {
693     return new FooBar;
694 });
695
696 // Then in test
697 $service = $I->grabService('foo');
698
699 // Will return an instance of FooBar, also works for singletons.
700 ?>
701 ```
702
703  * `param`  string $class
704
705
706 ### grabTextFrom
707  
708 Finds and returns the text contents of the given element.
709 If a fuzzy locator is used, the element is found using CSS, XPath,
710 and by matching the full page source by regular expression.
711
712 ``` php
713 <?php
714 $heading = $I->grabTextFrom('h1');
715 $heading = $I->grabTextFrom('descendant-or-self::h1');
716 $value = $I->grabTextFrom('~<input value=(.*?)]~sgi'); // match with a regex
717 ?>
718 ```
719
720  * `param` $cssOrXPathOrRegex
721
722
723
724 ### grabValueFrom
725  
726  * `param` $field
727
728  * `return` array|mixed|null|string
729
730
731 ### have
732  
733 Use Lumen's model factory to create a model.
734 Can only be used with Lumen 5.1 and later.
735
736 ``` php
737 <?php
738 $I->have('App\User');
739 $I->have('App\User', ['name' => 'John Doe']);
740 $I->have('App\User', [], 'admin');
741 ?>
742 ```
743
744 @see https://lumen.laravel.com/docs/master/testing#model-factories
745  * `param string` $model
746  * `param array` $attributes
747  * `param string` $name
748  * `[Part]` orm
749
750
751 ### haveApplicationHandler
752  
753 Register a handler than can be used to modify the Laravel application object after it is initialized.
754 The Laravel application object will be passed as an argument to the handler.
755
756 ``` php
757 <?php
758 $I->haveApplicationHandler(function($app) {
759     $app->make('config')->set(['test_value' => '10']);
760 });
761 ?>
762 ```
763
764  * `param` $handler
765
766
767 ### haveBinding
768  
769 Add a binding to the Laravel service container.
770 (https://laravel.com/docs/master/container)
771
772 ``` php
773 <?php
774 $I->haveBinding('My\Interface', 'My\Implementation');
775 ?>
776 ```
777
778  * `param` $abstract
779  * `param` $concrete
780
781
782 ### haveContextualBinding
783  
784 Add a contextual binding to the Laravel service container.
785 (https://laravel.com/docs/master/container)
786
787 ``` php
788 <?php
789 $I->haveContextualBinding('My\Class', '$variable', 'value');
790
791 // This is similar to the following in your Laravel application
792 $app->when('My\Class')
793     ->needs('$variable')
794     ->give('value');
795 ?>
796 ```
797
798  * `param` $concrete
799  * `param` $abstract
800  * `param` $implementation
801
802
803 ### haveHttpHeader
804  
805 Sets the HTTP header to the passed value - which is used on
806 subsequent HTTP requests through PhpBrowser.
807
808 Example:
809 ```php
810 <?php
811 $I->haveHttpHeader('X-Requested-With', 'Codeception');
812 $I->amOnPage('test-headers.php');
813 ?>
814 ```
815
816 To use special chars in Header Key use HTML Character Entities:
817 Example:
818 Header with underscore - 'Client_Id'
819 should be represented as - 'Client&#x0005F;Id' or 'Client&#95;Id'
820
821 ```php
822 <?php
823 $I->haveHttpHeader('Client&#95;Id', 'Codeception');
824 ?>
825 ```
826
827  * `param string` $name the name of the request header
828  * `param string` $value the value to set it to for subsequent
829        requests
830
831
832 ### haveInstance
833  
834 Add an instance binding to the Laravel service container.
835 (https://laravel.com/docs/master/container)
836
837 ``` php
838 <?php
839 $I->haveInstance('My\Class', new My\Class());
840 ?>
841 ```
842
843  * `param` $abstract
844  * `param` $instance
845
846
847 ### haveMultiple
848  
849 Use Laravel's model factory to create multiple models.
850 Can only be used with Lumen 5.1 and later.
851
852 ``` php
853 <?php
854 $I->haveMultiple('App\User', 10);
855 $I->haveMultiple('App\User', 10, ['name' => 'John Doe']);
856 $I->haveMultiple('App\User', 10, [], 'admin');
857 ?>
858 ```
859
860 @see https://lumen.laravel.com/docs/master/testing#model-factories
861  * `param string` $model
862  * `param int` $times
863  * `param array` $attributes
864  * `param string` $name
865  * `[Part]` orm
866
867
868 ### haveRecord
869  
870 Inserts record into the database.
871 If you pass the name of a database table as the first argument, this method returns an integer ID.
872 You can also pass the class name of an Eloquent model, in that case this method returns an Eloquent model.
873
874 ``` php
875 <?php
876 $user_id = $I->haveRecord('users', array('name' => 'Davert')); // returns integer
877 $user = $I->haveRecord('App\User', array('name' => 'Davert')); // returns Eloquent model
878 ?>
879 ```
880
881  * `param string` $table
882  * `param array` $attributes
883  * `return` integer|EloquentModel
884  * `[Part]` orm
885
886
887 ### haveSingleton
888  
889 Add a singleton binding to the Laravel service container.
890 (https://laravel.com/docs/master/container)
891
892 ``` php
893 <?php
894 $I->haveSingleton('My\Interface', 'My\Singleton');
895 ?>
896 ```
897
898  * `param` $abstract
899  * `param` $concrete
900
901
902 ### moveBack
903  
904 Moves back in history.
905
906  * `param int` $numberOfSteps (default value 1)
907
908
909 ### resetCookie
910  
911 Unsets cookie with the given name.
912 You can set additional cookie params like `domain`, `path` in array passed as last argument.
913
914  * `param` $cookie
915
916  * `param array` $params
917
918
919 ### see
920  
921 Checks that the current page contains the given string (case insensitive).
922
923 You can specify a specific HTML element (via CSS or XPath) as the second
924 parameter to only search within that element.
925
926 ``` php
927 <?php
928 $I->see('Logout');                        // I can suppose user is logged in
929 $I->see('Sign Up', 'h1');                 // I can suppose it's a signup page
930 $I->see('Sign Up', '//body/h1');          // with XPath
931 $I->see('Sign Up', ['css' => 'body h1']); // with strict CSS locator
932 ```
933
934 Note that the search is done after stripping all HTML tags from the body,
935 so `$I->see('strong')` will return true for strings like:
936
937   - `<p>I am Stronger than thou</p>`
938   - `<script>document.createElement('strong');</script>`
939
940 But will *not* be true for strings like:
941
942   - `<strong>Home</strong>`
943   - `<div class="strong">Home</strong>`
944   - `<!-- strong -->`
945
946 For checking the raw source code, use `seeInSource()`.
947
948  * `param string` $text
949  * `param string` $selector optional
950
951
952 ### seeAuthentication
953  
954 Checks that user is authenticated.
955
956
957 ### seeCheckboxIsChecked
958  
959 Checks that the specified checkbox is checked.
960
961 ``` php
962 <?php
963 $I->seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
964 $I->seeCheckboxIsChecked('#signup_form input[type=checkbox]'); // I suppose user agreed to terms, If there is only one checkbox in form.
965 $I->seeCheckboxIsChecked('//form/input[@type=checkbox and @name=agree]');
966 ?>
967 ```
968
969  * `param` $checkbox
970
971
972 ### seeCookie
973  
974 Checks that a cookie with the given name is set.
975 You can set additional cookie params like `domain`, `path` as array passed in last argument.
976
977 ``` php
978 <?php
979 $I->seeCookie('PHPSESSID');
980 ?>
981 ```
982
983  * `param` $cookie
984  * `param array` $params
985
986
987 ### seeCurrentUrlEquals
988  
989 Checks that the current URL is equal to the given string.
990 Unlike `seeInCurrentUrl`, this only matches the full URL.
991
992 ``` php
993 <?php
994 // to match root url
995 $I->seeCurrentUrlEquals('/');
996 ?>
997 ```
998
999  * `param string` $uri
1000
1001
1002 ### seeCurrentUrlMatches
1003  
1004 Checks that the current URL matches the given regular expression.
1005
1006 ``` php
1007 <?php
1008 // to match root url
1009 $I->seeCurrentUrlMatches('~^/users/(\d+)~');
1010 ?>
1011 ```
1012
1013  * `param string` $uri
1014
1015
1016 ### seeElement
1017  
1018 Checks that the given element exists on the page and is visible.
1019 You can also specify expected attributes of this element.
1020
1021 ``` php
1022 <?php
1023 $I->seeElement('.error');
1024 $I->seeElement('//form/input[1]');
1025 $I->seeElement('input', ['name' => 'login']);
1026 $I->seeElement('input', ['value' => '123456']);
1027
1028 // strict locator in first arg, attributes in second
1029 $I->seeElement(['css' => 'form input'], ['name' => 'login']);
1030 ?>
1031 ```
1032
1033  * `param` $selector
1034  * `param array` $attributes
1035 @return
1036
1037
1038 ### seeInCurrentUrl
1039  
1040 Checks that current URI contains the given string.
1041
1042 ``` php
1043 <?php
1044 // to match: /home/dashboard
1045 $I->seeInCurrentUrl('home');
1046 // to match: /users/1
1047 $I->seeInCurrentUrl('/users/');
1048 ?>
1049 ```
1050
1051  * `param string` $uri
1052
1053
1054 ### seeInField
1055  
1056 Checks that the given input field or textarea *equals* (i.e. not just contains) the given value.
1057 Fields are matched by label text, the "name" attribute, CSS, or XPath.
1058
1059 ``` php
1060 <?php
1061 $I->seeInField('Body','Type your comment here');
1062 $I->seeInField('form textarea[name=body]','Type your comment here');
1063 $I->seeInField('form input[type=hidden]','hidden_value');
1064 $I->seeInField('#searchform input','Search');
1065 $I->seeInField('//form/*[@name=search]','Search');
1066 $I->seeInField(['name' => 'search'], 'Search');
1067 ?>
1068 ```
1069
1070  * `param` $field
1071  * `param` $value
1072
1073
1074 ### seeInFormFields
1075  
1076 Checks if the array of form parameters (name => value) are set on the form matched with the
1077 passed selector.
1078
1079 ``` php
1080 <?php
1081 $I->seeInFormFields('form[name=myform]', [
1082      'input1' => 'value',
1083      'input2' => 'other value',
1084 ]);
1085 ?>
1086 ```
1087
1088 For multi-select elements, or to check values of multiple elements with the same name, an
1089 array may be passed:
1090
1091 ``` php
1092 <?php
1093 $I->seeInFormFields('.form-class', [
1094      'multiselect' => [
1095          'value1',
1096          'value2',
1097      ],
1098      'checkbox[]' => [
1099          'a checked value',
1100          'another checked value',
1101      ],
1102 ]);
1103 ?>
1104 ```
1105
1106 Additionally, checkbox values can be checked with a boolean.
1107
1108 ``` php
1109 <?php
1110 $I->seeInFormFields('#form-id', [
1111      'checkbox1' => true,        // passes if checked
1112      'checkbox2' => false,       // passes if unchecked
1113 ]);
1114 ?>
1115 ```
1116
1117 Pair this with submitForm for quick testing magic.
1118
1119 ``` php
1120 <?php
1121 $form = [
1122      'field1' => 'value',
1123      'field2' => 'another value',
1124      'checkbox1' => true,
1125      // ...
1126 ];
1127 $I->submitForm('//form[@id=my-form]', $form, 'submitButton');
1128 // $I->amOnPage('/path/to/form-page') may be needed
1129 $I->seeInFormFields('//form[@id=my-form]', $form);
1130 ?>
1131 ```
1132
1133  * `param` $formSelector
1134  * `param` $params
1135
1136
1137 ### seeInSource
1138  
1139 Checks that the current page contains the given string in its
1140 raw source code.
1141
1142 ``` php
1143 <?php
1144 $I->seeInSource('<h1>Green eggs &amp; ham</h1>');
1145 ```
1146
1147  * `param`      $raw
1148
1149
1150 ### seeInTitle
1151  
1152 Checks that the page title contains the given string.
1153
1154 ``` php
1155 <?php
1156 $I->seeInTitle('Blog - Post #1');
1157 ?>
1158 ```
1159
1160  * `param` $title
1161
1162
1163
1164 ### seeLink
1165  
1166 Checks that there's a link with the specified text.
1167 Give a full URL as the second parameter to match links with that exact URL.
1168
1169 ``` php
1170 <?php
1171 $I->seeLink('Logout'); // matches <a href="#">Logout</a>
1172 $I->seeLink('Logout','/logout'); // matches <a href="/logout">Logout</a>
1173 ?>
1174 ```
1175
1176  * `param string` $text
1177  * `param string` $url optional
1178
1179
1180 ### seeNumberOfElements
1181  
1182 Checks that there are a certain number of elements matched by the given locator on the page.
1183
1184 ``` php
1185 <?php
1186 $I->seeNumberOfElements('tr', 10);
1187 $I->seeNumberOfElements('tr', [0,10]); // between 0 and 10 elements
1188 ?>
1189 ```
1190  * `param` $selector
1191  * `param mixed` $expected int or int[]
1192
1193
1194 ### seeOptionIsSelected
1195  
1196 Checks that the given option is selected.
1197
1198 ``` php
1199 <?php
1200 $I->seeOptionIsSelected('#form input[name=payment]', 'Visa');
1201 ?>
1202 ```
1203
1204  * `param` $selector
1205  * `param` $optionText
1206
1207
1208
1209 ### seePageNotFound
1210  
1211 Asserts that current page has 404 response status code.
1212
1213
1214 ### seeRecord
1215  
1216 Checks that record exists in database.
1217 You can pass the name of a database table or the class name of an Eloquent model as the first argument.
1218
1219 ``` php
1220 <?php
1221 $I->seeRecord('users', array('name' => 'davert'));
1222 $I->seeRecord('App\User', array('name' => 'davert'));
1223 ?>
1224 ```
1225
1226  * `param string` $table
1227  * `param array` $attributes
1228  * `[Part]` orm
1229
1230
1231 ### seeResponseCodeIs
1232  
1233 Checks that response code is equal to value provided.
1234
1235 ```php
1236 <?php
1237 $I->seeResponseCodeIs(200);
1238
1239 // recommended \Codeception\Util\HttpCode
1240 $I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK);
1241 ```
1242
1243  * `param` $code
1244
1245
1246 ### seeResponseCodeIsBetween
1247  
1248 Checks that response code is between a certain range. Between actually means [from <= CODE <= to]
1249
1250  * `param` $from
1251  * `param` $to
1252
1253
1254 ### seeResponseCodeIsClientError
1255  
1256 Checks that the response code is 4xx
1257
1258
1259 ### seeResponseCodeIsRedirection
1260  
1261 Checks that the response code 3xx
1262
1263
1264 ### seeResponseCodeIsServerError
1265  
1266 Checks that the response code is 5xx
1267
1268
1269 ### seeResponseCodeIsSuccessful
1270  
1271 Checks that the response code 2xx
1272
1273
1274 ### selectOption
1275  
1276 Selects an option in a select tag or in radio button group.
1277
1278 ``` php
1279 <?php
1280 $I->selectOption('form select[name=account]', 'Premium');
1281 $I->selectOption('form input[name=payment]', 'Monthly');
1282 $I->selectOption('//form/select[@name=account]', 'Monthly');
1283 ?>
1284 ```
1285
1286 Provide an array for the second argument to select multiple options:
1287
1288 ``` php
1289 <?php
1290 $I->selectOption('Which OS do you use?', array('Windows','Linux'));
1291 ?>
1292 ```
1293
1294 Or provide an associative array for the second argument to specifically define which selection method should be used:
1295
1296 ``` php
1297 <?php
1298 $I->selectOption('Which OS do you use?', array('text' => 'Windows')); // Only search by text 'Windows'
1299 $I->selectOption('Which OS do you use?', array('value' => 'windows')); // Only search by value 'windows'
1300 ?>
1301 ```
1302
1303  * `param` $select
1304  * `param` $option
1305
1306
1307 ### sendAjaxGetRequest
1308  
1309 If your page triggers an ajax request, you can perform it manually.
1310 This action sends a GET ajax request with specified params.
1311
1312 See ->sendAjaxPostRequest for examples.
1313
1314  * `param` $uri
1315  * `param` $params
1316
1317
1318 ### sendAjaxPostRequest
1319  
1320 If your page triggers an ajax request, you can perform it manually.
1321 This action sends a POST ajax request with specified params.
1322 Additional params can be passed as array.
1323
1324 Example:
1325
1326 Imagine that by clicking checkbox you trigger ajax request which updates user settings.
1327 We emulate that click by running this ajax request manually.
1328
1329 ``` php
1330 <?php
1331 $I->sendAjaxPostRequest('/updateSettings', array('notifications' => true)); // POST
1332 $I->sendAjaxGetRequest('/updateSettings', array('notifications' => true)); // GET
1333
1334 ```
1335
1336  * `param` $uri
1337  * `param` $params
1338
1339
1340 ### sendAjaxRequest
1341  
1342 If your page triggers an ajax request, you can perform it manually.
1343 This action sends an ajax request with specified method and params.
1344
1345 Example:
1346
1347 You need to perform an ajax request specifying the HTTP method.
1348
1349 ``` php
1350 <?php
1351 $I->sendAjaxRequest('PUT', '/posts/7', array('title' => 'new title'));
1352
1353 ```
1354
1355  * `param` $method
1356  * `param` $uri
1357  * `param` $params
1358
1359
1360 ### setApplication
1361  
1362  * `param \Laravel\Lumen\Application` $app
1363
1364
1365 ### setCookie
1366  
1367 Sets a cookie with the given name and value.
1368 You can set additional cookie params like `domain`, `path`, `expires`, `secure` in array passed as last argument.
1369
1370 ``` php
1371 <?php
1372 $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
1373 ?>
1374 ```
1375
1376  * `param` $name
1377  * `param` $val
1378  * `param array` $params
1379
1380
1381
1382 ### submitForm
1383  
1384 Submits the given form on the page, with the given form
1385 values.  Pass the form field's values as an array in the second
1386 parameter.
1387
1388 Although this function can be used as a short-hand version of
1389 `fillField()`, `selectOption()`, `click()` etc. it has some important
1390 differences:
1391
1392  * Only field *names* may be used, not CSS/XPath selectors nor field labels
1393  * If a field is sent to this function that does *not* exist on the page,
1394    it will silently be added to the HTTP request.  This is helpful for testing
1395    some types of forms, but be aware that you will *not* get an exception
1396    like you would if you called `fillField()` or `selectOption()` with
1397    a missing field.
1398
1399 Fields that are not provided will be filled by their values from the page,
1400 or from any previous calls to `fillField()`, `selectOption()` etc.
1401 You don't need to click the 'Submit' button afterwards.
1402 This command itself triggers the request to form's action.
1403
1404 You can optionally specify which button's value to include
1405 in the request with the last parameter (as an alternative to
1406 explicitly setting its value in the second parameter), as
1407 button values are not otherwise included in the request.
1408
1409 Examples:
1410
1411 ``` php
1412 <?php
1413 $I->submitForm('#login', [
1414     'login' => 'davert',
1415     'password' => '123456'
1416 ]);
1417 // or
1418 $I->submitForm('#login', [
1419     'login' => 'davert',
1420     'password' => '123456'
1421 ], 'submitButtonName');
1422
1423 ```
1424
1425 For example, given this sample "Sign Up" form:
1426
1427 ``` html
1428 <form action="/sign_up">
1429     Login:
1430     <input type="text" name="user[login]" /><br/>
1431     Password:
1432     <input type="password" name="user[password]" /><br/>
1433     Do you agree to our terms?
1434     <input type="checkbox" name="user[agree]" /><br/>
1435     Select pricing plan:
1436     <select name="plan">
1437         <option value="1">Free</option>
1438         <option value="2" selected="selected">Paid</option>
1439     </select>
1440     <input type="submit" name="submitButton" value="Submit" />
1441 </form>
1442 ```
1443
1444 You could write the following to submit it:
1445
1446 ``` php
1447 <?php
1448 $I->submitForm(
1449     '#userForm',
1450     [
1451         'user' => [
1452             'login' => 'Davert',
1453             'password' => '123456',
1454             'agree' => true
1455         ]
1456     ],
1457     'submitButton'
1458 );
1459 ```
1460 Note that "2" will be the submitted value for the "plan" field, as it is
1461 the selected option.
1462
1463 You can also emulate a JavaScript submission by not specifying any
1464 buttons in the third parameter to submitForm.
1465
1466 ```php
1467 <?php
1468 $I->submitForm(
1469     '#userForm',
1470     [
1471         'user' => [
1472             'login' => 'Davert',
1473             'password' => '123456',
1474             'agree' => true
1475         ]
1476     ]
1477 );
1478 ```
1479
1480 This function works well when paired with `seeInFormFields()`
1481 for quickly testing CRUD interfaces and form validation logic.
1482
1483 ``` php
1484 <?php
1485 $form = [
1486      'field1' => 'value',
1487      'field2' => 'another value',
1488      'checkbox1' => true,
1489      // ...
1490 ];
1491 $I->submitForm('#my-form', $form, 'submitButton');
1492 // $I->amOnPage('/path/to/form-page') may be needed
1493 $I->seeInFormFields('#my-form', $form);
1494 ```
1495
1496 Parameter values can be set to arrays for multiple input fields
1497 of the same name, or multi-select combo boxes.  For checkboxes,
1498 you can use either the string value or boolean `true`/`false` which will
1499 be replaced by the checkbox's value in the DOM.
1500
1501 ``` php
1502 <?php
1503 $I->submitForm('#my-form', [
1504      'field1' => 'value',
1505      'checkbox' => [
1506          'value of first checkbox',
1507          'value of second checkbox',
1508      ],
1509      'otherCheckboxes' => [
1510          true,
1511          false,
1512          false
1513      ],
1514      'multiselect' => [
1515          'first option value',
1516          'second option value'
1517      ]
1518 ]);
1519 ```
1520
1521 Mixing string and boolean values for a checkbox's value is not supported
1522 and may produce unexpected results.
1523
1524 Field names ending in `[]` must be passed without the trailing square
1525 bracket characters, and must contain an array for its value.  This allows
1526 submitting multiple values with the same name, consider:
1527
1528 ```php
1529 <?php
1530 // This will NOT work correctly
1531 $I->submitForm('#my-form', [
1532     'field[]' => 'value',
1533     'field[]' => 'another value',  // 'field[]' is already a defined key
1534 ]);
1535 ```
1536
1537 The solution is to pass an array value:
1538
1539 ```php
1540 <?php
1541 // This way both values are submitted
1542 $I->submitForm('#my-form', [
1543     'field' => [
1544         'value',
1545         'another value',
1546     ]
1547 ]);
1548 ```
1549
1550  * `param` $selector
1551  * `param` $params
1552  * `param` $button
1553
1554
1555 ### switchToIframe
1556  
1557 Switch to iframe or frame on the page.
1558
1559 Example:
1560 ``` html
1561 <iframe name="another_frame" src="http://example.com">
1562 ```
1563
1564 ``` php
1565 <?php
1566 # switch to iframe
1567 $I->switchToIframe("another_frame");
1568 ```
1569
1570  * `param string` $name
1571
1572
1573 ### uncheckOption
1574  
1575 Unticks a checkbox.
1576
1577 ``` php
1578 <?php
1579 $I->uncheckOption('#notify');
1580 ?>
1581 ```
1582
1583  * `param` $option
1584
1585 <p>&nbsp;</p><div class="alert alert-warning">Module reference is taken from the source code. <a href="https://github.com/Codeception/Codeception/tree/2.5/src/Codeception/Module/Lumen.php">Help us to improve documentation. Edit module reference</a></div>