Automatic Blender Addon Testing with TravisCI

Today I want to introduce you on how to automaticly test your blender addon with the very popular continous integration service Travis.

If you are a blender addon developer you might have been strugling with automated testing of your addons, just as I did.

I'm the maintainer of an addon that exports blender files to the X-Plane OBJ-file format.

Since today I was unable to automaticly test my addon, which is hosted on GitHub. However there is a really good continous integration service called Travis which seamlessly integrates with GitHub. A lot of Open Source projects use Travis to create automatic builds on each push. This increases software quality and trust, as users and developers immediatly see if the software is failing tests or not.

Using TravisCI for blender is not very straight forward and required some try and error until I got it working.

This is why I want to share on how you can setup Travis to test your blender addon.

1. Setup testing environment

At first you need to setup your automatic tests.

Python has the great unittest module which provides us with assertions and test runners. However we cannot use its command line utilities to test our addon, as testing has to be done within blender.

For my tests I created a tests folder.

Within that folder I created a folder for each test group. And within each subfolder I created a .test.blend file together with a .test.py python script file containing the actual tests.

The blend file contains assets to be tested against. In the example below the blend file is even empty as we just want to test, if our addon is enabled.

tests/
  addon/
    addon.test.blend
    addon.test.py

The tests/addon/addon.test.py for my addon looks as follows:

import unittest

# import the already loaded addon
import io_xplane2blender

class TestAddon(unittest.TestCase):
    def test_addon_enabled(self):
        # test if addon got loaded correctly
        # every addon must provide the "bl_info" dict
        self.assertIsNotNone(io_xplane2blender.bl_info)

# we have to manually invoke the test runner here, as we cannot use the CLI
suite = unittest.defaultTestLoader.loadTestsFromTestCase(TestAddon)
unittest.TextTestRunner().run(suite)

Then within the root of my addon source I've added a simple tests.py python script which acts as a test runner:

import os
import glob
import subprocess
import sys

blenderExecutable = 'blender'

# allow override of blender executable (important for CI!)
if len(sys.argv) > 1:
    blenderExecutable = sys.argv[1]

# iterate over each *.test.blend file in the "tests" directory
# and open up blender with the .test.blend file and the corresponding .test.py python script
for file in glob.glob('./tests/**/*.test.blend'):
  # change 'io_xplane2blender' to match your addon
  subprocess.call([blenderExecutable, '--addons', 'io_xplane2blender', '--factory-startup', '-noaudio', '-b', file, '--python', file.replace('.blend', '.py')])

Once this is done you can run your tests using:

$ python tests.py

If you want to test against a specifique blender installation you can provide the path to the blender executable as the first argument to the tests.py

$ python tests.py [path-to-blender-executable]

2. Setting up Travis for your GitHub repository

Next you need to tell TravisCI to watch your GitHub repository.

1. For this visit https://travis-ci.org/ and hit "Sign in with GitHub" in the upper right corner.
2. After signing in with GitHub you'd be able to add your repository to Travis.
3. Once you've activated your repository enter the repository settings in Travis and be sure to check "Build only if .travis.yml is present".

3. Create .travis.yml

Next you have to create a .travis.yml file within the root of your repository.

# this is essential to make python work out of the box
language: python

# Define which python version to build against.
# As blender comes bundled with it's own python you can use just one version if you like
python:
  - "2.7"
  - "3.4"

before_install:
  # update apt-gets repository sources
  - sudo apt-get update -qq

  # install blender from official sources.
  # This will most propably install an outdated blender version,
  # but it will resolve all system dependencies blender has to be able to run.
  - sudo apt-get install blender

install:
  # create temp directory where we store a recent blender version
  - mkdir tmp && cd tmp

  # download the blender version you want to test against
  - wget http://mirror.cs.umn.edu/blender.org/release/Blender2.74/blender-2.74-linux-glibc211-x86_64.tar.bz2

  # Extract the archive
  - tar jxf blender-2.74-linux-glibc211-x86_64.tar.bz2

  # rename the extracted folder to "blender" for easier reference
  - mv blender-2.74-linux-glibc211-x86_64 blender

  # remove the archive, we do not need it anymore
  - rm blender-2.74-linux-glibc211-x86_64.tar.bz2

  # go back to root directory
  - cd ..

  # now create a symlink to the addon within blenders addons directory
  # this is important, because otherwhise blender would not be able to load the addon
  - sudo ln -s ${PWD}/io_xplane2blender ${PWD}/tmp/blender/2.74/scripts/addons/io_xplane2blender

# Finally start our test runner passing it the blender executable from the downloaded blender release
script: python tests.py ./tmp/blender/blender

Now commit the .travis.yml file and wait for Travis to run your build.