Test framework

To easily test every aspect of Spryker and the code you write, Spryker uses the Codeception testing framework and PHPUnit.

Codeception offers many handy things to write better and cleaner tests. Many solutions this framework has are built on top of PHPUnit. In the next articles, we will only reference Codeception even if these features are available in PHPUnit as well.

On top of Codeception, we have built the Testify module, which provides many handy helpers. See Testify for more details on Testify itself, and Testify Helpers for details on the existing Testify helpers.

Basic test setup

To start running tests, you require a single codeception.yml file. Configuration provided in this file is used by default when executing the vendor/bin/codecept run command. This file, along with others, is included in the default Spryker installation and should be regarded as a starting point for your tests.

Here is an example of the codeception.yml file:

namespace: PyzTest
actor: Tester

include:
    # This will include all codeception.yml's that can be found in the defined path
    - tests/PyzTest/*/*

...

Configuration

The codeception.yml file at the root of your project is the main entry point for your tests. In this file, you define the basic configuration for your test suite.

In this file, you can include other codeception.yml files to organize your tests better.

Example:

namespace: PyzTest
actor: Tester

include:
    - tests/PyzTest/*/*
...

For an example, refer to codeception.yml in Spryker Master Suite.

For more information, see Codeception configuration documentation.

params:
    - .env
    - .env.store-a.testing

Separating tests

In numerous scenarios, you will need to improve your test setup by separating it into logical groups. By default, all test groups are located in tests/Pyz. The structure of items within this directory mirrors that of the src code:

tests/
-- Pyz/
---- Glue/
---- Shared/
---- Yves/
---- Zed/

This structure is foundational in nearly all Spryker projects. All of the tests inside those directories are executed based on the configuration in the root codeception.yml file.

Separating tests by namespace

Especially in the development environment, it often makes sense to separate tests by their application namespace. This approach lets you, for example, to run only Zed-related tests. To separate tests by namespaces, place the codeception.yml file into the tests/Pyz/Zed directory.

Here is an example of the codeception.yml file illustrating namespace-based separation:

namespace: PyzTest
actor: Tester

include:
    # This will include all codeception.yml's that can be found in the defined path for this specific application namespace
    - tests/PyzTest/Zed/*
...

Separating tests by stores

Imagine you have a large code base, and you use stores to implement additional or different behavior from the standard module. Suppose you have 10 thousand tests that are testing all your code, but you wish to execute tests for a particular store. In this situation, there’s no need to execute all tests twice—once for the default store and once for each individual store. Instead, you can execute your test suite once for the default store and then execute tests for the specific stores you require:

You can achieve this by having separated codeception.yml files for the default store and for any other store.

As you can see, there are many ways to leverage Codeception configuration files to achieve fine-grained or coarse-grained groups based on your testing needs.

Console commands

There are many console commands provided from Codeception, but the most used ones are:

• vendor/bin/codecept build - generates classes
• vendor/bin/codecept run - executes all your tests

For information on other Codeception console commands, run vendor/bin/codecept list.

See Executing Tests for details on some commands.

Testing with Spryker

On top of Codeception, we have added a basic infrastructure for tests. We have divided our tests by the applications, and for the layer we test. Thus, the organization of tests in most cases looks like this:

• tests/OrganizationTest/Application/Module/Communication - for example, controller or plugin tests.
• tests/OrganizationTest/Application/Module/Presentation - for example, testing pages with JavaScript.
• tests/OrganizationTest/Application/Module/Business - for example, testing facades or models.

The Communication suite can contain unit and functional tests. The controller tests can be used to test like a user that interacts with the browser but without the overhead of the GUI rendering. This suite should be used for all tests that do not need JavaScript.

The Business suite can contain unit and functional tests. The facade test is one kind of an API test approach. For more information, see Test API.

The Presentation suite contains functional tests that can be used to interact with a headless browser. These tests should be used when you have JavaScript on the page under test.

All test classes follow the exact same path as the class under test, except that tests live in the tests directory, and the organization part of the namespace is suffixed with Test. For example, tests/PyzTest/*. For details on the tests directory structure, see Directory Structure.

Each test suite contains a codeception.ymlconfiguration file. This file includes, for example, helpers that are enabled for the current suite.

For example, check the organization in the Application module of Spryker Master Suite.

Next step

Set up an organization of your tests