12 KiB

Raw Blame History

Testing

October CMS has a suite of tools available for running automated tests on your October instance and plugins. To run tests, you must ensure that you have PHPUnit installed and can run the phpunit command from a command-line interface.

System Tests
Creating Tests for Plugins
- Unit Tests
- Browser Tests

System Tests

The system tests cover the tests that analyse the core functionality of October CMS. To run these tests, we recommend that you use Git to checkout a copy of the development version of October CMS and use Composer to install all necessary dependencies.

You can do this on command-line by simply running the following:

git checkout git@github.com:octobercms/october.git
cd october
composer install

Unit Tests

The unit tests in October CMS can be found in the tests/unit folder and are executed through PHPUnit. You can run the tests by running the following command in the root folder of the October CMS installation:

./vendor/bin/phpunit

This will run tests for both October CMS and the Rain library. The Rain library tests can be found in the vendor/october/rain/tests folder.

Note that unit tests run in a special environment called testing. You may configure this environment by adding or modifying the configuration files in the config/testing/ directory.

Using a Custom Database Engine

By default, OctoberCMS uses SQLite stored in memory for the testing environment. If you wish to override this with your own database configuration, set the useConfigForTesting config to true in your /config/database.php file.

When the APP_ENV is testing and the useConfigForTesting is true database parameters will be taken from /config/database.php.

You can override the /config/database.php file by creating /config/testing/database.php. In this case variables from the latter file will be taken.

Browser Tests

Browsers tests are a more flexible type of automated test that run directly in a web browser. October CMS leverages the Laravel Dusk framework to run these tests, which in turn uses Google Chrome and a ChromeDriver install to run the tests.

Running the browser tests will require Google Chrome to be installed on your machine. Once this is done, you may prepare your installation for running Browser tests by running the following in your project root folder:

php artisan dusk:chrome-driver

Note: It is possible to use other browsers, or a standalone Selenium server, if you wish. Please see the Laravel Dusk documentation for more information.

Once installed, you may run the browsers test by simply running the following command in the root folder of the October CMS installation:

php artisan dusk

If you have previously run the browser tests and want to re-run only the tests that failed, you may use this shortcut to run just the failed tests:

php artisan dusk:fails

Note that your October CMS installation must be web-accessible in order to run the browser tests. Please review the next section on setting up the testing environment.

Testing Environment for Browser Tests

The Browser tests in October CMS are, by default, set up to run within a special testing environment called dusk. This is configured to run October CMS via the inbuilt PHP web server, using an SQLite database to store the database temporarily.

You may start this web server before running the browser tests simply by running the following:

php artisan serve

This environment is configured in two places: the .env.dusk file available in the project root, and within the config/dusk/ folder. You may modify either of these configuration files in order to configure the testing environment to your requirements.

When the browser tests are started, the .env file in your project (if any) is subtituted with .env.dusk for the duration of the tests. Once the tests end, the .env file is restored to its original content.

Note: The system browser tests will need to be authenticated with a superuser-level user to run correctly. If you are using the default environment, this will happen automatically.

If you are custom settings however, you may need to provide authentication information to Dusk in order for it to run. You can specify the environment variables DUSK_ADMIN_USER and DUSK_ADMIN_PASS to use specific authentication credentials during testing. These are available in the .env.dusk file.

JavaScript Tests

In addition to the PHP-based tests above, we also have a suite of unit tests for our JavaScript libraries and functions. These run on an NodeJS-based environment, so you will need to download and install NodeJS and NPM in order to install the tools required for these tests.

Once installed, you may install the tools by running the following in the browser root:

npm install

Then, you may run the following command to run the JavaScript tests:

npm run test

Creating Tests for Plugins

October CMS has made it easy for plugin developers to create unit and browser tests for their plugins.

Please read the sections below in order to configure your plugin for your required types of testing.

Unit Tests

To allow unit testing in your plugin, you must first create a file called phpunit.xml in the plugin base directory with the following content - for example, in a file /plugins/acme/blog/phpunit.xml:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    backupGlobals="false"
    backupStaticAttributes="false"
    bootstrap="../../../tests/bootstrap.php"
    colors="true"
    convertErrorsToExceptions="true"
    convertNoticesToExceptions="true"
    convertWarningsToExceptions="true"
    processIsolation="false"
    stopOnFailure="false"
>
    <testsuites>
        <testsuite name="Plugin Unit Test Suite">
            <directory>./tests/unit</directory>
        </testsuite>
    </testsuites>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="CACHE_DRIVER" value="array"/>
        <env name="SESSION_DRIVER" value="array"/>
    </php>
</phpunit>

Then you may create a tests/unit/ directory to contain the unit test classes.

Each unit test class file must match the following guidelines:

Each file can be any number of folder levels deep, but must end with Test.php.
Each test class must have a namespace that follows both your plugin name as well as the folder location of your test.
Each test class must extend the October\Core\Tests\PluginTestCase class.

For example, if you have a plugin Acme.Blog that contained a Post model that you wanted to test, you would create the test class file in tests/unit/models/PostTest.php, with the test class code containing the following:

<?php namespace Acme\Blog\Tests\Unit\Models;

use Acme\Blog\Models\Post;
use October\Core\Tests\PluginTestCase;

class PostTest extends PluginTestCase
{
    public function testCreateFirstPost()
    {
        $post = Post::create(['title' => 'Hi!']);
        $this->assertEquals(1, $post->id);
    }
}

The October\Core\Tests\PluginTestCase class takes care of ensuring that you have a clean database for each test, in order to run each test in isolation. If you need to run some code before, or after each test, you may overwrite the setUp and tearDown methods in your class. It is important, however, that you allow the parent methods to run too.

public function setUp(): void
{
    parent::setUp();

    // Load necessary model fixture
    $this->postFixture = PostFixture::create(['title' => 'Test Post']);
}

public function tearDown(): void
{
    // Remove model fixtur
    unset($this->postFixture);

    parent::tearDown();
}

Note: If your plugin uses configuration files, then you will need to run System\Classes\PluginManager::instance()->registerAll(true); in the setUp method of your tests.

Below is an example of a base test case class that should be used if you need to test your plugin working with other plugins instead of in isolation.

use System\Classes\PluginManager;
use October\Core\Tests\PluginTestCase;

class BaseTestCase extends PluginTestCase
{
    public function setUp()
    {
        parent::setUp();

        // Get the plugin manager
        $pluginManager = PluginManager::instance();

        // Register the plugins to make features like file configuration available
        $pluginManager->registerAll(true);

        // Boot all the plugins to test with dependencies of this plugin
        $pluginManager->bootAll(true);
    }

    public function tearDown()
    {
        parent::tearDown();

        // Get the plugin manager
        $pluginManager = PluginManager::instance();

        // Ensure that plugins are registered again for the next test
        $pluginManager->unregisterAll();
    }
}

To run the unit tests for your plugin, simply go to the base folder for your plugin, and run the following command:

../../../vendor/bin/phpunit

This will execute PHPUnit in the context of your plugin.

Browsers Tests

Browser tests for plugins can be set up in much the same way as unit tests, with a small number of differences.

Browsers tests require their own PHPUnit XML configuration file. You should create a phpunit.dusk.xml file in your project base directory with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit
    backupGlobals="false"
    backupStaticAttributes="false"
    bootstrap="../../../tests/bootstrap.php"
    colors="true"
    convertErrorsToExceptions="true"
    convertNoticesToExceptions="true"
    convertWarningsToExceptions="true"
    processIsolation="false"
    stopOnFailure="false"
>
    <testsuites>
        <testsuite name="Plugin Browser Test Suite">
            <directory>./tests/browser</directory>
        </testsuite>
    </testsuites>
    <php>
        <env name="APP_ENV" value="dusk"/>
        <env name="CACHE_DRIVER" value="array"/>
        <env name="SESSION_DRIVER" value="array"/>
    </php>
</phpunit>

Browser tests should be separate from unit tests - you can instead store browser tests within the tests/browser/ directory.

Browser test files follow the same rules as unit test files, however, instead of extending the October\Core\Tests\PluginTestCase class, they should instead extend the October\Core\Tests\BrowserTestCase class.

To run the plugin browser tests, you must run the following command within the root folder of your October CMS install, not the plugin:

php artisan dusk -c plugins/acme/test/phpunit.dusk.xml

12 KiB Raw Blame History

Testing

System Tests

Unit Tests

Using a Custom Database Engine

Browser Tests

Testing Environment for Browser Tests

JavaScript Tests

Creating Tests for Plugins

Unit Tests

Browsers Tests

12 KiB

Raw Blame History