How to write unit tests for your plugin – Introducing the Matomo Platform

This is the next post of our blog series where we introduce the capabilities of the Matomo (Piwik) platform (our previous post was How to verify user permissions). This time you’ll learn how to write unit tests in Matomo. For this tutorial you will need to have basic knowledge of PHP, PHPUnit and the Matomo platform.

When is a test a unit test?

There are many different opinions on this and it can be sometimes hard to decide. At Matomo we consider a test as a unit test if only a single method or class is being tested and if a test does not have a dependency to the filesystem, web, config, database or to any other plugin.

If a test is slow it can be an indicator that it is not a unit test. “Slow” is of course a bit vague. We will cover how to write other type of tests, such as integration tests, in one of our next blog posts.

Getting started

In this post, we assume that you have already installed Matomo 2.9.0 or later via git, set up your development environment and created a plugin. If not, visit the Matomo Developer Zone where you’ll find the tutorial Setting up Matomo and other Guides that help you to develop a plugin.

Let’s create a unit test

We start by using the Matomo Console to create a new unit test:

./console generate:test --testtype unit

The command will ask you to enter the name of the plugin the created test should belong to. I will use the plugin name “Insights”. Next it will ask you for the name of the test. Here you usually enter the name of the class you want to test. I will use “Widgets” in this example. There should now be a file plugins/Insights/tests/Unit/WidgetsTest.php which contains already an example to get you started easily:

/**
 * @group Insights
 * @group WidgetsTest
 * @group Plugins
 */
class WidgetsTest extends \PHPUnit_Framework_TestCase
{

    public function testSimpleAddition()
    {
        $this->assertEquals(2, 1+1);
    }

}

We don’t want to cover how you should write your unit test. This is totally up to you. If you have no experience in writing unit tests yet, we recommend to read articles on the topic, or a book, or to watch videos or anything else that will help you learn best.

Running a test

To run a test we will use the command tests:run which allows you to execute a test suite, a specific file or a group of tests.

To verify whether the created test works we will run it as follows:

./console tests:run WidgetsTest

This will run all tests having the group WidgetsTest. As other tests can use the same group you might want to pass the path to your test file instead:

./console tests:run plugins/Insights/tests/Unit/Widgets.php

If you want to run all tests within your plugin pass the name of your plugin as an argument:

./console tests:run insights

Of course you can also define multiple arguments:

./console tests:run insights WidgetsTest

This will execute all tests within the insights plugin having the group WidgetsTest. If you only want to run unit tests within your plugin you can do the following:

./console tests:run insights unit

Advanced features

Isn’t it easy to create a unit test? We never even created a file! You can accomplish even more if you want: You can generate other type of tests, you can run tests on Amazon’s AWS and more. Unfortunately, not everything is documented yet so we recommend to discover more features by executing the commands ./console list tests and ./console help tests:run.

If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.