habitica/test/api

So you want to write API integration tests?

That's great! This README will serve as a quick primer for style conventions and practices for these tests.

What is this?

These are integration tests for the Habitica API. They are performed by making REST requests to the API's endpoints and asserting on the data that is returned.

If the javascript looks weird to you, that's because it's written in ES2015 and transpiled by Babel.

How to run the tests

First, install gulp.

$ npm install -g gulp

To run the api tests, make sure the mongo db is up and running and then type this on the command line:

$ gulp test:api-v2

It may take a little while to get going, since it requires the web server to start up before the tests can run.

You can also run a watch command for the api tests. This will allow the tests to re-run automatically when you make changes in the /test/api/v2/.

$ gulp test:api-v2:watch

One caveat. If you have a severe syntax error in your files, the tests may fail to run, but they won't alert you that they are not running. If you ever find your test hanging for a while, run this to get the stackstrace. Once you've fixed the problem, you can resume running the watch comand.

$ gulp test:api:safe

If you'd like to run the tests individually and inspect the output from the server, in one pane you can run:

$ export PORT=3003; export NODE_DB_URI="mongodb://localhost/habitrpgtest"
$ gulp nodemon

And run your tests in another pane:

$ mocha path/to/file.js

# Mark a test with the `.only` attribute
$ mocha

Structure

Each top level route has it's own directory. So, all the routes that begin with /groups/ live in /test/api/groups/.

Each test should:

• encompase a single route
• begin with the REST parameter for the route
• display the full name of the route, swapping out / for _
• end with test.js

So, for the POST route /groups/:id/leave, it would be

POST-groups_id_leave.test.js

Promises

To mitigate callback hell 👿, we've written helper methods that return promises. This makes it very easy to chain together commands. All you need to do to make a subsequent request is return another promise and then call .then((result) => {}) on the surrounding block, like so:

it('does something', () => { 
  let request;
  return generateUser().then((user) => { // We return the initial promise so this test can be run asyncronously
    request = requester(user);
    return request.post('/groups', {
      type: 'party',
    });
  }).then((party) => { // the result of the promise above is the argument of the function
    return request.put(`/groups/${party._id}`, {
      name: 'My party',
    });
  }).then((result) => {
    return request.get('/groups/party');
  }).then((party) => {
    expect(party.name).to.eql('My party');
  });
});

If the test is simple, you can use the chai-as-promised return expect(somePromise).to.eventually syntax to make your assertion.

it('makes the party creator the leader automatically', () => { 
  let api = requester(user);
  return expect(request.post('/groups', {
    type: 'party',
  })).to.eventually.have.deep.property('leader._id', user._id);
});

If the test is checking that the request returns an error, use the .eventually.be.rejected.and.eql syntax.

it('returns an error', () => { 
  let api = requester(user);
  return expect(request.get('/groups/id-of-a-party-that-user-does-not-belong-to'))
    .to.eventually.be.rejected.and.eql({
      code: 404,
      text: t('messageGroupNotFound'),
    });
});

Questions?

Ask in the Aspiring Coder's Guild!