Edit on GitHub
Jump to docs navigation

Extending / Advanced / Writing Unit Tests

Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.0 instead?

If you would like to write unit tests for an extension you can very easily piggy-back onto the Bolt core classes to test how the extension interacts with a Bolt application.

There are a few things you will need to add to your extension to get setup.

Step 1: Modifications to composer.json

A few simple additions are needed to get Bolt installed as a dependency and your tests namespaced. Use the following as an example, changing the name of your test directory to suit.

    "name": "bolt/members",
    "description": "Membership creation and management for Bolt",
    "require-dev": {
        "phpunit/phpunit": "^4.7"
    "minimum-stability": "dev",
    "prefer-stable": true,
    "autoload": {
        "psr-4": {
            "Bolt\\Extension\\Bolt\\Members\\": "src",
            "League\\Event\\": "lib/League/Event",
            "League\\OAuth2\\Client\\": "lib/League/OAuth2/Client/",
            "Stevenmaguire\\OAuth2\\Client\\": "lib/League/OAuth2/Client/"
    "autoload-dev": {
        "psr-4": {
            "Bolt\\Extension\\Bolt\\Members\\Tests\\": "tests",
            "Bolt\\Tests\\": "vendor/bolt/bolt/tests/phpunit/unit/"
    "extra": {
        "bolt-assets": "web",
        "bolt-class": "Bolt\\Extension\\Bolt\\Members\\MembersExtension",

In the above example the important things to note are the minimum-stability and prefer-stable settings. Then an additional PSR-4 namespace is added to load tests from the ./tests directory.

Step 2: Create a phpunit.xml.dist file

The example file below configures PHPUnit, place it in the root of the project and adjust where needed.

<?xml version="1.0" encoding="UTF-8"?>
<phpunit backupGlobals="false"
        <testsuite name="unit">
        <listener file="vendor/bolt/bolt/tests/phpunit/BoltListener.php" class="Bolt\Tests\BoltListener">
              <!-- Configuration files. Can be either .yml or .yml.dist files -->
              <!-- Locations can be relative to TEST_ROOT directory, the Bolt directory, or an absolute path -->
                  <element key="config">
                  <element key="contenttypes">
                  <element key="menu">
                  <element key="permissions">
                  <element key="routing">
                  <element key="taxonomy">
              <!-- Theme directory. Can be relative to TEST_ROOT directory, the Bolt directory, or an absolute path -->
                  <element key="theme">
              <!-- The Bolt SQLite database, leave empty to use the one bundled with Bolt's repository -->
              <!-- Location can be relative to TEST_ROOT directory, the Bolt directory, or an absolute path -->
                  <element key="boltdb">
              <!-- Reset the cache and test temporary directories -->
              <!-- Create timer output in app/cache/phpunit-test-timer.txt -->

Note: We refer to a tests/bootstrap.php file that doesn't exist yet.

Note: The listener is optional, it will copy in an Sqlite database with table structure matching current Bolt tests, and it will also copy in the specified theme, and configuration files which is helpful if you're writing unit tests.

Step 3: Create a bootstrap.php file

This sets up a tmp directory to store required Bolt files and sets a couple of constants.

Create the file tests/bootstrap.php containing the following:

include_once __DIR__ . '/../vendor/bolt/bolt/tests/phpunit/bootstrap.php';

define('EXTENSION_AUTOLOAD',  realpath(dirname(__DIR__) . '/vendor/autoload.php'));


Step 4: Write some tests that extends BoltUnitTest

Here's the simplest test you can write, we test that the extension gets registered correctly to the containing Bolt application.

For example, in tests/ColourpickerTest.php you can add:


namespace Bolt\Extensions\Bolt\Colourpicker\Tests;

use Bolt\Tests\BoltUnitTest;
use Bolt\Extensions\Bolt\Colourpicker\Extension;

 * This test ensures the Colourpicker Loads correctly.

class ColourpickerTest extends BoltUnitTest
    public function testExtensionLoads()
        $app = $this->getApp();
        $extension = new Extension($app);
        $app['extensions']->register( $extension );
        $name = $extension->getName();
        $this->assertSame($name, 'colourpicker');
        $this->assertSame($extension, $app["extensions.$name"]);

Step 6: Update .gitignore

Add the following to your .gitignore file:


NOTE: Adding the composer.lock file is optional if you wish to commit that but as extensions are not installed as a root package in Bolt, it will have no effect.

Step 7: Now you can run your tests

Make sure you have done a composer update so your dependencies are up to date, then simply run phpunit from the root of your extension.

Edit this page on GitHub
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.