In this chapter we will cover some techniques and options that you can use to improve your testing experience
and keep your project better organized.
If you want to get a class-like structure for your Cepts, you can use the Cest format instead of plain PHP.
It is very simple and is fully compatible with Cept scenarios. It means that if you feel that your test is long enough
and you want to split it, you can easily move it into classes.
You can create a Cest file by running the command:
The generated file will look like this:
Each public method of Cest (except those starting with
_) will be executed as a test
and will receive an instance of the Actor class as the first parameter and the
$scenario variable as the second one.
_after methods you can use common setups and teardowns for the tests in the class.
This actually makes Cest tests more flexible than Cepts, which rely only on similar methods in Helper classes.
As you see, we are passing Actor object into
tryToTest method. It allows us to write scenarios the way we did before:
As you see, Cest classes have no parents like
This is done intentionally. It allows you to extend your classes with common behaviors and workarounds
that may be used in child classes. But don’t forget to make these methods
protected so they won’t be executed as tests.
You can also define a
_failed method in Cest classes which will be called if test finishes with
error or fails.
Codeception supports simple dependency injection for Cest and \Codeception\TestCase\Test classes.
It means that you can specify which classes you need as parameters of the special
and Codeception will automatically create the respective objects and invoke this method,
passing all dependencies as arguments. This may be useful when working with Helpers, for example:
Example of the Test class:
However, Dependency Injection is not limited to this. It allows you to inject any class,
which can be constructed with arguments known to Codeception.
In order to make auto-wiring work, you will need to implement the
_inject() method with the list of desired arguments.
It is important to specify the type of arguments, so Codeception can guess which objects are expected to be received.
_inject() will only be invoked once, just after creation of the TestCase object (either Cest or Test).
Dependency Injection will also work in a similar manner for Helper and Actor classes.
Each test of a Cest class can declare its own dependencies and receive them from method arguments:
Moreover, Codeception can resolve dependencies recursively (when
A depends on
B depends on
and handle parameters of primitive types with default values (like
$param = 'default').
Of course, you are not allowed to have cyclic dependencies.
What if you want to execute one test scenario but with different data? In this case you can use examples
to provide different data for test and inject them as
Data is defined via the
@example annotation, using JSON or Doctrine-style notation (limited to a single line):
If you use JSON notation please keep in mind that all string keys
and values should be enclosed in double quotes " according to JSON standard.
You can pass key-value data as an example and use it in tests as well:
These examples can be written using Doctrine-style annotation syntax as well:
You can also use the
@dataprovider annotation for creating dynamic examples, using a protected method for providing example data:
@dataprovider can also be a public method starting with
_ prefix so it will not be considered as a test:
You can control execution flow with
@after annotations. You may move common actions
into protected (non-test) methods and invoke them before or after the test method by putting them into annotations.
It is possible to invoke several methods by using more than one
Methods are invoked in order from top to bottom.
You can also use
@after for included functions. But you can’t have multiple annotations of the same kind
for single method - one method can have only one
@before and only one
@after annotation of the same kind.
For cases where you need to run tests with different configurations you can define different config environments.
The most typical use cases are running acceptance tests in different browsers,
or running database tests using different database engines.
Let’s demonstrate the usage of environments for the browsers case.
We need to add some new lines to
Basically you can define different environments inside the
env root, name them (
and then redefine any configuration parameters that were set before.
You can also define environments in separate configuration files placed in the directory specified by the
envs option in
The names of these files are used as environments names
chrome.dist.yml for an environment named
You can generate a new file with this environment configuration by using the
In that file you can specify just the options you wish to override:
The environment configuration files are merged into the main configuration before the suite configuration is merged.
You can easily switch between those configs by running tests with
To run tests only for PhantomJS you just need to pass
--env phantom option:
To run tests in all 3 browsers, list all the environments:
The tests will be executed 3 times, each time in a different browser.
It’s also possible to merge multiple environments into a single configuration by separating them with a comma:
The configuration is merged in the order given.
This way you can easily create multiple combinations of your environment configurations.
Depending on the environment, you may choose which tests are to be executed.
For example, you might need some tests to be only executed in Firefox, and some tests only in Chrome.
The desired environments can be specified with the
@env annotation for tests in Test and Cest formats:
For Cept you should use simple comments:
This way you can easily control which tests will be executed for each environment.
Sometimes you may need to change the test behavior in real time.
For instance, the behavior of the same test may differ in Firefox and in Chrome.
In runtime we can retrieve the current environment name, test name,
or list of enabled modules by calling the
You can access
\Codeception\Scenario in the Cept and Cest formats.
In Cept, the
$scenario variable is available by default,
while in Cest you should retrieve it through dependency injection:
Codeception\Scenario is also availble in Actor classes and StepObjects. You can access it with
@depends annotation you can specify a test that should be passed before the current one.
If that test fails, the current test will be skipped. You should pass the method name of the test you are relying on.
Depends applies to the
Codeception\Test\Unit formats. Dependencies can be set across different classes.
To specify a dependent test from another file you should provide a test signature.
Normally, the test signature matches the
But to get the exact test signature just run test with
--steps option to see it:
Codeception reorders tests so dependent tests always will executed after the tests they rely on.
The interactive console was added to try Codeception commands before executing them inside a test.
You can run the console with the following command:
Now you can execute all the commands of an appropriate Actor class and see the results immediately.
This is especially useful when used with the
WebDriver module. It always takes too long to launch Selenium
and the browser for tests. But with the console you can try different selectors, and different commands,
and then write a test that should pass when executed.
And a special hint: show your boss how you can easily manipulate web pages with the console and Selenium.
It will be easy to convince them to automate this step and introduce acceptance testing to the project.
Running from different folders
If you have several projects with Codeception tests, you can use a single
codecept file to run all of your tests.
You can pass the
-c option to any Codeception command, excluding
bootstrap, to execute Codeception in another directory:
To create a project in directory different from the current one, just provide its path as a parameter:
-c option allows you to specify not only the path, but a config file to be used.
Thus, you can have several
codeception.yml files for your test suite. You may use it to specify different environments
and settings. Just pass a filename into
-c parameter to execute tests with specific config settings.
There are several ways to execute bunch of tests. You can run tests from specific directory:
You can execute one (or several) specific groups of tests:
In this case, all tests that belong to either of the groups
editor will be executed.
The concept of groups was taken from PHPUnit and in classical PHPUnit tests they behave just in the same way.
For Tests and Cests you can use the
@group annotation to add a test to the group.
For Cept files, use pseudo-annotations in comments:
For feature-files (Gherkin) use tags:
Groups can be defined in global or suite configuration files.
Tests for groups can be specified as an array of file names or directories containing them:
A list of tests for the group can be passed from a Group file. It should be defined in plain text with test names on separate lines:
A group file can be included by its relative filename:
You can create group files manually or generate them from third party applications.
For example, you can write a script that updates the slow group by taking the slowest tests from xml report.
You can even specify patterns for loading multiple group files with a single definition:
This will load all found
p* files in
tests/_data as groups. Group names will be as follows p1,p2,…,pN.
For bash and zsh shells, you can use autocompletion for your Codeception projects by executing the following in your shell (or add it to your .bashrc/.zshrc):
By using the above code in your shell, Codeception will try to autocomplete the following:
- Test paths
-use-vendor-bin is optional. This option will work for most Codeception projects, where Codeception is located in your
But in case you are using a global Codeception installation for example, you wouldn’t use this option.
Note that with the
-use-vendor-bin option, your commands will be completed using the Codeception binary located in your project’s root.
Without the option, it will use whatever Codeception binary you originally used to generate the completion script (‘codecept location’ in the above examples)
Codeception is a framework which may look simple at first glance
but it allows you to build powerful tests with a single API, refactor them,
and write them faster using the interactive console. Codeception tests can be easily organized in groups or Cest classes.