Codeception for
Symfony Framework

Symfony Module


Raul Ferriz




Install Codeception via Composer:

composer require codeception/codeception --dev


From Symfony 4 onwards there will be a top-level tests directory, instead of a separate Tests directory in each bundle. It is recommended to place unit, functional, and acceptance test files into tests.

Project Setup

Codeception should be installed globally for a project. To start, please run

php bin/codecept bootstrap --empty

This will create codeception.yml and the tests directory. There are no test suites inside tests yet.

Acceptance Testing

For UI testing you will have to create first suite for acceptance tests:

php bin/codecept g:suite acceptance

This will create acceptance.suite.yml and acceptance folder inside tests. Acceptance tests should be configured to work with Selenium WebDriver to test application inside a real browser.

class_name: AcceptanceTester
        - WebDriver:
            url: 'https://localhost/' # put your local url
            browser: firefox
        - \Helper\Acceptance            

Browser can be specified as firefox, chrome, phantomjs, or others.

Acceptance tests should be described in Cest format. Run code generator

php bin/codecept g:cest acceptance UserCest

to generate very first test tests/acceptance/UserCest.php. Each method of a class (except _before and _after) is a test. Tests use $I object (instance of AcceptanceTester class) to perform actions on a webpage. Methods of AcceptanceTester are proxified to corresponding modules, which in current case is WebDriver.

To generate method stubs for AcceptanceTester.

php bin/codecept build

To run the tests you will need firefox browser, selenium server running. If this requirements met acceptance tests can be executed as

php bin/codecept run acceptance


If you prefer to describe application with feature files, Codeception can turn them to acceptance tests. It is recommended to store feature files in features directory (like it does Behat) but symlinking it to tests/acceptance/features so they can be treated as tests too.

ln -s $PWD/features tests/acceptance

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.

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.

php bin/codecept gherkin:snippets

Functional Testing

There is no need to use WebTestCase to write functional tests. Symfony functional tests are written in the same manner as acceptance tests but are executed inside a framework. Codeception has the Symfony Module for it. To create a functional test suite, run:

php bin/codecept g:suite functional

Functional tests are written in the same manner as acceptance tests. They also use scenario and $I actor object. The only difference is how they are executed. To run tests as Symfony test you should enable corresponding module in functional suite configuration file tests/functional.suite.yml. Probably you want Doctrine to be included as well. Then you should use this configuration:

class_name: FunctionalTester
        - Symfony:
            app_path: 'src'
            environment: 'test'
        - Doctrine2:
            depends: Symfony
        - \Helper\Functional
Learn more about starting with Symfony in our blogpost »

API Tests

API Tests are done at functional testing level but instead of testing HTML responses on user actions, they test requests and responses via protocols like REST or SOAP. To create api tests, you should create a suite for them:

php bin/codecept g:suite api

You will need to enable REST, Symfony and Doctrine module in tests/api.suite.yml:

class_name: ApiTester
        - Symfony:
            app_path: 'src'
            environment: 'test'
        - REST:
            url: /v1
            depends: Symfony
        - Doctrine2:
            depends: Symfony
        - \Helper\Api

Symfony module actions like amOnPage or see should not be available for testing API. This why Symfony module is not enabled but declared with depends for REST module. But Symfony module should be configured to load Kernel class from app_path.

Unit Testing

Create a unit test suite with:

php bin/codecept g:suite unit

Codeception is powered by PHPUnit so unit and integration test work in a similar manner. To genereate a plain PHPUnit test for Foo class, run:

php bin/codecept g:test unit Foo

Actions of Symfony and Doctrine2 modules will be accessible from $this->tester inside a test of Codeception\Test\Unit.

Continue to Unit Testing Guide ».