Test Framework

Using the automated tests

The Test Framework resides within the not_for_release/testFramework directory. This directory is only really available if you checkout the Zen Cart code using git. It is not available if you just download the Zen Cart code as a zip file via a release link.

ALERT: Running Zen Cart tests locally has the potential to overwrite your Zen Cart database and destroy local data.

FIXME - work in progress

Preparation / Initial Setup

To prepare to run the Unit Test and Feature Test suites:

  1. First, install Composer on your PC:
  • go to getcomposer.org
  • download and install according to your operating system
  • follow the Getting Started instructions.
  1. Run composer install from inside root directory of your Zen Cart, on your PC.

Unit Tests

Unit tests can be run using:

composer unit-tests

in the root directory of your Zen Cart install.

Currently there are no local configuration requirements needed to run unit tests.

Feature Tests

While unit tests allow testing of functions/classes and other small fragments of code, feature tests allow testing of the application as a whole. The tests will typically access the application via URLs and test the resulting html returned by those URLs. Feature tests can also interact with the application, by setting form values and submitting those forms.

NOTE: Current feature tests don’t support javascript so interactions with pages that rely on javascript operating may not be possible. It is planned in the future to allow interactions with pages that rely on javascript using something like Selenium or Panther.

WARNING: Feature tests rely on Re-creating the database on each separate test suite. This means it will destroy your database. However, given that you should only be testing on a local development environment, this shouldn’t be a problem.

Feature tests can be run using

  • composer feature-tests will run all feature tests
  • composer feature-tests-store will run feature tests just for the store
  • composer feature-tests-admin will run feature tests just for the admin


Feature tests override the standard configure.php files used by Zen Cart and require you to create new configure files just for testing purposes.

Your configure files should be created in the not_for_release/testFramework/Support/configs directory and will be named _USER_.store.configure.php and _USER_.admin.configure.php where the _USER_ must be replaced by the user that your local environment runs as (ie: the username that you’re logged into your PC with).

You can find that user by running the following from the root of your installation.

php ./not_for_release/testFramework/detectUser.php

These files are exactly the same format as standard Zen Cart configure.php files and you can copy the admin.configure.php.example and store.configure.php.example files as starting points.

Migrations and Seeders

As the functional tests rely on a populated database, the test framework uses the mysql install files and demo data found within the zc_install folder, so this directory needs to be present.

There may be times though where you may want to alter the data to test a specific bug. An example may be when a search is not finding a product that contains certain strings, or a salemaker with specific data is not applying correctly.

In these cases you can create your own data seeder to add this data just for your test.

Custom seeders are created in the not_for_release/testFramework/Support/database/Seeders/ directory.

An example is not_for_release/testFramework/Support/database/Seeders/CustomSeeders/StoreWizardSeeder.php

You can run a custom seeder in your tests using


replacing StoreWizardSeeder with the name of your seeder class.

Mail Server

By default the Test Framework disables the sending of emails. This can be overridden by usng another configure file An example exists at not_for_release/testFramework/Support/configs/main.configure.php.example The example shows settings for using a local Mailpit (an email server emulator) instance. Note: Any misconfiguration here will likely result in failing tests.

As with other configure files noted above the actual configure file should be named _USER_.store.configure.php with _USER_ being replaced by the user running the tests.

Last modified March 17, 2024 by Chris Brown (c093cea).