Moodle Plugin Development

Acceptance Testing (Behat) with Docker

As a Moodle plugin developer, particularly if you intend to release your plugin via the directory, you will want to test your code in different scenarios. Typically I find that clients want a plugin for the current version of Moodle they are running but there always seems to be plans afoot to upgrade to a newer version and your plugin is expected to work in that version too. I like to develop with MySQL tables but occasionally the client runs a different database engine. To manage such diversity when testing, you may want to consider using the docker containers provided by Moodle HQ at in their git repository at https://github.com/moodlehq/moodle-docker. I, for one, wish I had discovered this previously.

A good question to ask yourself before attempting to create automated unit and accaptance tests for your plugin development project is whether it is worth the effort and whether your client is likely to accept the additional cost of doing so. I delve into these questions in another article but if you find yourself having to generate and test automated tests or manual testing in different scenarios, the docker solution is a good choice.

If you do not know what docker is, here is one definition “ Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package.” The Moodle docker environment is not actually a container but uses docker Compose to configure several docker containers to provide a Moodle environment and you get to provide the Moodle code to test.

As far as I can make out, it is possible to run Docker containers in Windows, if you must, so be aware that this article is Linux biased. For more information about using Linux containers on Windows see https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/linux-containers.

To see the different scenarios that you can test your plugin code with, consider the environment variables that you can set for the tests.

Environment Variable	Req?	Possible values	Default value
MOODLE_DOCKER_DB	yes	pgsql, mariadb, mysql, mssql, oracle	none
MOODLE_DOCKER_PHP_VERSION	no	7.3, 7.2, 7.1, 7.0, 5.6	7.1
MOODLE_DOCKER_BROWSER	no	firefox, chrome	firefox

Using git to manage your Moodle installation (see https://docs.moodle.org/37/en/Git_for_Administrators), you can more easily test several versions of Moodle with your plugin installed. The local repository directory can be your local webserver’s Moodle document root. The webserver by default runs on localhost and port 8000 though along with the document root, you can set the values as you see fit using the relevant environment settings.

Environment Variable	Req?	Possible values	Default value
MOODLE_DOCKER_WEB_HOST	no	any valid hostname	localhost
MOODLE_DOCKER_WEB_PORT	no	any integer value	8000
MOODLE_DOCKER_WWWROOT	yes	path on your file system	none

There are a few more environment variables – full list is available at https://github.com/moodlehq/moodle-docker.

To get started, you will need to install docker community edition. The instructions are at https://docs.docker.com/install/ and I found it fairly straightforward to install docker onto my Ubuntu laptop. After that you need to install the Compose tool and follow the relevant instructions at https://docs.docker.com/compose/install/.

Follow this up by cloning the Moodle docker repository – or alternatively download and unzip the repository - onto your device.

Now to run the Moodle environment, you need to set the required environment variables MOODLE_DOCKER_DB and MOODLE_DOCKER_WWWROOT and then copy the docker config file ‘config.docker-template.php’ to the wwwroot folder as config.php. I typically have this set up as a shell script but if you are a Linux user, you will need to use the source command (or the extra .) so that the script runs in your current environment otherwise the enviromental variables are lost when the script completes.

So typically, in the moodle docker folder, you would:

Set MOODLE_DOCKER_WWWROOT=/path/to/moodle/repository
Set MOODLE_DOCKER_DB=pgsql | mariadb | mysql | mssql | oracle
Copy config.docker-template.php $MOODLE_DOCKER_WWWROOT/config.php
Start up the containers with ‘ bin/moodle-docker-compose up -d’, the -d means detach i.e. runs in the background.
Wait for DB to come up (important for oracle/mssql) with ‘ bin/moodle-docker-wait-for-db’

Even if I am planning to just run automated tests, I still like to setup so I can log into the Moodle instance so I can install and uninstall my plugin code and for manual testing:

Run bin/moodle-docker-compose exec webserver php admin/cli/install_database.php --agree-license --fullname="Docker moodle" --shortname="docker_moodle" --adminpass=" Pa55w0rd " --adminemail="admin@example.com"

It is likely that you may not complete all your tests for each environment so sometimes you want to keep the data etc for the next time. For those occasions, you need to stop the containers and keep their state. This is achieved by running ‘ bin/moodle-docker-compose stop’ and then ‘ bin/moodle-docker-compose start’ in the Moodle docker folder to restart. You do have to setup the enviroment variables for the restart. To destroy the environment, you need to run ‘ bin/moodle-docker-compose down’.

Before starting the Moodle docker environment, I would typically checkout the Moodle version I want to test against. I normally install the plugin after the core Moodle is up and running so I can test the installation and before tearing it all done, the uninstall. Alternatively, you could copy your plugin’s folder into the Moodle repository folder prior to starting the docker containers. In the default setup, Moodle will be running on http://localhost:8000/.

Using git for Moodle gives you various options when testing. You can test new installations of your plugin on different Moodle versions as well as test upgrades from one version to the another. Obviously you can test with different database engines as well as with different versions of PHP.

The Moodle docker provides a way to run the Moodle CLI (command line interface) scripts with the ‘ bin/moodle-docker-compose exec webserver’ command option. So in order to initialise your test enviroments you would typically run ‘ bin/moodle-docker-compose exec webserver php admin/tool/phpunit/cli/init.php’ for PHPUnit tests and bin/moodle-docker-compose exec webserver php admin/tool/behat/cli/init.php for Behat acceptance testing. The Behat faildump directory is exposed at http://localhost:8000/_/faildumps/. You can also watch – at least the javascript tests – by installing and using a Virtual Network Computing (VNC) session – see https://github.com/moodlehq/moodle-docker#using-vnc-to-view-behat-tests for more information.

To run tests, refer to the documentation of the Moodle site. For Behat tests, see https://docs.moodle.org/dev/Running_acceptance_test#Step_2:_Running_acceptance_test_environment and https://docs.moodle.org/dev/PHPUnit#Test_execution for PHP unit tests.

The command to run the behat tests is slightly different from the the usual ‘ vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behatrun/behat/behat.yml --tags mod_myplugin’

instead being ‘ bin/moodle-docker-compose exec webserver php admin/tool/behat/cli/run.php –tags=@auth_manual’.

Emails generated by the Moodle instance are captured by Mailhog and you can view them in the ‘ /_/mail’ folder.

The Moodle docker environment consists of a number of docker containers :

moodle-docker_webserver_1
moodle-docker_mailhog_1
moodle-docker_exttests_1
moodle-docker_selenium_1
moodle-docker_db_1

If you need access to the container which are mainly Linux based – for example, to get access to the database, you can do so by running ‘ do cker exec -it $container$ /bin/bash’.

This article is one in a series covering automated testing for Moodle plugin development. You can find the other articles on the site.