|
| 1 | +<meta http-equiv="refresh" content="0;url=https://github.com/lucatume/wp-browser"> |
1 | 2 | --- |
2 | 3 | layout: page |
3 | 4 | title: Codeception for WordPress |
4 | 5 | hero: wp_hero.html |
5 | | -sidebar: | |
6 | | -
|
7 | | - ## Codeception Tests |
8 | | -
|
9 | | - * Combine **all testing levels** (acceptance, functional, integration, unit) |
10 | | - * Use WordPress defined functions, constants, classes and methods in any test |
11 | | - * Can be written in **BDD** format with Gherkin |
12 | | -
|
13 | | - ## Reference |
14 | | -
|
15 | | - * [WPBrowser modules library](https://github.com/lucatume/wp-browser) |
16 | | - * [Tools and Tutorials](http://theaveragedev.com) |
17 | | - * [WordPress demo plugin](https://github.com/lucatume/idlikethis) |
18 | | -
|
19 | | - --- |
20 | | -
|
21 | | - Written by [**Luca Tumedei**](https://github.com/lucatume) |
22 | 6 |
|
23 | 7 | --- |
24 | | - |
25 | | -## Install |
26 | | - |
27 | | -Install latest stable WPBrowser package via Composer (WPBrowser will install Codeception for you): |
28 | | - |
29 | | -```bash |
30 | | -composer require lucatume/wp-browser --dev |
31 | | -``` |
32 | | - |
33 | | -If a dependency resolution issue arises and you have previously installed `codeception/codeception` try removing it and requiring just `lucatume/wp-browser`: |
34 | | - |
35 | | -```bash |
36 | | -composer remove codeception/codeception --dev |
37 | | -composer require lucatume/wp-browser --dev |
38 | | -``` |
39 | | - |
40 | | -WPBrowser will install the latest version of Codeception for you. |
41 | | - |
42 | | -## Setup |
43 | | - |
44 | | -To fully use the WordPress specific modules of the WPBrowser suite you need to setup a local WordPress installation; this is in no way different from what's required to locally develop a WordPress theme or plugin. |
45 | | -In the examples below I assume that the local WordPress installation root directory is `/var/www/wordpress`, that it responds at the `http://wordpress.localhost` URL and that I am developing a plugin called "Acme Plugin". |
46 | | -While it's possible to start from a default Codeception configuration the WPBrowser package comes with its own initialization template that can be called using: |
47 | | - |
48 | | -```bash |
49 | | -./vendor/bin/codecept init wpbrowser |
50 | | -``` |
51 | | - |
52 | | -The command offers the possibility to scaffold an empty suite or to undergo an interactive setup that will end in a ready to run Codeception for WordPress installation; it will create the `tests` directory and scaffold the `acceptance`, `functional`, `wpunit` and `unit` suites creating a `tests` sub-directory and a configuration file for each. |
53 | | -If you did not use the step-by-step initialization then edit each suite configuration file (e.g. `tests/functional.suite.yml` for the functional suite) to match your local WordPress setup and point the modules to the local WordPress installation folder, the local WordPress URL and so on. |
54 | | -If you are using the `WPLoader` module in your tests take care to create a dedicated database for it and not to use the same database the `Db` or `WPDb` modules might use. |
55 | | -The use of the modules defined in the WPBrowser package is not tied to this bootstrap though so feel free to set up Codeception in any other way. |
56 | | - |
57 | | -## Setting Environment variables |
58 | | -If you have used the initialization template, you'll need to set Codeception to [load parameters](https://codeception.com/docs/06-ModulesAndHelpers#dynamic-configuration-with-parameters) from the environment variables. You can do this by updating the `params` key in your codeception.dist.yaml to |
59 | | -``` |
60 | | -params: |
61 | | - - .env.testing |
62 | | -``` |
63 | | -This will load the environment variables from the `.env.testing` file. |
64 | | - |
65 | | -## Integration Tests |
66 | | -Commonly "WordPress unit tests" (hence the `wpunit` default name of the suite) are not related to classical unit tests but to integration tests. The difference is that unit tests are supposed to test a class methods in complete isolation, while integration tests check how components work inside WordPress. That's why, to prepare WordPress for testing, you should enable `WPLoader` module into `wpunit.suite.yml`. |
67 | | -The `WPLoader` module: it takes care of loading, installing and configuring a fresh WordPress installation before each test method runs. |
68 | | -To handle the heavy lifting the module requires some information about the local WordPress installation: in the `codeception.yml` file configure it to match your local setup; with reference to the example above the module configuration might be: |
69 | | - |
70 | | -```yaml |
71 | | -modules: |
72 | | - config: |
73 | | - WPLoader: |
74 | | - wpRootFolder: /var/www/wordpress |
75 | | - dbName: wordpress-tests |
76 | | - dbHost: localhost |
77 | | - dbUser: root |
78 | | - dbPassword: root |
79 | | - wpDebug: true |
80 | | - tablePrefix: wptests_ |
81 | | - domain:wordpress.localhost |
82 | | - plugins: |
83 | | - - acme-plugin/plugin.php |
84 | | - activatePlugins: |
85 | | - - acme-plugin/plugin.php |
86 | | -``` |
87 | | -
|
88 | | -The module is wrapping and augmenting the [WordPress Core automated testing suite](https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/) and to generate a test case that uses Codeception and the methods provided by the Core testing suite you can use the generation command provided by the package: |
89 | | -
|
90 | | -```bash |
91 | | -./vendor/bin/codecept generate:wpunit wpunit "Acme\SomeClass" |
92 | | -``` |
93 | | - |
94 | | -The generated test case extends the `WPTestCase` class and it exposes all the mehtods defined by `Codeception\Test\Unit` test case and the Core suite `\WP_UnitTestCase`. |
95 | | -Additional test method generation possibilities are available to cover the primitive test cases offered in the Core testing suite using `wpajax`, `wprest`, `wpcanonical`, `wpxmlrpc` as arguments for the `generate` sub-command. |
96 | | - |
97 | | -Any database interaction is wrapped in a transaction to guarantee isolation between tests. |
98 | | - |
99 | | -<div class="alert alert-warning"> |
100 | | - <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
101 | | - Continue to <a href="http://codeception.com/docs/05-UnitTests">Unit Testing Guide »</a>. |
102 | | -</div> |
103 | | - |
104 | | -## WordPress Functional Tests |
105 | | -Functional tests are meant to test requests handling and end-to-end interactions. |
106 | | -WPBrowser will scaffold functional tests to use the `WordPress`, `WPDb` and `Filesystem` modules. |
107 | | -While the latter is the one defined by the Codeception suite `WordPress` and `WPDb` modules extend the Codeception framework and `Db` modules with WordPress specific methods. |
108 | | -The modules will require some WordPress specific setup parameters: |
109 | | - |
110 | | -```yaml |
111 | | -modules: |
112 | | - enabled: |
113 | | - - Filesystem |
114 | | - WPDb: |
115 | | - dsn: 'mysql:host=localhost;dbname=wordpress' |
116 | | - user: root |
117 | | - password: root |
118 | | - dump: tests/_data/wp.sql |
119 | | - populate: true |
120 | | - cleanup: true |
121 | | - url: 'http://wordpress.localhost' |
122 | | - tablePrefix: wp_ |
123 | | - WordPress: |
124 | | - depends: WPDb |
125 | | - wpRootFolder: /var/www/wordpress |
126 | | - adminUsername: admin |
127 | | - adminPassword: password |
128 | | - adminPath: /wp-admin |
129 | | -``` |
130 | | -
|
131 | | -To generate a functional test use the default `codecept` commmand. |
132 | | - |
133 | | -```bash |
134 | | -./vendor/bin/codecept generate:cept functional "PostInsertion" |
135 | | -``` |
136 | | - |
137 | | -<div class="alert alert-warning"> |
138 | | - <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
139 | | - Continue to <a href="http://codeception.com/docs/04-FunctionalTests">Functional Teseting Guide »</a>. |
140 | | -</div> |
141 | | - |
142 | | -## Acceptance Tests |
143 | | - |
144 | | -To test a WordPress theme or plugin functionalities using its UI you should simulate the user interaction with a browser both in the site front-end and back-end. |
145 | | -You can use the `WebDriver` and `Db` modules defined by Codeception but the WPBrowser package extends those modules in the `WPWebDriver` and `WPDb` modules to add WordPress specific methods to each. |
146 | | -The `WPWebDriver` module drives a real browser in the same way the `WebDriver` does. |
147 | | -The modules require some WordPress specific parameters to work: |
148 | | - |
149 | | -```yaml |
150 | | -modules: |
151 | | - enabled: |
152 | | - WPWebDriver: |
153 | | - url: 'http://wordpress.localhost' |
154 | | - browser: phantomjs |
155 | | - port: 4444 |
156 | | - restart: true |
157 | | - wait: 2 |
158 | | - adminUsername: admin |
159 | | - adminPassword: password |
160 | | - adminUrl: /wp-admin |
161 | | -``` |
162 | | - |
163 | | -As the `WebDriver` module the `WPWebDriver` module require a Selenium or PhantomJS server to run. |
164 | | -The `WPDb` module allows for quick interactions with the WordPress database API like quick generation of multiple posts, database value fetching and more: |
165 | | - |
166 | | -```php |
167 | | -<?php |
168 | | -$I->haveManyPostsInDatabase(10, ['post_type' => 'custom_post_type']); |
169 | | -$transient = $I->grabTransientFromDatabase('some_transient'); |
170 | | -``` |
171 | | -`WPWebDriver` methods wrap complex interactions with the WordPress UI into sugar methods like: |
172 | | - |
173 | | -```php |
174 | | -<?php |
175 | | -$I->loginAsAdmin(); |
176 | | -$I->amOnPluginsPage(); |
177 | | -$I->activatePlugin('acme-plugin'); |
178 | | -``` |
179 | | - |
180 | | -## BDD |
181 | | - |
182 | | -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: |
183 | | - |
184 | | -``` |
185 | | -ln -s $PWD/features tests/acceptance |
186 | | -``` |
187 | | - |
188 | | -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`. |
189 | | - |
190 | | -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. |
191 | | - |
192 | | -``` |
193 | | -./vendor/bin/codecept gherkin:snippets |
194 | | -``` |
195 | | -
|
196 | | -In the same manner features can be set up as functional tests. |
197 | | -
|
198 | | -Methods defined in WPBrowser `WPWebDriver` and `WPDb` modules can offer a base to implement the steps: |
199 | | -
|
200 | | -```php |
201 | | -<?php |
202 | | -/** |
203 | | - * @Given I login as administrator |
204 | | - */ |
205 | | -public function iLoginAsAdministrator() |
206 | | -{ |
207 | | - // from WPBrowser or WPWebDriver module |
208 | | - $this->loginAsAdmin(); |
209 | | -} |
210 | | -
|
211 | | -/** |
212 | | - * @Then I see CSS option is set |
213 | | - */ |
214 | | -public function iSeeCssOptionIsSet() |
215 | | -{ |
216 | | - // from WPDb module |
217 | | - $this->seeOptionInDatabase('acme_css_option'); |
218 | | -} |
219 | | -``` |
220 | | - |
221 | | -<div class="alert alert-warning"> |
222 | | - <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span> |
223 | | - Continue to <a href="http://codeception.com/docs/07-BDD">Behavior Driven Development Guide »</a> |
224 | | -</div> |
0 commit comments