| commit | author | age | ||
| 2207d6 | 1 | # Modules |
| W | 2 | |
| 3 | Modules are high-level extensions that are used in tests. Modules are created for each test suites (according to suite configuration) and can be accessed directly from unit tests: | |
| 4 | ||
| 5 | ```php | |
| 6 | <?php | |
| 7 | $this->getModule('PhpBrowser')->client; | |
| 8 | ?> | |
| 9 | ``` | |
| 10 | ||
| 11 | or used inside scenario-driven tests, where `$I` acts as an wrapper to different modules | |
| 12 | ||
| 13 | ```php | |
| 14 | <?php | |
| 15 | $I->click(); // => PhpBrowser | |
| 16 | $I->seeInDatabase(); // => Db | |
| 17 | ?> | |
| 18 | ``` | |
| 19 | ||
| 20 | Each module is extending `Codeception\Module` class and defined in `Codeception\Module` namespace. All Codeception modules are autoloaded by searching in this particular namespace: `PhpBrowser` => `Codeception\Module\PhpBrowser`. | |
| 21 | ||
| 22 | ## What you should know before developing a module | |
| 23 | ||
| 24 | The core principles: | |
| 25 | ||
| 26 | 1. Public methods of modules are actions of an actor inside a test. That's why they should be named in proper format: | |
| 27 | ||
| 28 | ``` | |
| 29 | doSomeStuff() => $I->doSomeStuff() => I do some stuff | |
| 30 | doSomeStuffWith($a, $b) => $I->doSomeStuffWith("vodka", "gin"); => I do some stuff with "vodka", "gin" | |
| 31 | seeIsGreat() => $I->seeIsGreat() => I see is great | |
| 32 | ``` | |
| 33 | ||
| 34 | * Each method that define environment should start with `am` or `have` | |
| 35 | * Each assertion should start with `see` prefix | |
| 36 | * Each method that returns values should start with `grab` (grabbers) or `have` (definitions) | |
| 37 | ||
| 38 | Example: | |
| 39 | ||
| 40 | ```php | |
| 41 | $I->amSeller(); | |
| 42 | $I->haveProducts(['vodka', 'gin']); | |
| 43 | $I->haveDiscount('0.1'); | |
| 44 | $I->setPrice('gin', '10$'); | |
| 45 | $I->seePrice('gin', '9.9'); | |
| 46 | $price = $I->grabPriceFor('gin'); | |
| 47 | ``` | |
| 48 | ||
| 49 | 2. Configuration parameters are set in `.suite.yml` config and stored in `config` property array of a module. All default values can be set there as well. Required parameters should be set in `requiredFields` property. | |
| 50 | ||
| 51 | ```php | |
| 52 | <?php | |
| 53 | protected $config = ['browser' => 'firefox']; | |
| 54 | protected $requiredFields = ['url']; | |
| 55 | ?> | |
| 56 | ``` | |
| 57 | ||
| 58 | You should not perform validation if `url` was set. Module would perform it for you, so you could access `$this->config['url']` inside a module. | |
| 59 | ||
| 60 | 3. If you use low-level clients in your module (PDO driver, framework client, selenium client) you should allow developers to access them. That's why you should define their instances as `public` properties of method. | |
| 61 | ||
| 62 | Also you *may* provide a closure method to access low-level API | |
| 63 | ||
| 64 | ```php | |
| 65 | <?php | |
| 66 | $I->executeInSelenium(function(\WebDriverClient $wb) { | |
| 67 | $wd->manage()->addCookie(['name' => 'verified']); | |
| 68 | }); | |
| 69 | ?> | |
| 70 | ``` | |
| 71 | ||
| 72 | 4. Modules can be added to official repo, or published standalone. In any case module should be defined in `Codeception\Module` namespace. If you develop a module and you think it might be useful to others, please ask in Github Issues, maybe we would like to include it into the official repo. | |
