Blog

Travis-CI is a free-for-OSS continuous integration server, which has become very popular in the PHP world. Drush, Symfony, and dreditor all use it for frequently testing their code base and pull requests for regressions and ensuring new functionality has the needed test coverage.

Compared to the current Drupal testbot, Travis-CI allows testing of not only simpletest on PHP 5.3 (for Drupal 7 projects), but of most everything that you can install on a Debian system, e.g. QUnit for JavaScript, Behat, PHPUnit, but also Ruby based projects, Bash projects, Go projects, etc.

You can also test various scenarios in a matrix like setup, e.g. different PHP versions to ensure your code runs on both PHP 5.3 and 5.4 or with different versions of a dependent library.

This flexibility comes with a price however, because you need to setup the whole environment yourself. The selected PHP version (with xdebug) and composer are pre-installed, but that's it. The Drupal base installation, the running of the tests, the parsing of the test output, and ensuring dependencies are there is all your own responsibility.

And because of that there are many different .travis.yml files floating around the net for various scenarios of setting up this or that, but in the end everyone re-invents the wheel. Until now…

As Easy as it Gets

I am proud to announce the drupal_ti project, which allows any module on drupal.org to easily leverage travis-ci.org for testing:

• PHPUnit
• SimpleTest
• Behat

The process (which I will show in more detail below) is as simple as copying a generic .travis.yml.dist file as .travis.yml to your modules root, push your repository to Github, activate the repository at travis-ci.org and you are done.

Oh, and while you are at it, if you add a .coveralls.yml file, then code coverage is automatically reported to coveralls.io, too (for PHPUnit).

All the hard work of installing drupal, running a web server, setting up Selenium, etc. is done by drupal_ti.

So you don't have to copy some .travis.yml you found on the net and spend hours debugging little edge cases (HHVM and sendmail, how to parse the simpletest output, etc.), but can depend on a proven and self-tested code base.

Features

• Drupal 8 ready: drupal_ti supports both Drupal 7 and 8 modules. Use DRUPAL_TI_ENVIRONMENT="drupal-8" for your Drupal 8 modules.
• Tested: drupal_ti tests its own code base for both Drupal 7 and Drupal 8 modules.
• Modular architecture: drupal_ti has so called 'runners' and you can combine either e.g. "phpunit simpletest" or run them as separate workers by specifying a matrix.
• Environment aware: drupal_ti has a file for each environment, which makes the code generic for both Drupal 7 and 8.
• Examples provided: drupal_ti provides easy examples of the needed files in tests/drupal-{7,8}/drupal_ti_test. So you can get started easily!
• Extensible: By specifying DRUPAL_TI_SCRIPT_DIR_BEFORE or DRUPAL_TI_SCRIPT_DIR_AFTER you can easily create your own runners and environment includes that run before or after the main runners. This could even come from composer.
• Usable for non-travis CI: Because drupal-ti is just a command and because .travis.yml just has some environment vars, you can just copy the main declarations to some environment.sh file, set the TRAVIS_BUILD_DIR and use it locally, too.

An Example Conversion

My module registry_autoload uses simpletest on drupal.org to test its features. Now I want to test some advanced trait support, which needs PHP 5.4, so travis-ci.org is an option to do so.

Step 1 - Create the GitHub Repository and Push Your Code

1. Sign in to github.com
2. Click: + > New repository, enter: registry_autoload
3. Click: Create repository

Copy the commands displayed by Github to push your code to GitHub. I like to use drupal.org as my upstream and GitHub as my origin remote:

$ git clone --branch 7.x-1.x Fabianx@git.drupal.org:project/registry_autoload.git
$ cd registry_autoload
$ git remote rename origin upstream
$ git remote add origin git@github.com:LionsAd/registry_autoload.git
$ git push -u origin 7.x-1.x

Step 2 - Activate Travis-ci.org

Now head over to travis-ci.org:

1. Choose "Sign in with GitHub" and follow instructions
2. Click on your name at the top right, "Fabian Franz" for me
3. Click: "Sync now" if you don't see the repository, yet
4. Simply switch the toggle to "ON" for the project
5. Click on the repository settings icon (the "tools icon")
6. Toggle "Build only if .travis.yml is present"
7. Click on "Build history"
8. Leave the browser window open

Step 3 - Add drupal_ti .travis.yml

Now checkout a new branch, and add the .travis.yml file:

$ git checkout -b travis-integration
$ curl https://raw.githubusercontent.com/LionsAd/drupal_ti/master/.travis.yml.dist -O
$ mv .travis.yml.dist .travis.yml

Then, customize the following parts of the file:

    # Configuration vars.
    - DRUPAL_TI_MODULE_NAME="registry_autoload"
    - DRUPAL_TI_SIMPLETEST_GROUP="Registry"

And:

  matrix:
    # [[[ SELECT ANY OR MORE OPTIONS ]]]
    - DRUPAL_TI_RUNNERS="simpletest"

The simpletest group is returned from getInfo() in Drupal 7, but an annotation @group x in Drupal 8. Despite the name of the variable, you could also put in a class like RegistryAutoloadTestCase. Basically anything that SimpleTest accepts on the command line as last argument. The clue is that this variable accepts spaces e.g. "DrupalTi Test", which is else very difficult to achieve when passing variables around.

Now add the file and push to GitHub:

$ git add .travis.yml
$ git commit -m "Added travis integration"
$ git push origin travis-integration

Step 4 - Watch the Test Run

Now head back over to your browser window and magically there will be a new build, click on it and you will see a matrix like structure, here shown for build #2:

Click on PHP 5.4 and click the little button on the far right with "follow", to follow the output.

After a while the build is finished and all tests passed:

Congratulations, your project is now tested on travis-ci.org!

Now merge, the branch into your mainline and whenever you want to test a change on travis-ci.org just push a branch or make a pull request:

$ git checkout 7.x-1.x
$ git merge travis-integration
$ git push origin 7.x-1.x

# Also push the changes back to drupal.org
$ git push upstream 7.x-1.x

The easiest way to work with this kind of integration is to push all patches to origin first and once satisfied, push to upstream. That way GitHub and drupal.org are always in sync.

To be Continued…

In the next part of this series, I will explore how you can get started with unit testing locally and on travis-ci.org (using drupal_ti) and afterwards we will take a look at some easy behat setup.

If you are curious and want to start now, take a look at the run-* scripts in:

• https://github.com/LionsAd/drupal_ti/tree/master/tests/drupal-7/drupal_t...
• https://github.com/LionsAd/drupal_ti/tree/master/tests/drupal-8/drupal_t...

Enjoy and please leave me feedback either in the Drupal issue queue or on the GitHub project page.

About the Author

Fabian Franz is a Senior Performance Engineer and Technical Lead at Tag1
Consulting. He is author of the registry_autoload, service_container and render_cache modules for Drupal 7 and a contributor to Drupal 8 Core in the form of reviews, patches, and co-leader of the Twig initiative.