yii2/docs/guide/test-environment-setup.md

Testing environment setup

Yii 2 has officially maintained integration with Codeception testing framework that allows you to create the following test types:

• Unit - verifies that a single unit of code is working as expected;
• Functional - verifies scenarios from a user's perspective via browser emulation;
• Acceptance - verifies scenarios from a user's perspective in a browser.

Yii provides ready to use test sets for all three test types in both yii2-basic and yii2-advanced project templates.

Codeception comes preinstalled with both basic and advanced project templates. In case you are not using one of these templates, you can follow the steps in the next section to install it.

Setting up Codeception in a Yii application

Installing Codeception

Codeception can be installed using Composer by issuing the following console command:

composer require --dev 'codeception/codeception:^5.0' codeception/module-yii2 codeception/module-asserts codeception/module-filesystem codeception/verify codeception/module-phpbrowser

This command will install Codeception as well as some useful Codeception modules as development dependencies. Here is a short description about the packages installed:

• codeception/codeception:^5.0: This is the package for the main Codeception framework. The ^5.0 in the version constraint means that the package can be any version within the 5.x series, but not version 6 or higher.

  Note: Codeception 5 requires PHP 8 or higher. If your application is still using PHP 7 you need to change the version constraint of Codeception to 4.0. In this guide we will assume Codeception 5 is installed. There are some significant changes in the directory structure between Codeception 5 and 4, which you need to consider. Check the Codeception 5 release notes for more detail.

• codeception/module-yii2: This is a Codeception module that provides integration with the Yii framework. This module provides helpers and configuration for testing Yii2 applications using Codeception.

• codeception/module-asserts: This is a Codeception module that provides additional assertion methods for tests, such as assertGreaterThan, assertContains, and assertJsonPathEquals. These methods can be used to make more specific assertions about the behavior of the code being tested.

• codeception/module-filesystem: This is a Codeception module that provides methods for interacting with the filesystem during tests, such as creating, deleting, and modifying files and directories. This can be useful for testing code that involves reading from or writing to the filesystem.

• codeception/verify: This is a Codeception module that provides a wrapper for PHPUnit assertions, that are aimed to make tests a bit more readable.

• codeception/module-phpbrowser This is a Codeception module that provides a built-in web browser for testing web applications. This module allows you to simulate user interactions with a web application, such as clicking on links, filling out forms, and submitting data.

Info: The --dev flag indicates that the packages being installed are development dependencies, which means they are not needed for running the project in production. When installing the project in production you should always use composer install with the --no-dev flag.

Creating test config and directory structure

After installing Codeception you need to create the directory structure and configureation files. Codeception comes with a bootstrap command that does most of this work:

vendor/bin/codecept bootstrap

This will create a new Codeception configuration file named codeception.yml in your application's root directory.

It will set up three different test suites by default: unit, functional, and acceptance. You can learn more about the differences between these types of tests in the Introduction section of the Codeception documentation.

It will also generate the tests/ directory with the following structure:

• tests/Support this directory is used for storing helper classes and traits that can be used in your acceptance, functional, and unit tests. You can use these to write custom actions or verification methods you can re-use in your tests.

  There is a class for every test suite:

  • UnitTester.php
  • FunctionalTester.php
  • AcceptanceTester.php

  There is also a _generated directory which contains code that is generated by Codeception and is included in the Test Helper classes. Files in this directory should not be included in Version control so the bootstrap command placed a .gitignore file inside.

• For every test suite there is a *.suite.yml which is the configuration file for the specific test suite: Unit.suite.yml, Functional.suite.yml, and Acceptance.suite.yml.

• The actual tests for each test suite are placed in the directories named Unit, Functional, and Acceptance.

• The _output directory contains Test output such as Html and Screenshots of Failing tests and other test report data. Files in this directory should not be included in Version control so the bootstrap command placed a .gitignore file inside.

Setting up test suites for Yii

For testing you need a separate application configuration for the test environment. This can be based on application configuration used in your development and production environment but should contain the following changes:

• Use a separate Database. Tests will make a lot of changes to the database and should always start in a clean environment to make sure test results are always reproduceable. So you should configure the db application component to use a separate database. If you have other database connections you need to adjust these as well.

• If you have a mailer component, configure it to not send any emails:

  // ...
  'components' => [
      // ...
      'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,
            // ... keep other settings here
  
            // send all mails to a file by default.
            'useFileTransport' => true,
        ],
  ],
  

• In general, make sure your test environment does not contain any configuration that allows to connect to production database or services. This is to avoid data loss or unexpected behavior in production systems.

In the following we assume that your application's test configuration is located in config/test.php. Adjust the configuration as necessary to match your configuration file location.

Modify the codeception.yml file to include the necessary settings for your Yii application:

modules:
    config:
        Yii:
            configFile: 'config/test.php'

Unit tests

To enable the Yii2 module in the unit test suite, add it to the tests/Unit.suite.yml configuration file:

modules:
    enabled:
      - Yii2:
            part: [orm, email]

For a quick start you may generate a unit test and run it with the following commands:

vendor/bin/codecept g:test Unit First
vendor/bin/codecept run Unit

The output should be similar to the following:

Codeception PHP Testing Framework v5.0.9

Tests.Unit Tests (1) -------------------------------------------------------------------------------------
✔ FirstTest: Some feature(0.01s)
----------------------------------------------------------------------------------------------------------
Time: 00:00.058, Memory: 4.00 MB

OK (1 test, 0 assertions)

For more information on unit tests continue in the Unit Tests subsection.

Functional tests

To enable the Yii2 module in the functional test suite, add it to the tests/Functional.suite.yml configuration file:

bootstrap: bootstrap.php
modules:
    enabled:
      - Yii2

Functional tests need a Yii environment set up properly, so the Yii class needs to be included. This can be achieved by creating a bootstrap.php file inside the tests/Functional directory, that is included before the tests:

<?php

defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'test');
require __DIR__ . '/../../vendor/yiisoft/yii2/Yii.php';

For a quick start you may generate a functional test and run it with the following commands:

vendor/bin/codecept g:cest Functional First
vendor/bin/codecept run Functional

The output should be similar to the following:

Codeception PHP Testing Framework v5.0.9

Tests.Functional Tests (1) -------------------------------------------------------------------------------------
✔ FirstCest: Try to test(0.01s)
----------------------------------------------------------------------------------------------------------
Time: 00:00.058, Memory: 4.00 MB

OK (1 test, 0 assertions)

For more information on functional tests continue in the Functionl Tests subsection.

Acceptance tests

TODO

Selenium WebDriver

This configuration requires Selenium WebDriver running on localhost:4444

Change the host/port according to your needs

See http://codeception.com/docs/05-UnitTests#Selenium

modules:

enabled:

- WebDriver

config:

WebDriver:

url: 'http://localhost/'

browser: 'chrome'

host: '127.0.0.1'

port: 4444

vendor/bin/codecept run