The goal of this project is to facilitate the running of tests and code analysis against a Moodle plugin in CI tool of your choice. All of these tests and tools are run everytime a change is pushed to a GitHub branch or pull request.

We currently provide user manual how to use it with Travis CI and GitHub Actions, if you are using moodle-plugin-ci with other CI services please do share your setup examples by creating a ticket.

Why would you want to do this? It saves you from having to remember to setup and run PHPUnit, Behat, code checker, etc every single time you make a change. If you have enough test coverage, it also makes accepting pull requests painless because you can be more confident that the change wont break anything. There are many more advantages to use CI tools, like being able to test your code against multiple databases, multiple PHP versions, etc.

This project supports the following testing frameworks and code analysis tools:

Requirements

The requirements for Version 3 are PHP 7.0 or later and Moodle 3.2 or later.

In addition, the plugin being tested must have a version.php file and $plugin->component must be defined within it.

If you need to run your plugin in earlier versions of Moodle, then please use previous versions of this tool. Documentation and more information about Version 2 can be found here. Similarly, information about Version 1 can be found in here

Please know older versions (1 and 2) are no longer getting new features and may not receive additional updates.

Getting started

Follow steps to get your Moodle plugin building in CI tool of your choice.

Travis CI

Step 1

Sign into Travis CI with your GitHub account. Once you’re signed in, and Travis CI will have synchronized your repositories from GitHub. Go to your profile page and enable Travis CI for the plugin you want to build. Now whenever your plugin receives an update or gets a new pull request, Travis CI will run a build to make sure nothing broke.

Step 2

Copy the .travis.dist.yml file into the root of your plugin and rename it to .travis.yml. Now might be a good time to review the .travis.yml contents and remove anything that is not needed. See this help document for an explanation about the contents of the this file. Once you have added the .travis.yml file, commit and push up to GitHub, to trigger a Travis CI build. Navigate back to Travis CI to see if your build passes or fails.

GitHub Actions

Step 1

Copy gha.dist.yml file to .github/workflows directory in your project. You can give this file any name, e.g. moodle-ci.yml which we use in this document. Review the moodle-ci.yml contents and remove anything that is not needed. See this help document for an explanation about the contents of the this file. Once you have added the .github/workflows/moodle-ci.yml file, commit and push up to GitHub, to trigger a CI build.

Step 2

On GitHub, navigate to the main page of the repository. Under your repository name, click Actions tab and see your build status. You may find this Quick Start manual useful. Now whenever you push commits to your plugin repo or it gets a new pull request, GitHub will run a build to make sure nothing broke.

Getting more of CI

Next steps on your continuous build journey may include:

  • Reviewing the help documentation to further improve and customize your build.
  • Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
  • Show off your build status by adding the build status badge to your plugin’s README file.
  • Write new tests to increase your code coverage.
  • Contribute to this repo if you have improvement idea or found an issue.
  • Enjoy your favorite beverage because you no longer have to waste time manually testing your plugin!

Upgrading

Guides to updating your plugin’s .travis.yml file to use the latest versions of this tool.

Documentation

Visit the help page for a complete list of documents, guides and links.

Usage / Versioning

This project uses Semantic Versioning for its public API. The public API for this project is defined as the CLI interface of the moodle-plugin-ci script. Everything outside of this script is considered to be private API and is not guaranteed to follow Semantic Versioning.

The commands ran via the moodle-plugin-ci script by default take no arguments. It is recommended, if at all possible, to avoid using arguments to prevent problems with future versions. Rest assured though that if any arguments are modified, it will be in the change log and the version will be bumped appropriately according to Semantic Versioning.

License

This project is licensed under the GNU GPL v3 or later. See the LICENSE file for details.