In the previous article we saw how to test GET transactions in our API. There's still a lot to cover so in this article we are going to be covering how to test POST operations; in other words how to test create.

Perhaps it is time we start POSTing stuff to our app.

Testing POST

Picking from the work we've already laid on the previous articles, let's move on straight into writing our expectations for creating our "post". Let's write our expectations.

First, to keep things simple, we are not doing any validation on the Posts model. You can create empty posts if you like right now, but we really don't care in this article. All we care for is that you send the proper captcha.

In a future article we are going to do validations, but we are going to do it with custom errors and handlers, which is pretty cool actually.

Back to the subject, if you send an invalid captcha, you should get a 400 Bad Request with the message 'Invalid Captcha'. If all is good, you should get a 201 Created, with the recently created post. Let's write our tests then.

// spec/api/functional/PostsSpec.js
describe('Posts endpoint', function(){

  function clear() {
    wolfpack.clearResults();
    wolfpack.clearErrors();
  }

  beforeEach(clear);

  // ... All our previous tests should be here ... //

  describe('POST /posts', function(){
    var stub;
    beforeEach(function(){
      clear();
      stub = sinon.stub(Captcha, 'verifyCaptcha');
      Posts.create.reset();
    });

    afterEach(function(){
      stub.restore();
    });

    it("should return 400 and Invalid captcha if captcha verification fails", function(done){
      stub.returns(false);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(function(res){
          // Verify post was not created
          if (Posts.create.called) { throw Error('Post should have not been created'); }
        })
        .expect(400, {message: 'Invalid captcha'}, done);
    });

    it("should return 201 and the created post", function(done){
      stub.returns(true);
      wolfpack.setCreateResults(fixtures.posts[0]);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(201, fixtures.posts[0], done);
    });
  });

});

Tests seem to increase in complexity from what we saw in the previous article right? Go figures :P Anyway let's analyze the setup.

  describe('POST /posts', function(){
    var stub;
    beforeEach(function(){
      clear();
      stub = sinon.stub(Captcha, 'verifyCaptcha');
      Posts.create.reset();
    });

    afterEach(function(){
      stub.restore();
    });

    // ... Our tests are here ... //
  });

Let's start with the stub. What is that? The Captcha is going to be handled by a service we are going to create called Captcha. This service will have a method called verifyCaptcha that will do all the captcha processing and return either true or false, depending whether it succeeded or not. Obviously we need to test both scenarios so we created a stub for it which will act as the Captcha.verifyCaptcha.

We also need to reset the call counter for Posts.create. Wolfpack kindly enough injected Sinon into the create method so that we can know if it was called, so we must make sure the counter is always reset to 0 when we perform the tests.

And let's not forgot the clear on top that resets any results and errors we've previously set on wolfpack.

For the teardown of the test (the afterEach), we make sure that we restore the stubbed function to its original state.

Let's see the tests now.

    it("should return 400 and Invalid captcha if captcha verification fails", function(done){
      stub.returns(false);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(function(res){
          // Verify post was not created
          if (Posts.create.called) { throw Error('Post should have not been created'); }
        })
        .expect(400, {message: 'Invalid captcha'}, done);
    });

The first thing we do is set our stub for the captcha to return false. That's the stub.returns(false) thing. Afterall, we want to test that the captcha failed, so the method should return false.

Next, we send our request to the server. We POST to /posts, and then send in the body of the request. Again, it is a bad practice to send the fixture as the body. We should type in what we are sending via the POST, and if this changes in the future, we need to update the spec accordingly, just as we did here.

Unlike expectations, which can be placed in a separate file, it is good practice to have the body parameters located where the test is written. This allows for better visibility as to what are the conditions for the test to either fail or pass.

Sending the fixture as the body and the results of an operation can bring problems in the future as it automatically changes an expectation, which should fail in the first place for the change. In fact, in a little bit you are going to see why.

Moving on to the actual test expectations, the first expectation we set with Supertest was to check that if the captcha failed, no post should be created. For that, we are going to check that the spy wolfpack injected into the Posts model's create method was not called in the operation. If it is called, we raise the exception with our own message.

If Posts.create was not called, we can then check that we got the 400 HTTP status, and that we get a JSON with the message Invalid captcha.

Time to account for when the post is created successfully.

    it("should return 201 and the created post", function(done){
      stub.returns(true);
      wolfpack.setCreateResults(fixtures.posts[0]);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(201, fixtures.posts[0], done);
    });

So for starters, we are making our stub for the captcha return true. So basically, our captcha test is passing correctly.

Next, we are setting up the database results Sails is going to get when we create the post. We do that using the global wolfpack.setCreateResults, which will set the same result for all create operations. Since there is only one create operation, no need to worry here. In more complex operations where there is more than one create, we can use additional features of wolfpack that will allow us to test.

Now we make the POST request to the server. This time we don't have anything else we need to keep track like if Posts.create was called, although we can do that. We could also make sure that our stub is actually being called and that the verifyCaptcha operation indeed happened, but I'll let those as a homework for you. So right now we only test that we get the 201 Created, and the post in return. Again, the way I did it here is the bad practice. Do it as I told you to do it.

Let's run the tests and see them fail. Great! They are red! Time to fix that.

First, let's create our Captcha service. Since this is just a demo, I won't really be implementing a Captcha. I'm just gonna create the service and method, and make it fail miserably.

Create a new service under api/services/Captcha.js and paste the following:

// api/services/Captcha.js
module.exports = {  
  verifyCaptcha: function() {
    throw Error('This error means you didn\'t stub the captcha correctly in your tests');
  }
};

Now let's write the code in our controller that will handle the route. The code below is the complete code that is contained within our controller (all route handlers included):

// api/controllers/PostsController.js
module.exports = {

  //.. All the GET stuff from the previous article here ..//

  createPost: function(req, res) {
    var body = {
      title: req.body.title,
      content: req.body.content,
      author: req.body.author
    };
    var valid = Captcha.verifyCaptcha(req.body.captcha);
    if (!valid) {
      return res.json(400, {message: 'Invalid captcha'});
    }

    return Posts.create(body).then(function(post){
      return res.json(201, post);
    }).catch(function(err){
      return res.json(500, err);
    });
  }

};

Noticed the scenario I coded but we are not testing? Yes, the 500 scenario. We are going to test that afterwards. Let's finish with the create first.

Now let's update our routes file. This is the complete route file with all routes included:

// config/routes.js
module.exports.routes = {

  'GET /posts': {
    controller: 'PostsController',
    action: 'getAllPosts'
  },

  'GET /posts/:id': {
    controller: 'PostsController',
    action: 'getPost'
  },

  'POST /posts': {
    controller: 'PostsController',
    action: 'createPost'
  }

};

Now let's run the tests. All green! Yay! Well, no. My dear friend, you just got a bad positive for setting fixtures as results.

The problem lies that in the setup you did (well I actually did it, but you get the point). The 400 test about the captcha is good, but the 201 test for creating the post is a bad positive.

Let's look at the setup of the test. We set the create results with Wolfpack:

wolfpack.setCreateResults(fixtures.posts[0]);  

Wolfpack's setCreateResults is a very powerful method that if used wrong it can bring false positives. Check now your expectation:

.expect(201, fixtures.posts[0], done);

So basically we are telling to expect fixtures.posts[0] === fixtures.posts[0]. The setCreateResults method ignores whatever data you sent in the body. It simply returns the exact data that you told him to return when the create in a model is called.

If you do not provide a setCreateResults, wolfpack will return the data processed through all hooks as if it was stored in the db. Comment the wolfpack.setCreateResults(fixtures.posts[0]) line and run the tests again and see the actual results.

See? We had a false positive because we rewrote the db results and we set the same fixture as the expectation.

This tells us two things. First, our fixture is wrong and is not representing the actual data as it is in the database, so we need to update it, and second, it is a terrible idea to use the fixture as an expectation.

First let's update our fixture with the two missing fields from the db: createdAt and updatedAt. Our posts fixture will now look like this:

// spec/fixtures/posts.js
module.exports = [  
  {
    id: 1,
    title: 'My First Novel',
    content: 'This is my novel. The end.',
    author: 'William Shakespeare',
    createdAt: '2015-11-01T12:00:00.001Z',
    updatedAt: '2015-11-01T12:00:00.001Z'
  },
  {
    id: 2,
    title: 'My first poem',
    content: 'Where is the question mark!"#$%&/()=?',
    author: 'Sappho',
    createdAt: '2015-11-01T12:00:00.002Z',
    updatedAt: '2015-11-01T12:00:00.00Z'
  }
];

By the way, the createdAt and updatedAt are just random dates I picked to make writing the expectation easier.

We also need to update the counters fixtures because they also have createdAt and updatedAt values in the database:

// spec/fixtures/counters.js
module.exports = [  
  {
    id: 1,
    postId: 1,
    count: 3,
    createdAt: '2015-11-01T12:00:00.001Z',
    updatedAt: '2015-11-01T12:00:00.001Z'
  },
  {
    id: 2,
    postId: 2,
    count: 1,
    createdAt: '2015-11-01T12:00:00.002Z',
    updatedAt: '2015-11-01T12:00:00.002Z'
  }
];

Now we need to update our expectations and work them properly. It is a good practice to put the expectation in a separate file, but for this article, I'll just put it within the same test:

    it("should return 201 and the created post", function(done){
      stub.returns(true);
      wolfpack.setCreateResults(fixtures.posts[0]);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(201, {
          id: 1,
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare',
          createdAt: '2015-11-01T12:00:00.001Z',
          updatedAt: '2015-11-01T12:00:00.001Z'
        }, done);
    });

Finally, let's run the tests one more time and see them turn green.

grunt test  

Red? What happened? Of course! Since the fixture changed, our expectation is different. We are now getting updatedAt and createdAt in our GET /posts/:id operation, which is good because it means our tests caught a breaking change.

Go ahead and update that expectation (I'll leave it up to you) and run the tests and watch them turn green.

There you go! Everything is green, including our previous tests! Yeah, I'm not gonna let you go that easily. Did you update the expectation in GET /posts? No? Well that's because you made the expectation the same as the fixture. The moment you changed the fixture, that test should have also break, but it didn't, which means a false positive. Go ahead and fix that so the expectation is not the fixture.

I hope this has been enough to show you why it is very important to have an expectation separate from a fixture. It can save you in the future. It should also have shown you the importance of knowing your data. Wolfpack is very powerful, and if used incorrectly, it can give you false results.

Now, onto testing the error condition.

If you recall, we have a special handler for 500 errors in our controller:

    //.. some code above for our captcha stuff ../
    return Posts.create(body).then(function(post){
      return res.json(201, post);
    }).catch(function(err){
      return res.json(500, err);
    });

So how can we test error an Internal Server error condition? Fortunately, wolfpack provides us with a useful method for mocking errors in the backend called setErrors.

First let's write our new expectation in our tests. We already have the code so we only need the expectation which is basically to show an error message in a specific format if there is any unknown error. Let's write it then:

// spec/api/functional/PostsSpec.js
  describe('POST /posts', function(){
    var stub;
    beforeEach(function(){
      clear();
      stub = sinon.stub(Captcha, 'verifyCaptcha');
      Posts.create.reset();
    });

    afterEach(function(){
      stub.restore();
    });

    // .. all our previous POST tests here ..//

    it("should return 500 and the error message if there is an unknown error", function(done){
      stub.returns(true);
      var errorMessage = 'Some error happened';
      wolfpack.setErrors(errorMessage);

      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(500, {error: errorMessage}, done);
    });

  });

For starters, the error happens in Post.create. Than means we need to get past through the captcha validation first, so we set the stub for the captcha to return true.

Next, we tell wolfpack to return an error for any operation performed. The setErrors method will override any CRUD operation and immediately return an error when a CRUD is called.

Now we perform our call to the server with our expectation. Run it and you will see it will fail because, even though we are getting a 500 error, the message is not the proper format. We need to update it.

So, go back to the PostsController.js, and in the error handler for the create, update the code to the proper format:

// api/controllers/PostsController.js
module.exports = {

  //.. All the GET stuff from the previous article here ..//

  createPost: function(req, res) {
    var body = {
      title: req.body.title,
      content: req.body.content,
      author: req.body.author
    };
    var valid = Captcha.verifyCaptcha(req.body.captcha);
    if (!valid) {
      return res.json(400, {message: 'Invalid captcha'});
    }

    return Posts.create(body).then(function(post){
      return res.json(201, post);
    }).catch(function(err){
      return res.json(500, {error: err.originalError});
    });
  }

};

Now we run our tests again and everything is green. Great! We've achieved better coverage and our api is fully tested, even for when errors happen.

Just for review, this is how the tests for our POST will look like then:

  describe('POST /posts', function(){
    var stub;
    beforeEach(function(){
      clear();
      stub = sinon.stub(Captcha, 'verifyCaptcha');
      Posts.create.reset();
    });

    afterEach(function(){
      stub.restore();
    });

    it("should return 400 and Invalid captcha if captcha verification fails", function(done){
      stub.returns(false);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(function(res){
          // Verify post was not created
          if (Posts.create.called) { throw Error('Post should have not been created'); }
        })
        .expect(400, {message: 'Invalid captcha'}, done);
    });

    it("should return 201 and the created post", function(done){
      stub.returns(true);
      wolfpack.setCreateResults(fixtures.posts[0]);
      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(201, {
          id: 1,
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare',
          createdAt: '2015-11-01T12:00:00.001Z',
          updatedAt: '2015-11-01T12:00:00.001Z'
        }, done);
    });

    it("should return 500 and the error message if there is an unknown error", function(done){
      stub.returns(true);
      var errorMessage = 'Some error happened';
      wolfpack.setErrors(errorMessage);

      request(server)
        .post('/posts')
        .send({
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        })
        .expect(500, {error: errorMessage}, done);
    });
  });

What's next?

We've finished our tests for GET and POST transactions. Still, there are two more common verbs we need to cover: PUT and DELETE. That's what we are going to be seeing in the next article. And after that? Sails Sessions and Policies :)

And remeber, the project for this article is available at:
https://github.com/fdvj/sails-testing-demo

In the previous article we saw a boilerplate setup for functional testing a SailsJS API. In this article, we are going to use that boilerplate to start testing our app.

Time to GET dirty and start testing.

Testing GET transactions

Now that we've setup our test environment, we can proceed and start writing our functional tests for the API. So I'm going to go TDD here (Test Driven Development), and start writing my tests before some of the code.

Remember you can download all the code we are discussing here at https://github.com/fdvj/sails-testing-demo. Just clone the repository and you will be good to go.

With the directory structure I've already defined and explained briefly in the previous post, I'm going to start writing my tests. As you may remember, we created a spec/api/ directory where we are going to put all our tests. Personally, I like to order it even a bit more, and separate my functional tests from my unit tests. So, in the spec/api/ directory, create two new directories: functional and unit. For this article, we are going to be writing our tests in spec/api/functional.

For this article, my application will be composed of only two endpoints which I need to test:

• GET /posts
• GET /posts/:id

In the following articles we will be covering the other common HTTP Verbs (POST, PUT and DELETE).

I've disabled Sails blueprints so that these routes won't get created automatically by Sails.

To keep things simple, the GET /posts should return me a 200 OK with an array of posts in the database. GET /posts/:id should return me a 200 OK with the given post and update a visit counter; if the post does not exist, it should return a 404 error.

Let's start by creating our test in spec/api/functional/PostsSpec.js. In there we will only test the Posts endpoint.

// spec/api/functional/PostsSpec.js
describe('Posts endpoint', function(){

});

The first endpoint we are going to test is the GET /posts endpoint. But first, we need to setup our tests. One important thing we need is to have the "database", in this case wolfpack acting as the db, reset everytime a test run.

The importance of resetting is that we can make sure that we are accurately testing the conditions happening in our test, and prevent data from other tests give us a false positive. To do so, we create a small helper function to reset wolfpack:

// spec/api/functional/PostsSpec.js
describe('Posts endpoint', function(){

  function clear() {
    wolfpack.clearResults();
    wolfpack.clearErrors();
  }

  beforeEach(clear);
});

Before continuing with our testing, I want to set up our models so that I know how will the fixtures look like when I create them. So far our app needs two models: a Posts model which will hold our posts data, and a Counters model which will keep track of how many times a post is viewed.

Our Posts model:

// api/models/Posts.js
module.exports = {

  attributes: {
    title: 'string',
    content: 'string',
    author: 'string'
  }
};

And our Counters model:

// api/models/Counters.js
module.exports = {

  attributes: {
    postId: 'integer',
    count: 'integer',
  }
};

Now that I have a better idea of how my data will look, I can create my fixtures. In spec/fixtures/ create a new file called posts.js and paste the following:

// spec/fixtures/posts.js
module.exports = [  
  {
    id: 1,
    title: 'My First Novel',
    content: 'This is my novel. The end.',
    author: 'William Shakespeare'
  },
  {
    id: 2,
    title: 'My first poem',
    content: 'Where is the question mark!"#$%&/()=?',
    author: 'Sappho'
  }
];

And now for our Counters fixture, create a new file in spec/fixtures/ called counters.js and paste the following:

// spec/fixtures/counters.js
module.exports = [  
  {
    id: 1,
    postId: 1,
    count: 3
  },
  {
    id: 2,
    postId: 2,
    count: 1
  }
];

The fixtures is the data that wolfpack will be returning from the "database". It is not required to use fixtures. If you like, you can also use factories for testing, but for simplicity, in these articles we are going to be using fixtures.

Great! We have our fixtures set up. Now we can do some actual testing and coding!

Our only expectation for GET /posts is for it to return a 200 OK status and an array of posts. So let's write that expectation in spec/api/functional/PostsSpec.js:

// spec/api/functional/PostsSpec.js
describe('Posts endpoint', function(){

  function clear() {
    wolfpack.clearResults();
    wolfpack.clearErrors();
  }

  beforeEach(clear);

  describe('GET /posts', function(){

    it("should return an array of posts", function(done){
      wolfpack.setFindResults(fixtures.posts);

      request(server)
        .get('/posts')
        .expect(200, fixtures.posts, done);
    });

  });

});

Let's back up a little and see what's going on here. The first thing I do is I set up Wolfpack to return the array of posts we have set up in our fixture for every find operation with wolfpack.setFindResults(fixtures.posts). Whatever we look for, Wolfpack will return that array. You can set multiple results depending on certain criteria with wolfpack, but for simplicity, let's just set it for all since we are going to have one find operation.

Next, I tell Supertest to make a call on the server. Remember when we set supertest to global.request and sails.hooks.http.app to global.server? Well, this is were we use them: request(server).

On the same object I tell supertest to connect to the server and make a GET request to /posts: request(server).get('/posts').

Next, I'm telling supertest to expect a 200 code in return, as well as the same array of fixtures I gave wolfpack, which in theory are all our posts in the database. Finally I pass the done callback which gets called when supertest gets the answer, whether its a success or a failure: request(server).get('/posts').expect(200, fixtures.posts, done).

It is important to test all supertest tests as asynchronous tests. These are asynchronous calls to the api. If you don't treat them as asynchronous operations, you can get random results in your test.

Before moving on, I just want to note that it is a bad practice to make the expectation the same as the input of the db, in other words, using the same fixture as the expectation. Tests are to be written so that if something changes that could affect your application, you should know about it when your test breaks. If you change the fixture, your expectation automatically changes, thus you may be unaware of a breaking change introduced into your database or codebase.

The proper way of testing this would be like this:

describe('Posts endpoint', function(){

  function clear() {
    wolfpack.clearResults();
    wolfpack.clearErrors();
  }

  beforeEach(clear);

  describe('GET /posts', function(){

    it("should return an array of posts", function(done){
      wolfpack.setFindResults(fixtures.posts);

      request(server)
        .get('/posts')
        .expect(
            200, 
            [{
                id: 1,
                title: 'My First Novel',
                content: 'This is my novel. The end.',
                author: 'William Shakespeare'
              },
              {
                id: 2,
                title: 'My first poem',
                content: 'Where is the question mark!"#$%&/()=?',
                author: 'Sappho'
             }],
            done);
    });

  });

});

Hard coding the expectation within the test is also not a good practice, but at least it is better. It is best to have the expectation in a separate file (it also serves as good documentation). I put it here because I want to keep the amount of lines and files in the article to a minimum and keep it as clear as possible. So, for the sake of your scrollwheel (and mine), to keep this post as small and readable possible, I will keep using the fixtures (which is the bad practice) in some of the tests.

Now run your tests in your console:

grunt test  

Great, it failed! Obviously! You haven't written any code to make your expectation happen. Let's make our tests pass then.

First things first, let's create our controller and the code we will use for the GET /posts route. We will call it PostsController.js:

// api/controllers/PostsController.js
module.exports = {

  getAllPosts: function(req, res) {
    Posts.find().then(function(posts){
      return res.json(200, posts);
    });
  }    
};

Now let's add our newly created route to our routes file:

// config/routes.js
module.exports.routes = {

  'GET /posts': {
    controller: 'PostsController',
    action: 'getAllPosts'
  }

};

Good. Now let's run the tests again. Type grunt test in your console and hit enter. Let's see the results.

Congratulations! You've just passed your first unit test, TDD style! Now let's move to something more complicated, the GET /posts/:id endpoint.

The GET /posts/:id endpoint has two separate tests we need to run. We need to test that when the post does not exist, it should return a 404. The second test is that, if it exist, it should return a 200, the post itself, and it should call a trigger invisible to the user that updates the counters. Let's see how we can do this.

In the same spec/api/functional/PostsSpec.js we are working on, let's add our new tests:

// spec/api/functional/PostsSpec.js
describe('Posts endpoint', function(){

  function clear() {
    wolfpack.clearResults();
    wolfpack.clearErrors();
  }

  beforeEach(clear);


  // ... The GET /posts tests go here  ...

  describe('GET /posts/:id', function(){
    beforeEach(function(){
      clear();
      Counters.increase.reset();
    });

    it("should return 404 if the post is not found", function(done){
      request(server)
        .get('/posts/1')
        .expect(function(){
          // Make sure the counter is not increased
          if (Counters.increase.called) { throw Error('Counter should have not increased'); }
        })
        .expect(404, done);
    });

    it("should return 200, the post, and increase the visited counter", function(done){
      Posts.setFindResults({id: fixtures.posts[0].id}, fixtures.posts[0]);
      Counters.setFindResults({postId: fixtures.posts[0].id}, fixtures.counters[0]);
      request(server)
        .get('/posts/1')
        .expect(function(res){
          // Verify that the correct counter was increased
          if (!Counters.increase.calledWith(1)) { throw Error('Counter for post should have increased'); }
        })
        .expect(200, {
          id: 1,
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        }, done);
    });

  });

});

Woah! Lots of stuff going on there. What's happening?

Let's start with the setup in the beforeEach. We run the clear function we set up at the beginning to reset wolfpack. Now comes the tricky part.

If you read Wolfpack's documentation, you will see that wolfpack spies on every method in a Sails model. But wait, Counters is a model we created, but we haven't defined any class methods yet! No we haven't, but Im expecting to write a method called increase that will increase the counters for a given post when I call it. Once I write it, Wolfpack will inject Sinon spies into it which will let me know if it was ever called. Problem is, if I don't reset the Sinon's call counter after each test, I may get a false positive on a test. So that's why I'm resetting the call counter for a method I haven't written yet, but I'm expecting to write pretty soon.

Moving on, let's examine this part a little:

    it("should return 404 if the post is not found", function(done){
      request(server)
        .get('/posts/1')
        .expect(function(){
          // Make sure the counter is not increased
          if (Counters.increase.called) { throw Error('Counter should have not increased'); }
        })
        .expect(404, done);
    });

What's going on here? Well, for starters, Supertest allows us to chain multiple expectations for a request. I have two expectations in my test.

First of all, if the post does not exist, obviously it cannot increase the counter, so I kind of created a small unit test here with this expect (which Supertest allows me to test with a function). If the Counters.increase method of the model is called, then my test failed because it shouldn't have.

So to play that scenario, I throw an exception with my own verbose message as to why this test failed. Supertest will catch the exception, and fail the test. In the results, I will then be able to see my verbose message as to why the test failed, in this case, Counter should have not increased.

Next expectation is a 404. Since we are resetting our wolfpack database every time a test is run, the Posts table/collection will be empty, so our code in the controller should be able to handle this an interpret it as a 404.

Now onto the next part of the tests:

    it("should return 200, the post, and increase the visited counter", function(done){
      Posts.setFindResults({id: fixtures.posts[0].id}, fixtures.posts[0]);
      Counters.setFindResults({postId: fixtures.posts[0].id}, fixtures.counters[0]);
      request(server)
        .get('/posts/1')
        .expect(function(res){
          // Verify that the correct counter was increased
          if (!Counters.increase.calledWith(1)) { throw Error('Counter for post should have increased'); }
        })
        .expect(200, {
          id: 1,
          title: 'My First Novel',
          content: 'This is my novel. The end.',
          author: 'William Shakespeare'
        }, done);
    });

We are now testing for when the post exists. First, we set up wolfpack so that it returns a post from the fixtures.

Wait! I don't see we are using wolfpack. We are calling a method setFindResults in the model! Actually, wolfpack injected that method into the model, which is a query method that allows you to tell wolfpack what results it should provide in case the given query is performed.

So the method goes like this:

// Format
Model.setFindResults(condition, results)

// Example
Model.setFindResults({name: 'John'}, {id: 2, name: 'John'})

Model.findOne({name: 'John'}).then(function(user){  
  // user will be {id: 2, name: 'John'}
});

You can read Wolfpack's documentation for more details on query methods.

Back to our code, in our case, when the model asks for Posts with an id of 1 (which is the id of the first fixture), wolfpack will return the data for the first fixture to Sails.

The same happens with the Counters model. Most likely it will look for the entry that keeps track of the counter, in which case we will return the first fixture for the counters.

On the expectations side, first we make the call GET /posts/1 which we expect first to call the Counters.increase method. Here we are also doing a small unit test as we are using Sinon's calledWith method to test that the method Counters.increased was passed a 1, the postId, as the argument. In other words, the app should somewhere in the endpoint call Counters.increase(1). In case this does not happen, it should fail the test with the exception.

Finally, I'm expecting a 200 HTTP status, along with an object identical to what we have as the first post fixture.

Don't forget to pass the done callback at the end so that the test doesn't timeout.

If we now run the tests, they should fail. Good, let's make them green.

First, let's write our methods in the Counters model which increase the count:

// api/models/Counters.js
module.exports = {

  attributes: {
    postId: 'integer',
    count: 'integer',

    increase: function() {
      this.count++;
      return this;
    }
  },

  increase: function(postId) {
    return this.findOne({postId: postId}).then(function(counter){
      return counter.increase().save();
    });
  }
};

As you can see, our model looks for the entry of the post, then increase the count and saves it. Good! Just like we planned for with wolfpack. Now let's write the code in our controller that will handle this route:

// api/controllers/PostsController.js
module.exports = {

  getAllPosts: function(req, res) {
    Posts.find().then(function(posts){
      return res.json(200, posts);
    });
  },

  // This getPost handles the GET /posts/:id route
  getPost: function(req, res) {
    Posts.findOne({id: req.params.id}).then(function(post){
      if (!post) {
        return res.send(404);
      }
      Counters.increase(post.id);
      return res.json(200, post);
    });
  }

};

Just a small review of the code here. First, we find the post with an id given in the url (req.params.id). If it does not exist, return a 404. Otherwise, increase the counter and return a 200 plus the post. Basically what we are expecting.

Let's build the route then.

// config/routes.js
module.exports.routes = {

  'GET /posts': {
    controller: 'PostsController',
    action: 'getAllPosts'
  },

  'GET /posts/:id': {
    controller: 'PostsController',
    action: 'getPost'
  }

};

Great! Our shiny new route is ready to be tested. Let's run those tests and watch them turn green.

grunt test  

Beautiful! Our tests all return green. Now when we refactor or add a new feature and break something, we'll know for sure.

What's next?

In this article we saw how we can test GET transactions in our API. There are still three other verbs we need to cover: POST, PUT and DELETE. In the next article we are going to cover how to test POST transactions in your API. Let's move on then.

Functional Testing a SailsJS API with Wolfpack: Part 3

SailsJS is a popular MVC framework for NodeJS. It is widely used due to its ease of use. However, the official Sails documentation on testing is pretty basic and ambiguous, so a lot of people is left to wonder how to properly test a Sails app.

Learn how to functionally test your SailsJS API using Wolfpack and Supertest.

In this first part of the series, we are going to see the basic setup I use to functional test an API with Wolfpack.

I've uploaded to my Github the boilerplate and article samples I'm going to present below. You can checkout the repo here.

A small intro

When I started working with Sails, I found myself in the situation that I wasn't completely sure on how to test a Sails application. In the simplest terms, the documentation said to lift the Sails application and do the testing with my favorite framework.

I didn't like testing against a database. Too much work involved. For GET transactions, I have to make sure that the database has the proper entries to do the tests well. I also had to make sure my teardown was done correctly, otherwise I could get false positives, or my db could grow really big. I wasn't a fan of that idea.

Looking around, I couldn't find any good docs or plugins that could let me avoid the hassle of testing my models against a db, so I decided to write my own. An thus Wolfpack was created.

What is Wolfpack?

Wolfpack is a database driver, like any other db driver (connector as they are really called) for Sails. The major difference is that Wolfpack does not persist the data; everything is stored in variables which disappear once the tests are done.

Wolfpack is also a testing helper. It basically injects itself into a Sails (Waterline) model you provide and spies upon every method in that model. It allows you to mock results that will usually be sent by a database, as well as mock errors that may happen so you can also test error scenarios in realtime.

Overall, Wolfpack lets you mock the results coming from your models, on a case-by-case basis, giving you a fair amount of control on how to run the tests on your app. Let's get to business.

Requirements

For this entire series, I'm assuming you know your way around a Sails project. I'm also assuming you've done test driven development, or at least wrote tests in the past using mocha or jasmine.

On the Sails side, I'm assuming you've disabled Sails default blueprints, which basically create "magic" routes and controllers for our models. If you don't disable blueprints, some of the steps described in this article may not perform as expected.

Setting up the test environment

This first part is all about readying up our environment for proper testing. Let's get to business then.

The following is my boilerplate test environment for a SailsJS application. I use Mocha, Chai and Supertest for my tests. Chai is best suited for Unit testing a Sails application. For functional testing an API, I prefer to use Supertest as it allows me to create a session and easily test HTTP verbs against my API.

From the boilerplate below, you are going to notice I'm setting up stuff I will not be using in this article (coverage and assertion libraries for example), since I'm going to be doing only functional testing. However, you will notice there are some scenarios in which a unit test is better suited. My setup allows me to do both unit and functional testing with ease.

I'll start by assuming you've already setup your Sails project using the Sails client tool and the directory structure is all setup correctly. This is important because my setup uses some tasks already implemented by the Sails team.

First things first, let's make sure we have Grunt installed globally. Type in grunt -v. If you get an error, then install Grunt globally like this:

npm install -g grunt-cli  

It is extremely important to have Grunt installed as the setup I'm using below uses Grunt for almost everything. If you prefer, you can use Gulp as well, but you'll need to tweak some stuff to get my setup working in Gulp.

Also, please note that Sails uses grunt by default, so you may also need to change some tasks there if you prefer to use Gulp or other task runner.

Now that we have Grunt installed, let's install our dev dependencies:

npm install --save-dev blanket chai grunt-blanket grunt-mocha-test mocha sinon supertest wolfpack  

There's an additional dependency I install, and that is Lodash. Lodash is a utility library like Underscore, but with a lot more methods and (arguably) better performance. You can use Underscore if you prefer, but just bear in mind you'll need to change the lodash into underscore in the code.

npm install --save lodash  

Now here comes the boiler plate stuff. Let's start by modifying some of Sails grunt tasks and create our own tasks as well.

In your root application folder, open the tasks/config/clean.js file, and add a new task called coverage. Right now we won't deal with code coverage, but in a future article we will, and since this is a boilerplate, lets leave it like that. Your clean.js file should look something like this:

// tasks/config/clean.js
module.exports = function(grunt) {

  grunt.config.set('clean', {
    dev: ['.tmp/public/**'],
    build: ['www'],
    coverage: {
      src: ['coverage/**']
    }
  });

  grunt.loadNpmTasks('grunt-contrib-clean');
};

Next, create a new file in tasks/config/ and call it blanket.js, and paste the following:

// tasks/config/blanket.js
module.exports = function(grunt) {

  grunt.config.set('blanket', {
    coverage: {
      src: ['api/'],
      dest: 'coverage/api/'
    }
  });

  grunt.loadNpmTasks('grunt-blanket');

};

Moving on, open tasks/config/copy.js and add a coverage task as well. The file should look like the one below:

// tasks/config/copy.js
module.exports = function(grunt) {

    grunt.config.set('copy', {
        dev: {
            files: [{
                expand: true,
                cwd: './assets',
                src: ['**/*.!(coffee|less)'],
                dest: '.tmp/public'
            }]
        },
        build: {
            files: [{
                expand: true,
                cwd: '.tmp/public',
                src: ['**/*'],
                dest: 'www'
            }]
        },
        coverage: {
            src: ['spec/api/**'],
            dest: 'coverage/'
        }
    });

    grunt.loadNpmTasks('grunt-contrib-copy');
};

Great! Now let's setup our test runner task. Create a new file called test.js under tasks/config/ and put the following:

// tasks/config/test.js
module.exports = function(grunt) {

  grunt.config.set('mochaTest', {
    test: {
      options: {
        reporter: 'spec'
      },
      src: ['spec/helpers/**/*.js', 'coverage/spec/api/**/*.js']
    },
    coverage: {
      options: {
        reporter: 'html-cov',
        quiet: true,
        captureFile: 'coverage.html'
      },
      src: ['coverage/spec/api/**/*.js']
    }
  });

  grunt.loadNpmTasks('grunt-mocha-test');

};

Excellent! We are almost done setting up our test runner. Now we need to register a test task with grunt so that we can run the tests. Under the tasks/register/ folder, create a new file called test.js and add the following:

// config/register/test.js
module.exports = function(grunt) {

  grunt.registerTask('test', 'Run tests and code coverage report.', ['clean:coverage', 'blanket', 'copy:coverage', 'mochaTest', 'clean:coverage']);

};

After all this, we need to verify our task is setup correctly. To do so, simply type grunt --help and look for our task at the bottom. If it shows, we are almost set up. If not, check the files we've just added and modified for anything missing (perhaps a pesky semicolon).

Now it is time to set our test helpers which will initiate Sails and provide us with the assertion libraries. But in order to do so, we need to set up the directory structure for our tests.

On a sidenote, when I created Wolfpack, I did it with the intention not to ever have to lift Sails for testing. However, since I'm doing functional testing against endpoints, it is for the best to run the application, that means lifting Sails, so that we can do a proper testing of the API.

The root of your Sails application should have several folders like api, assets, config, etc. In the root of our project, we are going to create a new folder called spec. You can name this folder differently if you prefer, however, if you do so, don't forget to update the paths in the grunt task files we've created and modified before.

Please note that this is how I setup my directory for the tests. You don't need to follow the same structure I do, but for the purpose of this article, please do so.

Within the spec/ folder, I'm going to create three additional folders: api, fixtures, and helpers. spec/api/ is where I put all my tests, spec/fixtures/ is where I put my fixtures for wolfpack to use, and spec/helpers/ is where I put any test helpers I need, including sails test helpers as we will soon see.

Let's start by setting up our Sails helper. In spec/helpers/ create a new file called sails.js and paste the following:

// spec/helpers/sails.js
var Sails = require('sails'),  
    _ = require('lodash'),
    wolfpack = require('wolfpack'),
    fs = require('fs'),
    sails;

global.wolfpack = wolfpack;

before(function(done) {

  // Increase the Mocha timeout so that Sails has enough time to lift.
  this.timeout(30000);

  Sails.lift({
    // configuration for testing purposes
    log: {level: 'silent'}
  }, function(err, server) {
    sails = server;
    if (err) return done(err);

    // Lookup models for wolpack injection
    var files = _.filter(fs.readdirSync(process.cwd() + '/api/models/'), function(file){
      return /\.js$/.test(file);
    });

    // Inject wolfpack into files
    _.each(files, function(file){
      file = file.replace(/\.js$/, '');
      var spied = wolfpack(process.cwd() + '/api/models/' + file);
      global[file] = spied;
      sails.models[file.toLowerCase()] = spied;
    });

    // Set hook path so its easier to call in tests
    global.server = sails.hooks.http.app;

    done(err, sails);
  });
});

after(function(done) {  
  // here you can clear fixtures, etc.
  Sails.lower(done);
});

Couple of things to note here. First, as you may notice, one of the first things I do is to set Mocha's timeout to 30 seconds (30000 milliseconds). This is because sometimes Sails takes a lot of time to lift, more than the 5 second default timeout for asynchronous operations set by Mocha. With the 30 second limit, I give ample time for Sails to finish loading before I start running the tests.

No worries, the 30 second limit just applies to the lifting. The rest of the app still has a 5 second timeout.

Once Sails loads, I start injecting wolfpack into all models loaded by the application. This will allow me to set the fixtures for the tests without having to start wolfpack individually in each model.

Im also exposing two global variables: wolfpack, which contains the wolfpack instance, and a server, which is basically a shortname for the sails app hook I'm going to be using in our Supertest tests.

Finally, the after hook makes sure we correctly lower Sails once the tests are run, so that we don't leave it hanging occupying the port used for testing.

Next, create a file under spec/helpers/ called libraries.js and paste the following:

// spec/helpers/libraries.js
var chai = require('chai'),  
    fs = require('fs');

chai.config.includeStack = true;

global.expect = chai.expect;  
global.AssertionError = chai.AssertionError;  
global.Assertion = chai.Assertion;  
global.assert = chai.assert;

global.sinon = require('sinon');

global.request = require('supertest');

global._ = require('lodash');

// Load fixtures
global.fixtures = {};

_.each(fs.readdirSync(process.cwd() + '/spec/fixtures/'), function(file){  
  global.fixtures[file.replace(/\.js$/, '').toLowerCase()] = require(process.cwd() + '/spec/fixtures/' + file);
});

What the libraries.js file does is it loads Chai's assertion methods and puts them in the global scope so they can easily be accessed in the tests. However, since in this series I'm functional testing and not unit testing, I will be using Supertest assertion's rather than Chai's.

As you can see as well, I'm loading SinonJS (which is a spy/stub library) and put it in the global scope for easy accessibility, as well as Supertest, which I put in the request global variable, and I also load lodash in the global scope.

Finally, I also load all files within the fixtures folder and load them into the global object fixtures. This way I preload all fixtures into the tests and to call them I simply need to input the name of the fixture file, without the posterior .js, to be able to access them.

We are now done setting up our testing environment.

What's next?

Well, testing of course! In the next part of this series we are going to start testing our API as any client out there will consume it. Let's move on to the next part then.

Functional Testing a SailsJS API with Wolfpack: Part 2