| layout | doc |
|---|---|
| title | Customization - Codeception - Documentation |
In this chapter we will explain how you can extend and customize file structure and test execution routines.
In case your project consists of several applications (frontend, admin, api) or you use Symfony2 framework with its bundles, you may be interested in having all tests for all applications (bundles) to be executed in one runner. In this case you will get one report that covers the whole project.
Place codeception.yml file into root folder of your project and specify paths to other codeception.yml configs you want to include.
{% highlight yaml %}
include:
- frontend
- admin
- api/rest paths: log: log settings: colors: false
{% endhighlight %}
You should also specify path to log directory, where the reports and logs will be stored.
To avoid naming conflicts between Actor classes and Helper classes, they should be added into namespaces.
To create test suites with namespaces you can add --namespace option to bootstrap command.
{% highlight bash %}
$ php codecept.phar bootstrap --namespace frontend
{% endhighlight %}
This will bootstrap a new project with namespace: frontend parameter in codeception.yml file.
Helpers will be in frontend\Codeception\Module namespace and Actor classes will be in frontend namespace.
Thus, newly generated tests will look like this:
{% highlight php %}
{% endhighlight %}
Once each of your applications (bundles) has its own namespace and different Helper or Actor classes, you can execute all tests in one runner. Run codeception tests as usual, using meta-config we created earlier:
{% highlight bash %}
$ php codecept.phar run
{% endhighlight %}
This will launch test suites for all 3 applications and merge the reports from all of them. Basically that would be very useful when you run your tests on Continuous Integration server and you want to get one report in JUnit and HTML format. Codecoverage report will be merged too.
If your applications uses same helpers, follow the next section of this chapter.
There is global _bootstrap.php file. This file is included at the very beginning of execution. We recommend to use it to initialize autoloaders and constants. It is especially useful if you want to include Modules or Helper classes that are not stored in tests/_helpers directory.
{% highlight php %}
{% endhighlight %}
Alternatively you can use Composer's autoloader. Codeception has its autoloader too. It's not PSR-0 compatible (yet), but it is still very useful when you need to declare alternative path for Helper classes:
{% highlight php %}
{% endhighlight %}
Now all classes with suffix Helper will be additionally searched in `DIR.'/../lib/tests/helpers'. You can declare to load helpers of specific namespace.
{% highlight php %}
{% endhighlight %}
That will point autoloader to look for classes like MyApp\Test\MyHelper in path __DIR__.'/../lib/tests/helpers'.
Alternatively you can use autoloader to specify path for PageObject and Controller classes, if they have appropriate suffixes in their names.
Example of tests/_bootstrap.php file:
{% highlight php %}
{% endhighlight %}
Codeception has limited capabilities to extend its core features. Extensions are not supposed to override current functionality, but are pretty useful if you are experienced developer and you want to hook into testing flow.
Basically speaking, Extensions are nothing more then event listeners based on Symfony Event Dispatcher component.
Here are the events and event classes. The events are listed in order they happen during execution. Each event has a corresponding class, which is passed to listener, and contains specific objects.
| Event | When? | What contains? |
|---|---|---|
suite.before |
Before suite is executed | Suite, Settings |
test.start |
Before test is executed | Test |
test.before |
At the very beginning of test execution | Codeception Test |
step.before |
Before step | Step |
step.after |
After step | Step |
step.fail |
After failed step | Step |
test.fail |
After failed test | Test, Fail |
test.error |
After test ended with error | Test, Fail |
test.incomplete |
After executing incomplete test | Test, Fail |
test.skipped |
After executing skipped test | Test, Fail |
test.success |
After executing successful test | Test |
test.after |
At the end of test execution | Codeception Test |
test.end |
After test execution | Test |
suite.after |
After suite was executed | Suite, Result, Settings |
test.fail.print |
When test fails are printed | Test, Fail |
result.print.after |
After result was printed | Result, Printer |
There may be a confusion between test.start/test.before and test.after/test.end. Start/end events are triggered by PHPUnit itself. But before/after events are triggered by Codeception. Thus, when you have classical PHPUnit test (extended from PHPUnit_Framework_TestCase), before/after events won't be triggered for them. On test.before event you can mark test as skipped or incomplete, which is not possible in test.start. You can learn more from Codeception internal event listeners.
The extension class itself is inherited from Codeception\Platform\Extension.
{% highlight php %}
'afterSuite', 'test.before' => 'beforeTest', 'step.before' => 'beforeStep', 'test.fail' => 'testFailed', 'result.print.after' => 'print', ); // methods that handle events public function afterSuite(\Codeception\Event\SuiteEvent $e) {} public function beforeTest(\Codeception\Event\TestEvent $e) {} public function beforeStep(\Codeception\Event\StepEvent $e) {} public function testFailed(\Codeception\Event\FailEvent $e) {} public function print(\Codeception\Event\PrintResultEvent $e) {} } ?>{% endhighlight %}
By implementing event handling methods you can listen to event and even update passed objects. Extensions have some basic methods you can use:
write- prints to screenwriteln- prints to screen with line end char at the endgetModule- allows you to access a module_reconfigure- can be implemented instead of overriding constructor.
Once you've implemented a simple extension class, you should include it in tests/_bootstrap.php file:
{% highlight php %}
{% endhighlight %}
Then you can enable it in codeception.yml:
{% highlight yaml %}
extensions: enabled: [MyCustomExtension]
{% endhighlight %}
In extension you can access currently passed options via options property.
You also can access global config via \Codeception\Configuration::config() method.
But if you want to have custom options for your extension, you can pass them in codeception.yml file:
{% highlight yaml %}
extensions: enabled: [MyCustomExtension] config: MyCustomExtension: param: value
{% endhighlight %}
Passed configuration is accessible via config property: $this->config['param'].
Check out a very basic extension Notifier.
Group Classes are extensions listening to events of a tests belonging to a specific group. When a test is added to a group:
{% highlight php %}
group('admin'); $I = new AcceptanceTester($scenario); ?>{% endhighlight %}
This test will trigger events:
test.before.adminstep.before.adminstep.after.admintest.success.admintest.fail.admintest.after.admin
A group class is built to listen to these events. It is pretty useful when additional setup is required for some of your tests. Let's say you want to load fixtures for tests that belong to admin group:
{% highlight php %}
writeln('inserting additional admin users...'); $db = $this->getModule('Db'); $db->haveInDatabase('users', array('name' => 'bill', 'role' => 'admin')); $db->haveInDatabase('users', array('name' => 'john', 'role' => 'admin')); $db->haveInDatabase('users', array('name' => 'mark', 'role' => 'banned')); } public function _after(\Codeception\Event\TestEvent $e) { $this->writeln('cleaning up admin users...'); // ... } } ?>{% endhighlight %}
A group class can be created with php codecept.phar generate:group groupname command.
Group class will be stored in tests/_groups directory.
A group class can be enabled just like you enable extension class. In file codeception.yml:
{% highlight yaml %}
extensions: enabled: [AdminGroup]
{% endhighlight %}
Now Admin group class will listen to all events of tests that belong to the admin group.
Each feature mentioned above may dramatically help when using Codeception to automate testing of large projects, although some features may require advanced knowledge of PHP. There is no "best practice" or "use cases" when we talk about groups, extensions, or other powerful features of Codeception. If you see you have a problem that can be solved using these extensions, then give them a try.
- Next Chapter: Data >
- Previous Chapter: < AdvancedUsageDocs are incomplete? Outdated? Or you just found a typo? Help us to improve documentation. Edit it on GitHub