README.md 6.92 KB
Newer Older
1 2 3
Codeception Extension for Yii 2
===============================

4
This extension provides [Codeception](http://codeception.com/) integration for the Yii Framework 2.0.
5

6
It provides classes that help with testing with codeception:
7

8
- a base class for unit-tests: `yii\codeception\TestCase`;
9 10 11 12 13 14 15 16 17 18 19
- a base class for codeception page-objects: `yii\codeception\BasePage`.


Installation
------------

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```
20
php composer.phar require --prefer-dist yiisoft/yii2-codeception "*"
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
```

or add

```json
"yiisoft/yii2-codeception": "*"
```

to the require section of your composer.json.


Usage
-----

When using codeception page-objects they have some similar code, this code was extracted and put into the `BasePage`
class to reduce code duplication. Simply extend your page object from this class, like it is done in `yii2-app-basic` and
`yii2-app-advanced` boilerplates.

For unit testing there is a `TestCase` class which holds some common features like application creation before each test
and application destroy after each test. You can configure a mock application using this class.
41 42 43
`TestCase` is extended from `Codeception\TestCase\Case` so all methods and assertions are available.
You may use codeception modules and fire events in your test, just use methods:

Mark committed
44 45 46
Getting Codeception modules
---------------------------

Mark committed
47 48
If you want to use codeception modules and helpers in your unit tests, you can do it like this:

49 50 51 52 53 54 55 56 57 58 59 60
```php
<?php
#in your unit-test
$this->getModule('CodeHelper'); #or some other module
```

You also can use all guy methods by accessing guy instance like:

```php
<?php
$this->codeGuy->someMethodFromModule();
```
Mark committed
61 62
Codeception events
------------------
63

Mark committed
64
To fire event do this:
65 66 67 68 69 70 71 72 73 74 75 76 77

```php
<?php
use Codeception\Event\TestEvent;

public function testSomething()
{
	$this->fire('myevent', new TestEvent($this));
}
```
this event can be catched in modules and helpers. If your test is in the group, then event name will be followed by the groupname, 
for example ```myevent.somegroup```.

Mark committed
78

Mark committed
79 80
Special test method chaining
----------------------------
Mark committed
81

82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
Execution of special tests methods is (for example on ```UserTest``` class):

```
tests\unit\models\UserTest::setUpBeforeClass();

	tests\unit\models\UserTest::_before();

		tests\unit\models\UserTest::setUp();

			tests\unit\models\UserTest::testSomething();

		tests\unit\models\UserTest::tearDown();

	tests\unit\models\UserTest::_after();

tests\unit\models\UserTest::tearDownAfterClass();
```

If you use special methods dont forget to call its parent.
101

Mark committed
102 103 104
Customizing application config
------------------------------

Mark committed
105 106
You may need to specify different configuration files per test cases, to do this you can make it like the following:

107
```php
108 109 110
<?php

SomeConsoleTest extends \yii\codeception\TestCase
111
{
112
	// this is the config file to load as application config
113
	public $appConfig = '@app/path/to/my/custom/config/for/test.php';
114 115 116
}
```

Mark committed
117 118 119
The `$appConfig` property could be an array or a valid alias, pointing to the file that returns a config array. You can specify
application class in the config, for example for testing console commands or features you can create `_console.php` config under
`tests/unit` directory like this:
120 121

```php
122
return yii\helpers\ArrayHelper::merge(
Mark committed
123 124 125 126 127 128 129 130
	require(__DIR__ . '/../../config/console.php'),
	require(__DIR__ . '/../_config.php'),
	[
		'class' => 'yii\console\Application',
		'components' => [
			//override console components if needed
		],
	]
131 132 133
);
```

Mark committed
134
and then just use your `ConsoleTestCase` like the following:
135 136 137 138 139 140 141 142 143 144 145

```php

use \yii\codeception\TestCase;

class ConsoleTestCase extends TestCase
{
	public $appConfig = '@tests/unit/_console.php';
}
```

Mark committed
146
You can extend other console test cases from this basic `ConsoleTestCase`.
147

Mark committed
148 149
Reconfiguring components for testing
------------------------------------
Mark committed
150

Mark committed
151
You can reconfigure a component for testing, for this purpose in your `setUp` method of your test case 
152
you can do this for example:
153 154

```php
155 156
<?php

157 158 159 160
use \yii\codeception\TestCase;
use Yii;

class MailTest extends TestCase
161
{
162 163 164

	protected function setUp()
	{
Mark committed
165
		// don't forget to call parent method that will setup Yii application
166 167 168 169 170 171 172
		parent::setUp();

		Yii::$app->mail->fileTransportCallback = function ($mailer, $message) {
			return 'testing_message.eml';
		};
	}

173 174 175
}
```

Mark committed
176 177
> **Tip**: You also can reconfigure Yii components and properties with method `Yii::configure()`.

Mark committed
178 179 180
You don't need to worry about application instances and isolation because application will be created [each time](https://github.com/yiisoft/yii2/blob/master/extensions/codeception/TestCase.php#L31) before any of test method will be executed in test case.
You can mock application in a different way. For this purposes you have method [`mockApplication`](https://github.com/yiisoft/yii2/blob/master/extensions/codeception/TestCase.php#L55) available in your test case.
This method creates new application instance and replaces old one with it and is handy when you need to create application with a config that is different from other test methods in the current test suite. For example:
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213

```php

use \yii\codeception\TestCase;

class SomeMyTest extends TestCase
{

	public function testOne()
	{
		...
	}

	public function testTwo()
	{
		$this->mockApplication([
			'language' => 'ru-RU',
			'components' => [
				'db' => [
					//your custom configuration here
				],
			],
		]);

		//your expectations and assertions goes here
	}

	public function testThree()
	{
		...
	}

}
Mark committed
214
```
215

Mark committed
216 217
Additional debug output
-----------------------
218

219 220
Because of Codeception buffers all output you can't make simple `var_dump()` in the TestCase, instead you need to use
`Codeception\Util\Debug::debug()` function and then run test with `--debug` key, for example:
221 222

```php
223
<?php
224

225
use Codeception\Util\Debug;
226

227
SomeDebugTest extends \yii\codeception\TestCase
228 229 230
{
	public function testSmth()
	{
231
		Debug::debug('some string');
232 233 234 235 236 237 238
		Debug::debug($someArray);
		Debug::debug($someObject);
	}

}
```

239
Then run command `php codecept.phar run --debug unit/SomeDebugTest` and you will see in output:
240 241

```html
242
  some string
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269

  Array
  (
      [0] => 1
      [1] => 2
      [2] => 3
      [3] => 4
      [4] => 5
  )
  
  yii\web\User Object
  (
      [identityClass] => app\models\User
      [enableAutoLogin] => 
      [loginUrl] => Array
          (
              [0] => site/login
          )
  
      [identityCookie] => Array
          (
              [name] => _identity
              [httpOnly] => 1
          )
  
      [authTimeout] => 
      [autoRenewCookie] => 1
270 271 272
      [idParam] => __id
      [authTimeoutParam] => __expire
      [returnUrlParam] => __returnUrl
273 274 275 276 277 278 279 280 281 282 283
      [_access:yii\web\User:private] => Array
          (
          )
  
      [_identity:yii\web\User:private] => 
      [_events:yii\base\Component:private] => 
      [_behaviors:yii\base\Component:private] => 
  )

```

284
For further instructions refer to the testing section in the [Yii Definitive Guide](https://github.com/yiisoft/yii2/blob/master/docs/guide/testing.md).