What it's all about

Gagarin is a mocha based testing framework designed to be used with Meteor. It can spawn multiple instances of your meteor application and run the tests by executing commands on both server and client in realtime. In other words, Gagarin allows you to automate everything you could achieve manually with meteor shell, browser console and a lot of free time. There's no magic. It just works.

Gagarin is also useful when you need more refined control over the meteor processes and test fancy things, e.g. the behavior of your app on server restarts or when you have multiple app instances writing to the same database.

Quick start

First, install the cli-tool with npm:

npm install -g gagarin

Put your tests in tests/gagarin/ directory, e.g.

// tests/gagarin/myFirstTestSuite.js

describe('My first Gagarin test suite', function () {
  var server = meteor();
  it('should just work', function () {
    return server.execute(function () { console.log('I am alive!'); });
  });
});

Finally, in your project root directory run:

gagarin --verbose

We recommend running tests in verbose mode, at least before 1.0.0. Try gagarin --help if you need more options.

It is possible to use more advanced directory structures. You can, for example, place your test files in local package folders, without registering them in package.js. See Directory structure for more details.

Important notes

Gagarin is still under heavy development and a new release is published almost every week. Some parts of the API change over time and we can't guarantee backward compatibility before we reach 1.0.0. Minor version changes may contain breaking changes. Though, we put a lot of effort to reduce the risk of breaking old tests. Gagarin has it's own test suite with more than 250 test cases, which BTW are very good source of examples.

Windows support

Since version 0.4.10 gagarin can also run on windows platform. The only additional requirement is that it has to be run within the elevated prompt. This is because during the application build process we need to create a symbolic link to

[..]\AppData\Local\.meteor\packages\meteor-tool\[..]\dev_bundle\server-lib\node_modules

which requires administrative rights. We are working hard to find a decent workaround (look here). Any help and suggestions are welcome.

Compatibility with various node versions

Gagarin should play nicely with node 0.10.x and 0.12.x. On the other hand, there are known compatibility issues with 0.11.x so we don't recommend using that particular version. It only applies to the cli-tool though. Your meteor application will always be run with the node from the development bundle corresponding to your current meteor release. Please keep this in mind if you are using any kind of continuous integration system, because it basically means that the appropriate version of meteor dev-tools will need to be downloaded before the tests can be run.

Breaking changes

Since version 0.4.0 the server object created by meteor() helper no longer has the location property. To make sure the browser starts on the proper location, you need to pass server as the first argument, so

var server = meteor();
var client = browser(server); // before 0.4.0 you would use server.location here

Step-by-step guide

Gagarin is a simple test runner built on top of mocha. Currently it's implemented as a custom mocha interface, which simply extends the standard bdd ui. This may change in the future if there's a demand to support other testing frameworks.

Installation

Gagarin consists of two parts: gagarin npm module and anti:gagarin meteor package. The first one should be installed globally on your system, while the second one should be added to your meteor application. In order to work properly, the versions of the two guys must coincide.

The minimal setup

Please start by installing the cli tool:

npm install -g gagarin

If you try to run gagarin command in your meteor project directory you should receive an error message telling that there are no tests to run. Let's fix it by creating a dummy test in tests/gagarin/ directory.

// tests/gagarin/dummy.js
describe('A dummy test suite', function () {
  it('should do nothing', function () {});
});

This time, everything should work fine and your test should pass. Please note that prior to running the tests scenarios Gagarin builds your application as well. Should the build fail you will be notified accordingly. In case of problems, it's always good to try gagarin --verbose mode for better insight.

Gagarin will always look for your test scenarios in tests/gagarin/ directory. To alter this behavior pass a custom path as the first parameter, e.g.

gagarin path/to/my/tests

For more details see Directory structure and gagarin --help.

What about the anti:gagarin package?

If you forgot to add it manually, the gagarin cli-tool will make sure to add the right version to your project. If the dummy test passed you should notice that indeed the anti:gagarin package is listed in .meteor/packages file.

The role of the smart package is adding some backdoor functionality, similar to meteor shell, for testing purposes. But don't worry - it's only activate when GAGARIN_SETTINGS environment variable is present. For safety, double check it's not there in your production environment.

Directory structure

While we advise to place your tests in tests/gagarin you're free to create a directory structure that fits your needs. Gagarin uses node-glob to find your test files based on a glob pattern.

By default, gagarin assumes you have placed your files inside tests/gagarin. By providing a glob as second argument, more advanced path structures are possible.

Example: tests under tests/gagarin

gagarin

or

gagarin ./tests/gagarin

Example: tests directly under ./tests

  gagarin ./tests

Example: package only structure Let's say you maintain a 'package only' app, and would like to place your tests under the package they are testing. So your app lacks a global tests directory and looks somewhat similar to:

  client
  server
  packages
    blog-acl
      tests
        authorized.js
        guests.js
    blog-comments
      tests
        comments.js

To run all tests found in local packages, you can provide a glob pattern like:

  gagarin ./packages/*/tests/*.js

Or if you have nested folders inside the tests folders:

  gagarin ./packages/*/tests/**/*.js

Example: global tests folder combined with package specific tests We can imagine you're having both global tests, and package specific tests in their own package directory. No problem, just run gagarin with a glob like:

gagarin ./**/tests/**/*.js

Run gagarin *pattern* --verbose if you need to find out witch tests files are being found by your pattern.

Some shells may expand wildcards. This will make gagarin load only the first test file matching the pattern. If you experience this problem, please wrap your pattern within "..." or '...'.

Writing simple tests

The simplest possible test suite may look like this:

describe('Example test suite', function () {
  var server = meteor();
  it('execute should work', function () {
    // return a promise
    return server.execute(function () {
      expect(Meteor.release).not.to.be.empty;
    });
  });
});

In the above example meteor is a global function provided by the framework, which you can use to spawn new meteor instances.For your convenience we've also exposed expect from the good old chai.

Please note that the function passed to the server.execute routine is the only part that is executed within the server environment. The rest of the code is totally external to your application. This technique has a lot of advantages but it also have one major drawback. The functions which are passed to the server do not share their scope with the other ones. In particular, the following code

a = 0;
it('should print the value of a', function () {
  return server.execute(function () {
    console.log(a);
  });
});

will throw an "undefined variable" error. Instead you should pass a as an argument

return server.execute(function (a) {
  console.log(a);
}, [ a ]);

Testing with browser

Gagarin makes it really easy to coordinate tests for client and server. For example

describe('You can also use browser in your tests', function () {
  var server = meteor();
  var client = browser(server);

  it('should work for both client and server', function () {
    return client.execute(function () {
      // some code to execute
    }).then(function () {
      return server.execute(function () {
        // some code to execute on server
      });
    });
  });
});

You can use the browser function to spawn as many clients as you want. The only requirement is that you have a webdriver running somewhere. By default, gagarin will try to find webdriver at port 9515 (chromedriver default). You can customize the webdriver url by providing the corresponding option for the cli tool:

gagarin --webdriver http://localhost:9515

If you're testing locally, we recommend using **c