In this post I’ll show how to run your meteor package tests from the command line (on Linux and OS X) and in Travis CI, the most popular cloud continuous integration service (free for open source projects), using our spacejam npm package.
How spacejam works
spacejam uses an undocumented option of meteor test-packages, –driver-package, to start meteor as follows:
meteor test-packages --driver-package test-in-console [package...]
The default driver-package for meteor test-packages is ‘test-in-browser’, which will run meteor test-packages with hot code pushes and an HTML reporter, where you can view your tinytest or munit test results.
test-in-console is a driver-package that meteor uses to test their own core packages internally from the command line and in continuous integration environments. It runs the tests for each connected browser only once, without hot code pushes, and prints the results to the browser console, instead of displaying them in an html reporter.
spacejam runs meteor test-packages using test-in-console, waits for meteor to be ready, and then starts phantomjs, a fully featured headless (no UI) browser, to run package tests both server side and client side, in phantomjs. Once all the tests have completed, spacejam exits with 0 if all the tests have passed, or with a non-zero exit code, otherwise. For a full list of possible exit codes, visit the spacejam documentation.
Testing your packages from the command line
First install spacejam. For the current user, use:
npm install -g spacejam
For all users, use:
# The -H is required sudo -H npm install -g spacejam
If you want to test a meteor package independently, without a meteor app, just cd to your package folder, and run:
spacejam test-packages ./
If you want to test packages in your app ‘packages’ folder, cd to your meteor app folder and list the packages to test on the command line:
spacejam test-packages mypkg1 mypkg2
If you don’t specify any packages, it will test all packages in the ‘packages’ folder, as well as all packages found in folders listed in the PACKAGE_DIRS environment variable.
How spacejam avoids conflicts with your app’s port and mongodb
In order to avoid conflicts with an app’s port, ROOT_URL, or mongodb, spacejam:
- Will start meteor test-packages with –port 4096.
Will not respect the ROOT_URL environment variable and will set it to http://localhost:4096/ before starting meteor test-packages.
Will not respect the MONGO_URL environment variable and will unset it before starting meteor test-packages. This design decision was made since we use free mongohq (compose.io) sandbox databases as our app’s mongodb during development, which is closer to our production scenario, and we didn’t want any data manipulations in our package tests to affect our meteor app, so we run our package tests on meteor’s internal mongodb, which also has the benefit of being faster.
If you still want to specify your own port, ROOT_URL or MONGO_URL for your package tests, you can do so using the –port, –root-url, and –mongo-url command line options. For a full list of command line options spacejam supports, visit the spacejam documentation.
Testing your packages in Travis CI
Travis CI is the most popular cloud based continuous integration service. It is free for open source projects and has excellent bi-directional integration with GitHub. It is also amazingly simple to setup and configure. All you need to do is to create a .travis.yml file in your GitHub repository root with instruction on how to build, test and optionally deploy your repository, and enable your repository in Travis CI. Once enabled, every time you push to GitHub, Travis CI will:
- Start a new clean ubuntu virtual machine.
- git clone your repository on it
- Checkout the latest commit in your git push
- Run the instructions in your .travis.yml file, and save all output as builds logs for your review (you can also view your build logs in real-time).
So, let’s get our hands dirty.
Enabling your GitHub repository in Travis CI
Goto https://travis-ci.org and sign in with your GitHub account. Then, follow the instructions in the screenshot below to enable your GitHub repository in Travis CI and navigate to it’s settings page (click on the screenshot to view it full size):
Protecting sensitive Meteor.settings data
If your package depends on sensitive data it reads from environment variables or Meteor.settings, such as 3rd party credentials (api keys, api passwords, etc.), do not add a Meteor.settings file with the credentials you use to your repository. Instead, define the METEOR_SETTINGS environment variable in your Travis CI repository settings, and set it’s value to the content of the Meteor.settings json file you use for testing. See the screenshot below for an example:
Adding the .travis.yml file to your repository
If your GitHub repository is a meteor package repository, create the following .travis.yml file in your repository root (make sure to preserve all indentations, this is the format of .yml files):
# .travis.yml files can have comments # The language specific base vm to use for this repository language: node_js # The node.js version to install node_js: "0.10.29" # All installation prerequisites before running your build / tests go here. install: # Install meteor - "curl https://install.meteor.com | /bin/sh" # Install spacejam - "npm install -g spacejam" # All build / test commands / scripts go here. # For testing meteor packages, that's all that is needed. script: - "spacejam test-packages ./"
Add and commit the file, push it to GitHub, and your first Travis CI build will start automatically. Yeah! To view the build results of your latest build, just click on the Current tab in Travis CI.
If your GitHub repository is a meteor app repository, or you have more than one package you want to test in the same repository, just use the same spacejam command(s) you would use to test those packages from the command line in the script section of your .travis.yml file.
Adding the Travis CI build status image to your repository README
If you want to communicate to the world and to the meteor community that your meteor package is in good standing and always tested, I recommend you add the Travis CI build status image to your repository README.md. Just add the markdown code below to the top of your README.md, replacing all links to our practicalmeteor:munit package repository in Travis CI, with links to your repository:
It will show up as follows:
For those of you who are not familiar with practicalmeteor:munit yet, it is an extension of tinytest with support for BDD style describe.it test suite semantics. It uses the same reporter tinytest uses and it can be used along side tinytest in the same package, allowing you to gradually migrate your tests from tinytest to munit.
- Travis CI allows you to easily configure the sending of build result notifications to many destinations, including Email, IRC, HipChat, WebHooks, etc. To view the list of supported notifications and how to configure them in your .travis.yml, visit the documentation.