Code testing

In a Cloud Docker for Commerce development environment, you can use the integrated test suite in each Cloud Suite for Commerce package for application code testing.

Test resources

The test suites, which use the Codeception testing framework for PHP, provide acceptance tests to validate code intended for contribution to Commerce Cloud package repositories.

Acceptance tests are in the package src/Test/Functional/Acceptance folder.
Test configuration is the codeception.dist.yml file in the package folder.

Use the following table to access the files and available tests for each Cloud package. The links use the develop branch, so be sure to select the appropriate tag for your project:

Package	Test configuration link	Acceptance test link
ECE-tools	codeception.dist.yml	magento/ece-tools Acceptance tests
Cloud components	codeception.dist.yml	magento/magento-cloud-components Acceptance tests
Cloud Docker	codeception.dist.yml	magento/magento-cloud-docker Acceptance tests
Cloud patches	codeception.dist.yml	magento/magento-cloud-patches Acceptance tests

For application testing, use the Magento Application Testing (MFTF) framework to run functional tests. See Application testing.

Prepare the Docker environment for testing

To set up and configure the test environment:

Clone the GitHub repository for the package to test.

git clone git@github.com:magento/<cloud-suite-package-repository>.git
Copied to your clipboard
git clone git@github.com:magento/<cloud-suite-package-repository>.git

For example, clone the ECE-Tools package:

git clone git@github.com:magento/ece-tools.git
Copied to your clipboard
git clone git@github.com:magento/ece-tools.git

Stop all services that use the following ports:
- 80—varnish
- 443—web, tls
- 3306—Apache, mysql

Add the following hostname to your /etc/hosts file.

127.0.0.1 magento2.docker
Copied to your clipboard
127.0.0.1 magento2.docker

Alternatively, you can run the following command to add it to the file:

echo "127.0.0.1 magento2.docker" | sudo tee -a /etc/hosts
Copied to your clipboard
echo "127.0.0.1 magento2.docker" | sudo tee -a /etc/hosts

Add required project dependencies if you are testing the following packages.

For the magento/magento-cloud-patches package:

composer require "magento/magento-cloud-docker:^1.0.0" --no-update
Copied to your clipboard
composer require "magento/magento-cloud-docker:^1.0.0" --no-update

For the magento/magento-cloud-components package:

composer require "magento/magento-cloud-docker:^1.0.0" --no-update
composer require "magento/framework:*" --no-update
composer require "magento/module-store:*" --no-update
composer require "magento/module-url-rewrite:*" --no-update
Copied to your clipboard
composer require "magento/magento-cloud-docker:^1.0.0" --no-update
composer require "magento/framework:*" --no-update
composer require "magento/module-store:*" --no-update
composer require "magento/module-url-rewrite:*" --no-update

Switch to the preferred PHP version for running tests.

Update the project dependencies.

composer update
Copied to your clipboard
composer update

Add credentials

Add credentials to your Docker environment using any of the following methods:

Use environment variables
Load credentials from the environment configuration file
Add variables directly to the test configuration file

To add credentials using environment variables:

Create environment variables for your GitHub authentication keys.

export REPO_USERNAME=your_public_key
Copied to your clipboard
export REPO_USERNAME=your_public_key

export REPO_PASSWORD=your_private_key
Copied to your clipboard
export REPO_PASSWORD=your_private_key

Some packages require a GitHub authentication during installation. Create an environment variable with your GitHub token that can be used to install these packages.

`export GITHUB_TOKEN=your_github_token
Copied to your clipboard
`export GITHUB_TOKEN=your_github_token

To load credentials from the environment configuration file:

Run the following commands to write credentials to the ./.env file:

echo "REPO_USERNAME=your_public_key" >> ./.env
Copied to your clipboard
echo "REPO_USERNAME=your_public_key" >> ./.env

echo "REPO_PASSWORD=your_private_key" >> ./.env
Copied to your clipboard
echo "REPO_PASSWORD=your_private_key" >> ./.env

Edit the codeception.dist.yml file.

params:
    - tests/functional/configuration.dist.yml
    - env
    - .env
Copied to your clipboard
params:
    - tests/functional/configuration.dist.yml
    - env
    - .env

Add a dependency for the vlucas/phpdotenv package required to load the environment variables.

composer require "vlucas/phpdotenv": "^3.0"
Copied to your clipboard
composer require "vlucas/phpdotenv": "^3.0"

To add credentials directly to the test configuration file:

Open the codeception.dist.yml file in an editor.

Replace the %REPO_USERNAME%, %REPO_PASSWORD%, and %GITHUB_TOKEN% placeholder values with your credentials:

modules:
  config:
    Magento\CloudDocker\Test\Functional\Codeception\TestInfrastructure:
    ...
    composer_magento_username: "%REPO_USERNAME%"
    composer_magento_password: "%REPO_PASSWORD%"
    composer_github_token: "%GITHUB_TOKEN%"
      ...
Copied to your clipboard
modules:
  config:
    Magento\CloudDocker\Test\Functional\Codeception\TestInfrastructure:
    ...
    composer_magento_username: "%REPO_USERNAME%"
    composer_magento_password: "%REPO_PASSWORD%"
    composer_github_token: "%GITHUB_TOKEN%"
      ...

Run tests

Before you run tests, you must prepare your Docker environment and update the test configuration file. See Prepare the test environment. By default, functional tests produce a short output. You can receive more detailed output by editing the codeception.dist.yml test configuration file to set the printOutput: property to true.

modules:
  config:
    Magento\CloudDocker\Test\Functional\Codeception\TestInfrastructure:
      ...
      printOutput: true
      ...
    Magento\CloudDocker\Test\Functional\Codeception\Docker:
      ...
      printOutput: true
      ...
Copied to your clipboard
modules:
  config:
    Magento\CloudDocker\Test\Functional\Codeception\TestInfrastructure:
      ...
      printOutput: true
      ...
    Magento\CloudDocker\Test\Functional\Codeception\Docker:
      ...
      printOutput: true
      ...

You can locate the test configuration file in the root directory for each package. See Test resources.

Run a specific test

Use the following command format to run a specific functional test:

./vendor/bin/codecept run Acceptance <TestName>Cest
Copied to your clipboard
./vendor/bin/codecept run Acceptance <TestName>Cest

For example, the following test for magento/ece-tools code verifies that the post-deploy task runs successfully.

./vendor/bin/codecept run Acceptance PostDeployCest
Copied to your clipboard
./vendor/bin/codecept run Acceptance PostDeployCest

Sample response:

Codeception PHP Testing Framework v2.5.6
Powered by PHPUnit 6.5.14 by Sebastian Bergmann and contributors.
Running with seed:
Acceptance Tests (1) -----------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------
PostDeployCest: Test post deploy | {"ADMIN_EMAIL":"admin@example.com"}
 [Magento\MagentoCloud\Test\Functional\Robo\Tasks\GenerateDockerCompose] Running ./bin/ece-docker build:compose
 --mode=functional --php=7.2
...
...
✔ PostDeployCest: Test post deploy | {"ADMIN_EMAIL":"admin@example.com"} (210.41s)
Copied to your clipboard
Codeception PHP Testing Framework v2.5.6
Powered by PHPUnit 6.5.14 by Sebastian Bergmann and contributors.
Running with seed:
Acceptance Tests (1) -----------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------
PostDeployCest: Test post deploy | {"ADMIN_EMAIL":"admin@example.com"}
 [Magento\MagentoCloud\Test\Functional\Robo\Tasks\GenerateDockerCompose] Running ./bin/ece-docker build:compose
 --mode=functional --php=7.2
...
...
✔ PostDeployCest: Test post deploy | {"ADMIN_EMAIL":"admin@example.com"} (210.41s)

You can see the available tests for each package in the package source files. See Test resources.

Run all tests

Use the following commands to run all available tests for each PHP version:

PHP 7.1

./vendor/bin/codecept run -g php71 --steps
Copied to your clipboard
./vendor/bin/codecept run -g php71 --steps

PHP 7.2

./vendor/bin/codecept run -g php72 --steps
Copied to your clipboard
./vendor/bin/codecept run -g php72 --steps

PHP 7.3

./vendor/bin/codecept run -g php73 --steps
Copied to your clipboard
./vendor/bin/codecept run -g php73 --steps

PHP 7.4

./vendor/bin/codecept run -g php74 --steps
Copied to your clipboard
./vendor/bin/codecept run -g php74 --steps

If you are testing magento/ece-tools code, use the following command:

./vendor/bin/codecept run -x php71 -x php72 -x php73 -x php74 --steps
Copied to your clipboard
./vendor/bin/codecept run -x php71 -x php72 -x php73 -x php74 --steps

For help with Codeception command options, use the .vendor/bin/codecept run --help command, or see the Codeception CLI documentation for the installed version.

Application testing

Configure Xdebug