|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: Codeception for Laravel |
| 4 | +hero: laravel_hero.html |
| 5 | +sidebar: | |
| 6 | +
|
| 7 | + ## Codeception Tests |
| 8 | +
|
| 9 | + * Combine **all testing levels** (acceptance, functional, unit) |
| 10 | + * Allow **multi-request** functional tests |
| 11 | + * **Fast**: Tests are wrapped into Eloquent transaction |
| 12 | + * **Scenario-Driven**: described in easy to get PHP DSL |
| 13 | + * can be written in **BDD** format with Gherkin |
| 14 | + * Great for **REST** and SOAP API testing |
| 15 | +
|
| 16 | + ## Reference |
| 17 | +
|
| 18 | + * [Laravel5 Module](/docs/modules/Laravel5) |
| 19 | + * [Demo Application](https://github.com/janhenkgerritsen/codeception-laravel5-sample) |
| 20 | +
|
| 21 | +--- |
| 22 | + |
| 23 | +## Install |
| 24 | + |
| 25 | +Install latest stable Codeception via Composer: |
| 26 | + |
| 27 | +```bash |
| 28 | +composer require codeception/codeception --dev |
| 29 | +``` |
| 30 | + |
| 31 | +## Setup |
| 32 | + |
| 33 | +It is easy to setup tests by running bootstrap command: |
| 34 | + |
| 35 | +``` |
| 36 | +composer exec codecept bootstrap |
| 37 | +``` |
| 38 | + |
| 39 | +This will create `tests` directory and configuration file `codeception.yml`. This also prepares 3 suites for testing: acceptance, functional, and unit. You will also need to prepare .env file for testing environment: |
| 40 | + |
| 41 | +``` |
| 42 | +cp .env .env.testing |
| 43 | +``` |
| 44 | + |
| 45 | +## Functional Tests |
| 46 | + |
| 47 | +Functional tests allow test application by simulating user actions, this is done by sending requests to framework kernel and checking HTML as a result. Unilke internal tests of Laravel, Codeception doesn't limit you to testing only one request per test. You can **test complex interactions involving different actions and controllers**. This way you can easily cover your specifictions with functional tests. |
| 48 | + |
| 49 | +To start you need to configure `tests/functional.suite.yml` to use Laravel5 module: |
| 50 | + |
| 51 | +```yaml |
| 52 | +class_name: FunctionalTester |
| 53 | +modules: |
| 54 | + enabled: |
| 55 | + - Laravel5: |
| 56 | + environment_file: .env.testing |
| 57 | + - \AppBundle\Helper\Functional |
| 58 | +``` |
| 59 | +
|
| 60 | +
|
| 61 | +<div class="alert alert-warning"> |
| 62 | + <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
| 63 | + Continue to <a href="http://codeception.com/docs/04-FunctionalTests">Functional Testing Guide »</a> |
| 64 | +</div> |
| 65 | +
|
| 66 | +Codeception will also use **Eloquent to cleanup changes to database** by wrapping tests into transaction and rolling it back in the end of a test. This makes tests isolated and fast. Laravel5 module allows to access services from DIC container, user authentication methods, fixture generators, check form validations and more. |
| 67 | +
|
| 68 | +To create first functional test for `Login` you should run: |
| 69 | + |
| 70 | +``` |
| 71 | +composer exec codecept g:cest functional Login |
| 72 | +``` |
| 73 | +
|
| 74 | +## Unit Tests |
| 75 | +
|
| 76 | +Codeception is powered by PHPUnit so unit and integration test work in a similar manner. To genereate a plain PHPUnit test for `Foo\Bar` class |
| 77 | +
|
| 78 | +``` |
| 79 | +php bin/codecept g:phpunit unit "Foo\Bar" |
| 80 | +``` |
| 81 | +
|
| 82 | +This generates a standard test inherited from `PHPUnit_Framework_TestCase`. For integration tests you may use Codeception-enhanced format which allows accessing services from DI container, use Eloquent, Data Factories. To have it create a unit test extending `Codeception\Test\Unit` class: |
| 83 | +
|
| 84 | +``` |
| 85 | +php bin/codecept g:test unit "Foo\Bar" |
| 86 | +``` |
| 87 | +
|
| 88 | +You will need to enable Laravel5 module in `unit.suite.yml` to have its methods inside `$this->tester` object. |
| 89 | +
|
| 90 | +<div class="alert alert-warning"> |
| 91 | + <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
| 92 | + Continue to <a href="http://codeception.com/docs/05-UnitTests">Unit Testing Guide »</a>. |
| 93 | +</div> |
| 94 | +
|
| 95 | +
|
| 96 | +### Acceptance Tests |
| 97 | +
|
| 98 | +To test an application in a real environment by using its UI you should use a real browser. Codeception uses Selenium Webdriver and corresponding WebDriver module to interact with a browser. You should configure `acceptance.suite.yml` to use WebDriver module and a browser of your choice. |
| 99 | +
|
| 100 | +```yaml |
| 101 | +class_name: AcceptanceTester |
| 102 | +modules: |
| 103 | + enabled: |
| 104 | + - WebDriver: |
| 105 | + url: 'https://localhost/' # put your local url |
| 106 | + browser: firefox |
| 107 | + - \Helper\Acceptance |
| 108 | +``` |
| 109 | + |
| 110 | +Browser can be specified as `firefox`, `chrome`, `phantomjs`, or others. |
| 111 | + |
| 112 | +Acceptance tests will be executed in development environment using real web server, so settings from `.env.testing` can't be passed to them. |
| 113 | + |
| 114 | +You can also use Eloquent to create data for acceptance tests. This way you can use data factories and models to prepare and cleanup data for tests. You should enable Laravel5 module with ORM part to add ActiveRecord methods: |
| 115 | + |
| 116 | +```yaml |
| 117 | +class_name: AcceptanceTester |
| 118 | +modules: |
| 119 | + enabled: |
| 120 | + - WebDriver: |
| 121 | + url: 'https://localhost/' # put your local url |
| 122 | + browser: firefox |
| 123 | + - Laravel5 |
| 124 | + part: ORM |
| 125 | + cleanup: false # can't wrap into transaction |
| 126 | + - \Helper\Acceptance |
| 127 | +``` |
| 128 | +
|
| 129 | +Laravel5 module won't be able to wrap test execution in a transaction but methods like `haveRecord` or `haveModel` will delete objects they created when test ends. |
| 130 | + |
| 131 | +### API Tests |
| 132 | + |
| 133 | +API Tests are done at functional testing level but instead of testing HTML responses on user actions, they test requests and responses via protocols like REST or SOAP. To create api tests you should create a suite for them |
| 134 | + |
| 135 | +``` |
| 136 | +php bin/codecept g:suite api |
| 137 | +``` |
| 138 | +
|
| 139 | +You will need to enable `REST`, `Laravel5` module in `tests/api.suite.yml`: |
| 140 | +
|
| 141 | +```yaml |
| 142 | +class_name: ApiTester |
| 143 | +modules: |
| 144 | + enabled: |
| 145 | + - REST: |
| 146 | + url: /api/v1 |
| 147 | + depends: Laravel5 |
| 148 | + - \ApiBundle\Helper\Api |
| 149 | + config: |
| 150 | + - Laravel5: |
| 151 | + environment_file: .env.testing |
| 152 | +
|
| 153 | +``` |
| 154 | + |
| 155 | +Laravel5 module actions like `amOnPage` or `see` should not be available for testing API. This why Laravel5 module is not enabled but declared with `depends` for REST module. Laravel5 should use testing environment which is specified in `config` section |
| 156 | + |
| 157 | + |
| 158 | +<div class="alert alert-warning"> |
| 159 | + <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
| 160 | + Continue to <a href="http://codeception.com/docs/10-WebServices#REST">REST API Testing Guide »</a>. |
| 161 | +</div> |
| 162 | + |
| 163 | +### BDD |
| 164 | + |
| 165 | +If you prefer to describe application with feature files, Codeception can turn them to acceptance or functional tests. It is recommended to store feature files in `features` directory (like it does Behat) but symlinking it to `tests/acceptance/features` or `tests/functional/features` so they can be treated as tests too. For using BDD with acceptance tests you need to run: |
| 166 | + |
| 167 | +``` |
| 168 | +ln -s $PWD/features tests/acceptance |
| 169 | +``` |
| 170 | + |
| 171 | +Codeception allows to combine tests written in different formats. If are about to wirite a regression test it probably should not be described as a product's feature. That's why feature-files is subset of all acceptance tests, and they are stored in subfolder of `tests/acceptance`. |
| 172 | + |
| 173 | +There is no standard Gherkin steps built in. By writing your feature files you can get code snippets which should be added to `AcceptanceTester` class. |
| 174 | + |
| 175 | +``` |
| 176 | +composer exec codecept gherkin:snippets |
| 177 | +``` |
| 178 | + |
| 179 | +In the same manner features can be set up as functional tests. |
| 180 | + |
| 181 | +<div class="alert alert-warning"> |
| 182 | + <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
| 183 | + Continue to <a href="http://codeception.com/docs/07-BDD">Behavior Driven Development Guide »</a> |
| 184 | +</div> |
0 commit comments