Plugin test workflow with PHPUnit
Introduction
In this guide, we will use PHPUnit to set up an optimized testing workflow for Kirby plugins with the ability to have custom blueprints and content for each plugin under a single Kirby installation.
Prerequisites
PHPUnit
If you don't have PHPUnit, follow the instructions on their site to install it.
Kirby
We need a Kirby installation too. It can house all our plugins. Since each plugin will have its own content (although it can use the content of the installation), we will use the Plainkit, which is very minimal:
Setup
Installing a plugin
Create and enter in the plugins folder where Kirby expects plugins:
Then, put your plugin there by adding it as a submodule. In this example, we will use the link-field plugin:
Let's check if we successfully added the plugin: Open the site.yml
blueprint and add a new field with type link
:
When you open the Panel, you should see something like this:
Bootstrapping Kirby
Open kirbyplugins/index.php
and you'll see:
This is the root script that handles every Kirby request. It requires another script, bootstrap.php
, that loads all Kirby-related stuff and then creates an instance of the Kirby object that is used to render the page.
We need to do the same within our plugin. But we have to provide some configuration to the Kirby object and instead of rendering it, we will run some tests.
Folder Structure
In the plugin folder, create the following directory structure:
The kirby
folder will contain the plugin's custom blueprints and content, suites
will contain our tests, and bootstrap.php
will be the script that sets up Kirby.
The Bootstrap script
Open bootstrap.php
and add:
This requires the same script that Kirby normally requires and echoes the site title so we can see if it works. Run the script with the PHP CLI and you should see Site Title
in the output:
Custom Kirby components
Copy the installed kirbyplugins/content
and kirbyplugins/site/blueprints
and put them in the plugin's tests/kirby
folder. You should have a similar directory structure like this:
Then, modify the plugin's bootstrap.php
script so that Kirby is set up to use those folders instead:
To test that, open tests/kirby/content/site.txt
and change…
…to:
Run the bootstrap.php
script again and you should see the new title:
If everything was successful, remove the echo
line from the bootstrap.php
script.
Tests
You should check the PHPUnit documentation to learn how to write tests. We are going to do the same thing here, basically. Create tests/suites/MyTest.php
and put the following inside:
To run the test, we use the phpunit
command, supply the plugin's bootstrap.php
script, and specify the folder containing the tests:
You should see a similar output:
All that's left now is adding more tests!
Extras
Autoloading
If your plugin uses classes, you would normally autoload them before running the tests. However, you don't have to in this case because you probably include the classes in your plugin's index.php
file already. When testing, the plugin's bootstrap.php
loads Kirby, which loads our plugin, which then loads our classes.
Composer Scripts
Running the test command manually each time can be tedious. You can take a look at Composer scripts and use them instead. To do that, copy the test command to your plugin's Composer configuration and adjust the paths accordingly:
Then, execute composer run test
in your shell and the tests should run.
Using the Panel
To be extra fancy, you can use the Panel to edit your plugin's custom content. Open the plugin's bootstrap.php
script and change it so that the created Kirby object is returned:
After that, modify the installation's root index.php
so that it uses this Kirby object instead:
You might have noticed that kirby/bootstrap.php
is required both in index.php
and in our plugin's bootstrap.php
. That's OK because our own script uses require_once
so that the file is included only once.
If you open the Panel, you should see your custom plugin content and be able to edit it. Any changes you make will be saved to the plugin's content
folder.
Other custom components
In this guide, we used only custom blueprints and content. However, you can define other custom components for your plugin as well. To do so, change the roots in your plugin's bootstrap.php
accordingly. This means you can have global setups in your Kirby installation and each plugin can define its own components as needed.