PHPackages oxid-esales/testing-library - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. oxid-esales/testing-library ActiveLibrary[Testing & Quality](/categories/testing) oxid-esales/testing-library =========================== OXID eShop testing library v9.0.0(4y ago)13374.0k—8.8%218GPL-3.0-onlyPHPPHP ^7.3 || ^8.0 Since Mar 13Pushed 1y ago28 watchersCompare [ Source](https://github.com/OXID-eSales/testing_library)[ Packagist](https://packagist.org/packages/oxid-esales/testing-library)[ Docs](https://www.oxid-esales.com/en/home.html)[ RSS](/packages/oxid-esales-testing-library/feed)WikiDiscussions b-8.0.x Synced 1mo ago READMEChangelog (9)Dependencies (22)Versions (137)Used By (8) OXID eShop Testing Library ========================== [](#oxid-eshop-testing-library) [![https://img.shields.io/packagist/v/oxid-esales/testing-library.svg?maxAge=3600](https://camo.githubusercontent.com/5052fdc57fe16d1c79d1f02d2df93200813ec047994e11d98c2bdee043952fe8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f7869642d6573616c65732f74657374696e672d6c6962726172792e7376673f6d61784167653d33363030)](https://packagist.org/packages/oxid-esales/testing-library)Warning! Testing library is deprecated. Please use native PHPUnit for testing. The OXID eShop testing library can be used to test OXID eShop 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 OXID eShop. 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 ------------ [](#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 ------------ [](#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](https://getcomposer.org/download/). ### Selecting where to install testing library [](#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) [](#option-1-selecting-shop-directory-for-installation-preferred-way) To install testing library within shop directory, update/create `composer.json` with following values: ``` { "name": "oxid-esales/eshop", "description": "OXID eShop", "type": "project", "keywords": ["oxid", "modules", "eShop"], "homepage": "https://www.oxid-esales.com/en/home.html", "license": [ "GPL-3.0", "proprietary" ], "require-dev": { "oxid-esales/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/oxid-esales/testing-library/test_config.yml.dist", "parameter-key": "mandatory_parameters", "env-map": { "shop_path": "SHOP_PATH", "shop_tests_path": "SHOP_TESTS_PATH", "module_ids": "MODULE_IDS" } } } } ``` 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) [](#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://github.com/OXID-eSales/testing_library`). Installing this way, binaries will be accessible from `testing_library/bin`. ### Installing testing library [](#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](README.md#configuration) Running tests ------------- [](#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. - `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`. 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` 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 [](#run-with-phpstorm) You need to setup path to bootstrap and configuration file 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" and "Default configuration file" checkbox and choose paths to bootstrap and configuration file. Path to bootstrap: {source}/vendor/oxid-esales/testing-library/bootstrap.php Path to the configuration file: {source}/vendor/oxid-esales/testing-library/phpunit.xml Configuration ------------- [](#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 [](#configuration-parameters) #### Mandatory parameters [](#mandatory-parameters) These parameters are required for testing library to work properly. Parameter nameDescription**shop\_path**Path to eShop source. Defaults to the same directory as to where vendor is located. Supports relative and absolute paths. Can be left empty when installed from shop or module directory.**shop\_tests\_path**Path to eShop tests. If shop resides in `/var/www/shop/source` and tests are in `/var/www/shop/tests`, this should be set to `../tests`. Supports relative and absolute paths.**module\_ids**When testing installed modules, specify the module id within shop. Multiple module ids can be specified separated by comma: 'module1\_id,module2\_id,module3\_id'. If no modules will be tested, leave this field empty or `null`. Default `null`#### Optional parameters [](#optional-parameters) These parameters are not required in order to work, but they provide additional functionality and options when testing. Parameter nameDescription**shop\_url**eShop base url (if not set, takes it from shop's config.inc.php file). Default `null`.**shop\_serial**For PE and EE editions shop serial has to be specified for shop installer to work. Default `''`.**enable\_varnish**Run tests with varnish on or off. Shop has to be configured to work with varnish, correct serial must be used. Default `false`**is\_subshop**Whether to run subshop tests. Currently only used when running selenium tests. Default `false`.**install\_shop**Whether to prepare shop database for testing. Shop `config.ing.php` file must be correct. Default `true`.**remote\_server\_dir**If defined, testing services will be copied to this directory and called via url instead of used locally. Example: :/path/to/shop.**shop\_setup\_path**eShop setup directory. After setting up the shop, setup directory will be deleted. For shop installation to work during tests run, path to this directory must be specified. If not set, uses default (i.e. shop dir `/var/www/eshop/source/`, default setup dir `/var/www/eshop/source/setup` ).**restore\_shop\_after\_tests\_suite**Whether to restore shop data after running all tests. If this is set to false, shop will be left with tests data added on it. Default `false`.**restore\_after\_acceptance\_tests**Whether to dump and restore the database after a single acceptance test. Default `true`.**restore\_after\_unit\_tests**Whether to dump and restore the database after all tests are finished in a single unit, integration test suite. Default `true`.**test\_database\_name**If specified, this database is used instead of real one for unit and integration tests**tmp\_path**If php has no write access to /tmp folder, provide alternative temp folder for tests.**database\_restoration\_class**Currently exists `DatabaseRestorer` and `LocalDatabaseRestorer`. `LocalDatabaseRestorer` - is faster, but does not work with remote databases, `DatabaseRestorer` - can be used with external database. Default `DatabaseRestorer`.**activate\_all\_modules**Whether to activate all modules defined in modules\_path when running tests. Normally only tested module is activated during test run. Modules will be activated in the specified order. Default `false`.**run\_tests\_for\_shop**Whether to run shop unit tests. This applies only when correct shop\_tests\_path are set. Default `true`.**run\_tests\_for\_modules**Whether to run modules unit tests. All modules provided in modules\_path will be tested. If shop\_tests\_path and run\_shop\_tests are set, shop tests will be run with module tests. Default `true`.**screen\_shots\_path**Folder where to save selenium screen shots. If not specified, screenshots will not be taken. Default `null`. Default `false`.**screen\_shots\_url**Url, where selenium screen shots should be available. Default `null`.**browser\_name**Browser name which will be used for acceptance testing. Possible values: `*iexplore, *iehta, *firefox, *chrome, *piiexplore, *pifirefox, *safari, *opera`. make sure that path to browser executable is known for the system. Default `firefox`.**selenium\_server\_ip**Selenium server IP address. Used to connect to selenium server when Mink selenium driver is used for acceptance tests. Default `127.0.0.1`.**additional\_test\_paths**Used for running additional tests. It's possible to add paths separated by comma. Loads tests in same manner as eShop or modules tests.**retry\_times\_after\_test\_fail**How many times to try test before marking it as failure. Could be used for unstable tests which fails randomly.### Changing PHPUnit parameters [](#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 [](#execution-before-unit-test-run-with-additionalincphp) 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 ------------- [](#writing-tests) ### Directory Structure [](#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 [](#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 [](#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 [](#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](https://github.com/OXID-eSales/testing_library/issues/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 OXID eShop acceptance tests. #### Methods usage [](#methods-usage-1) 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("example_test@oxid-esales.dev", "useruser"); ``` Rest of the methods can be found in class: `OxidEsales\TestingLibrary\AcceptanceTestCase`. ### Changing database restoration mechanism [](#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 [](#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) Testing library branch names follow the OXID eShop component branch names. Which means that branch names do not follow testing library version numbers, but represent the target version of the OXID eShop compilation. For example: Branch NameOXID eShop Compilation Target Versionb-6.2.xv6.2.\* (Next patch release of OXID eShop compilation v6.2)b-6.3.xv6.3.\* (Next patch release of OXID eShop compilation v6.3)masterOXID eShop compilation master branchTests running workflow ---------------------- [](#tests-running-workflow) Graphically visualized workflow can be found in workflow.puml. This file can be opened with tool called PlantUml (). ### Health Score 52 — FairBetter than 96% of packages Maintenance29 Infrequent updates — may be unmaintained Popularity45 Moderate usage in the ecosystem Community38 Small or concentrated contributor base Maturity86 Battle-tested with a long release history Bus Factor3 3 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~33 days Recently: every ~94 days Total 81 Last Release 1400d ago Major Versions v6.0.1 → v7.0.02019-11-07 v5.0.8 → v7.1.12020-05-05 v7.3.0 → v8.0.02021-04-12 v8.0.1 → v9.0.02021-07-06 6.4.x-dev → v8.1.02021-12-02 PHP version history (3 changes)v6.0.1PHP ^7.0 v8.0.0PHP ^7.3 || ^8.0 v8.1.0PHP ^7.4 || ^8.0 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1374817?v=4)[oxid](/maintainers/oxid)[@OxID](https://github.com/OxID) --- Top Contributors [![Shiftas](https://avatars.githubusercontent.com/u/3593099?v=4)](https://github.com/Shiftas "Shiftas (290 commits)")[![MantasVaitkunas](https://avatars.githubusercontent.com/u/623436?v=4)](https://github.com/MantasVaitkunas "MantasVaitkunas (105 commits)")[![Sieg](https://avatars.githubusercontent.com/u/98882?v=4)](https://github.com/Sieg "Sieg (88 commits)")[![liulka-oxid](https://avatars.githubusercontent.com/u/56023474?v=4)](https://github.com/liulka-oxid "liulka-oxid (66 commits)")[![robertblank](https://avatars.githubusercontent.com/u/7868142?v=4)](https://github.com/robertblank "robertblank (51 commits)")[![godefroy-le-hardi](https://avatars.githubusercontent.com/u/31134636?v=4)](https://github.com/godefroy-le-hardi "godefroy-le-hardi (51 commits)")[![sauliusstasiukaitis](https://avatars.githubusercontent.com/u/3603014?v=4)](https://github.com/sauliusstasiukaitis "sauliusstasiukaitis (37 commits)")[![vilmal](https://avatars.githubusercontent.com/u/3765393?v=4)](https://github.com/vilmal "vilmal (34 commits)")[![sebbbbauer](https://avatars.githubusercontent.com/u/1807282?v=4)](https://github.com/sebbbbauer "sebbbbauer (29 commits)")[![AlfonsMartin](https://avatars.githubusercontent.com/u/35966734?v=4)](https://github.com/AlfonsMartin "AlfonsMartin (26 commits)")[![hkreuter](https://avatars.githubusercontent.com/u/3692295?v=4)](https://github.com/hkreuter "hkreuter (16 commits)")[![mtkoltan](https://avatars.githubusercontent.com/u/7591102?v=4)](https://github.com/mtkoltan "mtkoltan (12 commits)")[![SebGoesToSpace](https://avatars.githubusercontent.com/u/62789384?v=4)](https://github.com/SebGoesToSpace "SebGoesToSpace (11 commits)")[![kenariosz](https://avatars.githubusercontent.com/u/2828175?v=4)](https://github.com/kenariosz "kenariosz (7 commits)")[![rezonanc-oxid](https://avatars.githubusercontent.com/u/8058763?v=4)](https://github.com/rezonanc-oxid "rezonanc-oxid (7 commits)")[![a-afsharfarnia](https://avatars.githubusercontent.com/u/54709809?v=4)](https://github.com/a-afsharfarnia "a-afsharfarnia (5 commits)")[![ramunasskarbalius](https://avatars.githubusercontent.com/u/3593717?v=4)](https://github.com/ramunasskarbalius "ramunasskarbalius (4 commits)")[![bpeschlaudert](https://avatars.githubusercontent.com/u/80339080?v=4)](https://github.com/bpeschlaudert "bpeschlaudert (3 commits)")[![realFlowControl](https://avatars.githubusercontent.com/u/14161194?v=4)](https://github.com/realFlowControl "realFlowControl (3 commits)")[![nymo](https://avatars.githubusercontent.com/u/884833?v=4)](https://github.com/nymo "nymo (3 commits)") --- Tags developer-toolsoxid-esalesphptooltestinglibraryOXIDmoduleseshop ### Embed Badge ![Health badge](/badges/oxid-esales-testing-library/health.svg) ``` [![Health](https://phpackages.com/badges/oxid-esales-testing-library/health.svg)](https://phpackages.com/packages/oxid-esales-testing-library) ``` ### Alternatives [brianium/paratest Parallel testing for PHP 2.5k118.8M754](/packages/brianium-paratest)[orchestra/testbench Laravel Testing Helper for Packages Development 2.2k39.1M32.1k](/packages/orchestra-testbench)[drupal/core-dev require-dev dependencies from drupal/drupal; use in addition to drupal/core-recommended to run tests from drupal/core. 2021.0M277](/packages/drupal-core-dev)[magento/magento2-functional-testing-framework Magento2 Functional Testing Framework 15511.5M30](/packages/magento-magento2-functional-testing-framework)[lucatume/wp-browser A set of Codeception modules to test WordPress projects. 6343.8M153](/packages/lucatume-wp-browser)[oxid-esales/oxideshop-ce This package contains OXID eShop CE source code. 2381.1M191](/packages/oxid-esales-oxideshop-ce) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)