Let’s take a look at Codeception’s architecture. We’ll assume that you have already installed it
and bootstrapped your first test suites. Codeception has generated three of them: unit, functional, and acceptance.
They are well described in the previous chapter. Inside your /tests folder you will have three
.yml config files and three directories
with names corresponding to these suites:
acceptance. Suites are independent groups of tests with a common purpose.
Codeception follows simple naming rules to make it easy to remember (as well as easy to understand) its method names.
One of the main concepts of Codeception is representation of tests as actions of a person. We have a UnitTester, who executes functions and tests the code. We also have a FunctionalTester, a qualified tester, who tests the application as a whole, with knowledge of its internals. Lastly we have an AcceptanceTester, a user who works with our application through an interface that we provide.
Methods of actor classes are generally taken from Codeception Modules. Each module provides predefined actions for different testing purposes, and they can be combined to fit the testing environment.
Codeception tries to solve 90% of possible testing issues in its modules, so you don’t have to reinvent the wheel.
We think that you can spend more time on writing tests and less on writing support code to make those tests run.
By default, AcceptanceTester relies on PhpBrowser module, which is set in the
tests/acceptance.suite.yml configuration file:
In this configuration file you can enable/disable and reconfigure modules for your needs.
When you change the configuration, the actor classes are rebuilt automatically. If the actor classes are not created or updated as you expect,
try to generate them manually with the
Codeception has its own testing format called Cest (Codecept + Test). To start writing a test we need to create a new Cest file. We can do that by running the following command:
This will generate
SigninCest.php file inside
tests/acceptance directory. Let’s open it:
_after methods to run some common actions before and after a test. And we have a placeholder action
tryToTest which we need to implement.
If we try to test a signin process it’s a good start to test a successful signin. Let’s rename this method to
We’ll assume that we have a ‘login’ page where we get authenticated by providing a username and password.
Then we are sent to a user page, where we see the text
Hello, %username%. Let’s look at how this scenario is written in Codeception:
This scenario can probably be read by non-technical people. If you just remove all special chars like braces, arrows and
this test transforms into plain English text:
Codeception generates this text representation from PHP code by executing:
These generated scenarios will be stored in your
_data directory in text files.
Before we execute this test, we should make sure that the website is running on a local web server.
Let’s open the
tests/acceptance.suite.yml file and replace the URL with the URL of your web application:
After configuring the URL we can run this test with the
This is the output we should see:
Let’s get some detailed output:
We should see a step-by-step report on the performed actions:
This simple test can be extended to a complete scenario of site usage, therefore, by emulating the user’s actions, you can test any of your websites.
To run more tests create a public method for each of them. Include
AcceptanceTester object as
$I as a method parameter and use the same
$I-> API you’ve seen before.
If your tests share common setup actions put them into
For instance, to test CRUD we want 4 methods to be implemented and all next tests should start at
Learn more about the Cest format in the Advanced Testing section.
It’s hard to write a complete test at once. You will need to try different commands with different arguments before you find a correct path.
Since Codeception 3.0 you can pause the execution at any point and enter an interactive shell where you will be able to try different commands in action.
All you need to do is call
$I->pause() somewhere in your test, then run the test in debug mode.
Interactive Pause requires
hoa/console which is not installed by default. To install it, run:
The execution of the test is stopped at this point, and a console is shown where you can try all available commands “live”. This can be very useful when you write functional, acceptance, or api test.
Inside Interactive Pause you can use the entire power of the PHP interpreter: variables, functions, etc.
You can access the result of the last executed command in a variable called
In acceptance or functional test you can save page screenshot or html snapshot.
To try commands without running a single test you can launch interactive console:
Now you can execute all the commands of a corresponding Actor class and see the results immediately.
Codeception allows execution of user stories in Gherkin format in a similar manner as is done in Cucumber or Behat. Please refer to the BDD chapter to learn more.
Codeception has a global configuration in
codeception.yml and a config for each suite. We also support
.dist configuration files.
If you have several developers in a project, put shared settings into
codeception.dist.yml and personal settings into
The same goes for suite configs. For example, the
unit.suite.yml will be merged with
Tests can be started with the
With the first argument you can run all tests from one suite:
To limit tests run to a single class, add a second argument. Provide a local path to the test class, from the suite directory:
Alternatively you can provide the full path to test file:
You can further filter which tests are run by appending a method name to the class, separated by a colon (for Cest or Test formats):
You can provide a directory path as well. This will execute all acceptance tests from the
Using regular expressions, you can even run many different test methods from the same directory or class.
For example, this will execute all acceptance tests from the
backend dir beginning with the word “login”:
To execute a group of tests that are not stored in the same directory, you can organize them in groups.
To generate JUnit XML output, you can provide the
--xml option, and
--html for HTML report.
This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be stored in the
To see all the available options, run the following command:
To receive detailed output, tests can be executed with the
You may print any information inside a test using the
There are plenty of useful Codeception commands:
generate:cestsuite filename - Generates a sample Cest test
generate:testsuite filename - Generates a sample PHPUnit Test with Codeception hooks
generate:featuresuite filename - Generates Gherkin feature file
generate:suitesuite actor - Generates a new suite with the given Actor class name
generate:scenariossuite - Generates text files containing scenarios from tests
generate:helperfilename - Generates a sample Helper File
generate:pageobjectsuite filename - Generates a sample Page object
generate:stepobjectsuite filename - Generates a sample Step object
generate:environmentenv - Generates a sample Environment configuration
generate:groupobjectgroup - Generates a sample Group Extension
We have taken a look into the Codeception structure. Most of the things you need were already generated by the
After you have reviewed the basic concepts and configurations, you can start writing your first scenario.