o3-shop/testing-library

OXID eShop testing library

v1.1.0 2023-04-25 09:03 UTC

Requires

• php: ^7.4 || ^8.0
• behat/mink: ~1.5.0
• codeception/codeception: ^4
• codeception/module-asserts: ^1.3
• codeception/module-db: ^1.0
• codeception/module-filesystem: ^1.0
• codeception/module-webdriver: ^1.1
• incenteev/composer-parameter-handler: ~2.0
• mikey179/vfsstream: ~1.6.8
• o3-shop/codeception-modules: ^1.0.0
• o3-shop/codeception-page-objects: ^v1.0.0
• o3-shop/developer-tools: ^1.0.0
• o3-shop/mink-selenium-driver: ~v1.0.0
• o3-shop/shop-ce: ^1.2 || dev-dev-b-1.x
• o3-shop/shop-facts: ^1.0.0
• o3-shop/shop-unified-namespace-generator: ^1.0.0
• pdepend/pdepend: 2.6.0
• phpunit/php-code-coverage: ^7.0.12
• phpunit/phpunit: ^8.5.14
• symfony/dom-crawler: v2.7.*
• symfony/filesystem: ^4.4.17
• symfony/polyfill-intl-idn: 1.17.1
• symfony/yaml: ~3.0

Replaces

• oxid-esales/testing-library: 8.1.0

GPL-3.0-only

• testing
• library
• modules
• eshop
• O3-Shop

README

The O3-Shop testing library can be used to test O3-Shop with existing or new Unit, Integration, Mink or QUnit tests. Furthermore, it can also be very helpful to developers who create a module for the O3-Shop.

This library is meant to help developers check their shop/module code with ease. It contains all the required tools and dependencies to execute unit tests, selenium tests, metrics.

Requirements

• Latest Composer version
• PHP cURL extension
• Not compatible with Windows (use VM instead)

This library can be used to test modules with earlier shop versions, but it will not be possible to run shop tests.

Installation

Testing library setup uses composer to get required packages, so make sure to have composer installed and accessible. You can find composer installation guide here.

Selecting where to install testing library

Testing library can be installed directly within shop or to any other directory. However, installation varies slightly depending on selected location. We advise to install it using shop directory.

Option 1: Selecting shop directory for installation (preferred way)

To install testing library within shop directory, update/create composer.json with following values:

{
    "name": "o3-shop/eshop",
    "description": "O3-Shop",
    "type": "project",
    "keywords": ["o3-shop", "modules", "eShop"],
    "homepage": "https://www.o3-shop.com/"
    "license": [
        "GPL-3.0",
        "proprietary"
    ],
    "require-dev": {
        "o3-shop/testing-library": "dev-master",
        "incenteev/composer-parameter-handler": "~2.0"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "scripts": {
        "post-install-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters"
        ],
        "post-update-cmd": [
            "Incenteev\\ParameterHandler\\ScriptHandler::buildParameters"
        ]
    },
    "extra": {
        "incenteev-parameters": {
            "file": "test_config.yml",
            "dist-file": "vendor/o3-shop/testing-library/test_config.yml.dist",
            "parameter-key": "mandatory_parameters",
            "env-map": {
                "shop_path": "SHOP_PATH",
                "shop_tests_path": "SHOP_TESTS_PATH",
                "partial_module_paths": "PARTIAL_MODULE_PATHS"
            }
        }
    }
}

Installing this way, binaries will be accessible from shop_source_path/vendor/bin. Latest development shop version already includes composer.json file in its source, so no changes need to be made.

Option 2: Selecting any directory for installation (alternative way)

To install testing library to any directory, you need to checkout testing library from Github into desired directory (git clone https://gitlab.o3-shop.com/o3/testing_library). Installing this way, binaries will be accessible from testing_library/bin.

Installing testing library

After you selected where you want to install the testing library, follow these steps:

1. Navigate to the directory that you picked for installation.
2. Use composer to setup testing library components (composer install). Ensure you do this from within the directory where composer.json is located. During setup you will be asked several questions regarding testing library configuration. These options will be explained in more detail here: Parameter explanation

Running tests

First and foremost - make sure you have a working shop, meaning:

1. Shop is installed/configured (config.inc.php is filled in with database connection details and so)
2. Shop can be accessed through url (used for shop installation).

Several test runners are available for use once testing library is prepared. These are available in bin or vendor/bin directory:

• runtests - run shop/module unit and integration tests.
• runtests-selenium - run shop/module selenium tests.
• runtests-coverage - run shop/module tests with code coverage.
• runmetrics - execute code metrics test for shop/module.

Additionally you can pass parameters to these scripts. runmetrics uses pdepend, and all runtests uses phpunit. You can add phpunit parameters to runtests, runtests-selenium, runtests-coverage. You can add pdepend parameters to runmetrics. To see which additional options can be passed to test runner, add --help option to the command (i.e. ./runtests --help, ./runmetrics --help). This will show available options for desired tool.

Some usage examples:

1. Running only a single file tests - bin/runtests path/to/test/fileTest.php
2. Running only specific pattern matching tests from specified file - bin/runtests --filter match_pattern path/to/test/fileTest.php
3. Running one or multiple test suites - TEST_DIRS=unit,integration bin/runtests
4. Running all Codeception tests - bin/runtests-codeception
5. Running a specific Codeception test from the main (shop) suite - bin/runtests-codeception-shop GiftRegistryCest::addProductToUserGiftRegistry

One thing to note when adding parameters to these tools - always provide file/folder at the end as it will no longer be picked automatically. Use AllTestsUnit or AllTestsSelenium respectively to run all tests.

Run with PHPStorm

You need to setup path to bootstrap in order to run tests with PHPStorm.

1. Open PHPStorm.
2. Open Run/Debug configurations window.
3. Press on configuration icon (wrench) right after the "Use alternative configuration file" input.
4. New PHPUnit window pops up. Check "Default bootstrap file" checkbox and choose path to bootstrap. Path to bootstrap: {source}/vendor/o3-shop/testing-library/bootstrap.php

Configuration

Configuration file is named test_config.yml and is placed in the root directory of this library or shop (when installing with shop composer.json). During setup you will be asked several questions regarding testing library and shop/module installation. After setup test_config.yml will be created, and later can be edited if some configuration values need to be changed.

All of the parameters can be set with environmental variables. Environmental parameter names are the same as in the configuration file, but should be all uppercase: shop_path => SHOP_PATH, browser_name => BROWSER_NAME, etc.

Configuration parameters

Mandatory parameters

These parameters are required for testing library to work properly.

Optional parameters

These parameters are not required in order to work, but they provide additional functionality and options when testing.

Changing PHPUnit parameters

To change PHPUnit parameters, add phpunit.xml file inside tests directory and it will be used.

Execution before UNIT test run with additional.inc.php

Testing library gives possibility to make some actions before UNIT test run. So if there is a need to to do that, add additional.inc.php file into tests directory and it will be executed.

Note:

Use addTestData() method and testSql directory to change environment for Acceptance tests. Read more in a section Writing acceptance tests.

Writing Tests

Directory Structure

Module tests should be placed in module root directory: path/to/shop/modules/my_module/tests. Tests can by placed in three directories: unit, integration and acceptance depending on tests type. ./runtests collects tests from unit and integration directories, while ./runtests-selenium - from acceptance. Code coverage is calculated from both unit and integration tests.

Writing unit and integration tests

Unit and integration should be placed under tests/unit and tests/integration directories. Any number of subdirectories can be created inside - all tests will be collected. Unit and integration tests should extend OxidEsales\TestingLibrary\UnitTestCase class so that database, registry, configuration parameters restoration, module activation would work. If unit tests are not relying on database or registry and are real clean unit tests, PHPUnit\Framework\TestCase class can be extended, but have in mind that autoloading of module classes and correct shop classes extension will not work. All preparation works can be done in additional.inc.php file. This file is loaded before database dump creation and before running any of the test, so can be used autoloaders registration, demodata preparation, etc. For unit testing shop is installed without default demodata added.

Methods usage

Run unit and integration test dependent if Subshops is enabled:

public function testCase_forSubShops()
{
    $this->markTestSkippedIfSubShop();
    ...
}

public function testCase_forNoSubShops()
{
    $this->markTestSkippedIfNoSubShop();
    ...
}

Rest of the methods can be found in class: OxidEsales\TestingLibrary\UnitTestCase.

Writing acceptance tests

Currently for acceptance testing Mink library and selenium driver is used.

Note:

selenium-server-standalone-jar 2.47.1 is used for testing. There might be some issues with older versions issue #13

Acceptance tests should be placed under tests/acceptance directory and extend OxidEsales\TestingLibrary\AcceptanceTestCase.

Tested module will be activated by default. Some data might be also added by extending AcceptanceTestCase::addTestData() method and activating module manually. This method will be run before any test and before database dump creation, once per tests suite.

For acceptance testing shop is installed with default demodata. Additional demodata can be added to testSql directory by the name of demodata_EE.sql, demodata_PE_CE.sql or demodata_EE_mall.sql (when subshop functionality is enabled in test_config). These files will be loaded on top of the database depending on the shop edition. Any additional files, needed for testing can be placed under testData directory - all content will be copied onto the shop source before running tests.

A useful method for preparing the shop is AcceptanceTestCase::callShopSC(). With this method you can e.g. insert a new article or modify config variables. For detailed usage examples have a look at the O3-Shop acceptance tests.

Methods usage

Testing library provides methods which allows write tests easier. Some methods usages are described bellow:

Activating theme:

// This will activate azure theme.
$this->activateTheme('azure');

Add article to basket:

// This will add article with ID 1001 to basket.
$this->addToBasket("1001");

Update items amount in basket: (Note that item must be in basket in order to change it)

// This will update article with ID 1001 in basket to have 2 items.
$this->changeBasket("1001", 2);

// This will remove an item from basket.
$this->changeBasket("1001", 0);

Login user in front end side:

$this->loginInFrontend("[e-mail]", "useruser");

Rest of the methods can be found in class: OxidEsales\TestingLibrary\AcceptanceTestCase.

Changing database restoration mechanism

Currently there are two database restoration classes available - DatabaseRestorer and LocalDatabaseRestorer. Both of these are truncating changed tables and adding all the information back in. If provided solutions are not fitting your needs, it can be changed by implementing OxidEsales\TestingLibrary\DatabaseRestorer\DatabaseRestorerInterface interface and registering new class in test_config.yml::database_restoration_class.

Library API

• test_config.yml parameters
• OxidEsales\TestingLibrary\AcceptanceTestCase
• OxidEsales\TestingLibrary\UnitTestCase
• \OxidEsales\TestingLibrary\ServiceCaller
• OxidEsales\TestingLibrary\Services called via \OxidEsales\TestingLibrary\ServiceCaller

Testing library branch names

Testing library branch names follow the O3-Shop component branch names. Which means that branch names do not follow testing library version numbers, but represent the target version of the O3-Shop compilation. For example:

Tests running workflow

Graphically visualized workflow can be found in workflow.puml. This file can be opened with tool called PlantUml (http://plantuml.com/).