Unit Tests

Test, Test, Test

Get Unit Tests Now!
A free utility that integrates PHPUnit into your ExpressionEngine setup. It makes it easy to write, run, and manage automated tests in an EE-context-safe environment—ideal for Add-On development, maintenance, and ensuring high code quality.

Summary

Feature Details
Purpose Run PHPUnit tests in ExpressionEngine context
Required For Certain Add-Ons Yes—Login Alert (and possibly others) include tests needing this Add-On
Execution Interface EE’s CLI (php ee/eecli.php tests:run -a addon_name)
Environment Context Sandboxed environment within EE for safe testing
Compatibility ExpressionEngine 7

Typical Use Cases

Testing Your Own Add-On Development

  • If you’re building or maintaining EE Add-Ons, you can use Unit Tests to automate checking your code for regressions or unintended side effects during development.

Utilizing Add-Ons That Include Tests

  • When using Add-Ons by other developers that bundle their own test suites, installing Unit Tests allows you to run those and ensure they’re working correctly in your environment.

Improving Code Quality

  • Automating tests enables catching bugs early, keeping performance reliable, and encouraging best practices.

Features

Run PHPUnit for EE Add-Ons

  • This Add-On integrates PHPUnit into your ExpressionEngine setup, letting you run unit tests against ExpressionEngine code and your own Add-Ons in an environment that mimics actual site execution.

Required by Other Add-Ons for Testing

  • Several Add-Ons by mithra62 (e.g., Login Alert) optionally include testing suites that require the Unit Tests Add-On to be installed in order to execute their unit tests.

Command-Line Interface (CLI)

  • Leveraging ExpressionEngine’s CLI, you can run something like: php ee/eecli.php tests:run -a <addon_short_name>

How It Helps

Boosts Confidence in Code Stability

  • Automated tests can detect unexpected changes quickly, especially after updates or refactoring.

Makes Maintenance Easier

  • With a consistent test environment, it's easier to upgrade ExpressionEngine versions or PHP without breaking existing functionality.

Supports Better Add-On Ecosystem

  • By providing a standard testing framework, it encourages other developers to include tests in their Add-Ons, lifting overall project quality.

How It Works

EE Unit Tests is middleware between ExpressionEngine and your unit tests that you execute through ExpressionEngine's Command Line tool (introduced in 6.1).

Example Command

This will execute the Tests within the unit_tests add-on.

php ./system/eecli.php tests:run -a your_addon_name

The below will display the available tests on the system

php ./system/eecli.php tests:list

Creating Unit Tests for Add-ons

PHPUnit unit tests will be automatically detected within any tests directories stored in your add-on's root directory. For example, unit_tests/tests would be automatically picked up.

You can also configure a specific directory, relative to your add-on directory, within your addon.setup.php file, using the tests key.

Limitations

The biggest problem is that there isn't any Command Line Options Support for configuration. Too much. Not worth it. Instead, be sure to use a phpunit.xml configuration file stored within your Tests root directory.