title: Unit Testing

Why Unit Testing

Let us start with a few questions:

How to measure the quality of code
How to ensure the quality of code
Are you free to refactor code
How to guarantee the correctness of refactored code
Have you confidence to release your untested code

If you are not sure, you probably need unit testing.

Actually, it brings us tremendous benefits:

ensurance of maintaining code quality
correct refactoring
enhanced confidence
automation

It's more important to use unit tests in a web application during the fast iteration, because each testing case can contribute to the increasing stability of the application. The result of various inputs in each test is definite, so it's obvious to detect whether the changed code has an impact on correctness or not.

Therefore, code, such as in Controller, Service, Helper, Extend and so on, require corresponding unit testing for quality assurances, especially modification of the framework or plugins, of which test coverage is strongly recommended to be 100%.

Test Framework

When searching 'test framework' in npm, there are a mass of test frameworks owning their own unique characteristics.

Mocha

Mocha is our first choice.

Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases.

AVA

Why not another recently popular framework AVA which looks like faster? AVA is great, but practice of serveral projects tells us the truth that code is harder to write.

Comments from @dead-horse:

AVA is not stable enough, for example, CPU capacity is going to be overloaded when plenty of files are running concurrently. The solution of setting parameter controlling concurrent could work, but 'only mode' would be not functioning any more.

Running cases concurrently makes great demands on implementation, because each test has to be independent, especially containing mock.

Considering the expensive initialization of app, it's irrational of AVA to execute each file in an independent process initializing their own app while serial framework does only one time.

Comments from @fool2fish：

It's faster to use AVA in simple application(maybe too simple to judge). But it's not recommended to use in complicate one because of its considerable flaws, such as incapability of offering accurate error stacks; meanwhile, concurrency may cause service relying on other test settings to hang up which reduces the success rate of the test. Therefore, process testing, for example, CRUD operations of database, should not use AVA.

Assertion Library

Assertion libraries, as flourishing as test frameworks, are emerged continuously. The one we used has changed from assert to should, and then to expect , but we are still trying to find better one.

In the end, we go back to the original assertion library because of the appearance of power-assert, which best expresses 『No API is the best API』.

To be Short, Here are it's advantages:

No API is the best API. Assert is all.
** powerful failure message **
** powerful failure message **
** powerful failure message **

You may intentionally make mistakes in order to see these failure messages.

Test Rule

Framework defines some fundamental rules on unit testing to keep us forcus on coding rather than assistant work, such as how to execute test cases.

Directory Structure

Test code is demand to be put in test directory, include fixtures and assistant scripts.

Each Test file has to be named by the pattern of ${filename}.test.js, ending with .test.js.

For example:

test
├── controller
│   └── home.test.js
├── hello.test.js
└── service
    └── user.test.js

Test Tool

Consistently using egg-bin to launch tests , which automaticlly load modules like Mocha, co-mocha, power-assert, nyc into test scripts, so that we can concentrate on writing tests without wasting time on the choice of various test tools or modules.

The only thing you need to do is setting scripts.test in package.json.

{
  "scripts": {
    "test": "egg-bin test"
  }
}

Then tests would be launched by executing npm test command.

npm test

> unittest-example@ test /Users/mk2/git/github.com/eggjs/examples/unittest
> egg-bin test

  test/hello.test.js
    ✓ should work

  1 passing (10ms)

Test Preparation

This chapter introduces you how to write test, and introduction of tests for the framework and plugins are located in framework and plugin.

mock

Generally, a complete application test requires initialization and cleanup, such as deleting temporary files or destroy application. Also, we have to deal with exceptional situations like network problem and inaccessible of server.

We extracted an egg-mockmodule for mock, help for quick implementation of application unit tests, supporting fast creation of ctx to test.

app

Before lauching, we have to create an instance of App to test code of application-level like Controller, Middleware or Service.

We can easily create one at Mocha's hook, before, through egg-mock.

// test/controller/home.test.js
const assert = require('assert');
const mock = require('egg-mock');

describe('test/controller/home.test.js', () => {
  let app;
  before(() => {
    // create an current app instance
    app = mock.app();
    // execute tests after app is ready
    return app.ready();
  });
});

Now, we have an app instance, and it's the base of all the following tests. See more about app at mock.app(options).

It's redundancy to create an instance in each test file, so we offered an bootstrap file in egg-mock to create it conveniently.

// test/controller/home.test.js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/controller/home.test.js', () => {
  // test cases
});

ctx

Except app, tests for Extend, Service and Helper are also taken into consideration. Let's ceate a context through app.mockContext(options) offered by egg-mock.

it('should get a ctx', () => {
  const ctx = app.mockContext();
  assert(ctx.method === 'GET');
  assert(ctx.url === '/');
});

To mock data on context is also supported.

it('should mock ctx.user', () => {
  const ctx = app.mockContext({
    user: {
      name: 'fengmk2',
    },
  });
  assert(ctx.user);
  assert(ctx.user.name === 'fengmk2');
});

Since we have got the app and the context, you are free to do a lot of tests.

Testing Order

Pay close attention to testing order, and make sure any chunk of code is executed as you expected.

Common Error:

// Bad
const { app } = require('egg-mock/bootstrap');

describe('bad test', () => {
  doSomethingBefore();

  it('should redirect', () => {
    return app.httpRequest()
      .get('/')
      .expect(302);
  });
});

Mocha is going to load all the code in the beginning, which means doSomethingBefore would be invoked before execution. It's not expected when especially using 'only' to specify the test.

It's supposed to locate in a before hook in the suite of a particular test case.

// Good
const { app } = require('egg-mock/bootstrap');

describe('good test', () => {
  before(() => doSomethingBefore());

  it('should redirect', () => {
    return app.httpRequest()
      .get('/')
      .expect(302);
  });
});

Mocha have keywords - before, after, beforeEach and afterEach - to set up preconditions and clean-up after your tests. These keywords could be multiple and execute in strict order.

Asynchronous Test

egg-bin support asynchronous test:

// using Promise
it('should redirect', () => {
  return app.httpRequest()
    .get('/')
    .expect(302);
});

// using callback
it('should redirect', done => {
  app.httpRequest()
    .get('/')
    .expect(302, done);
});

// using async
it('should redirect', async () => {
  await app.httpRequest()
    .get('/')
    .expect(302);
});

According to specific situation, you could make different choice of these ways. Multiple asynchronous test cases could be composed to one test with async function, or divided into several independent tests.

Controller Test

It's the tough part of all application tests, since it's closely related to router configuration. app.httpRequest() returns actually an instance of SuperTest, which connects Router and Controller, using to load a real request. It could also help us to examine param verification of Router by loading boundary conditions.

Here is an app/controller/home.js example.

// app/router.js
module.exports = app => {
  const { router, controller } = app;
  router.get('homepage', '/', controller.home.index);
};

// app/controller/home.js
class HomeController extends Controler {
  async index() {
    this.ctx.body = 'hello world';
  }
}

Then a test.

// test/controller/home.test.js
const { app, mock, assert } = require('egg-mock/bootstrap');

describe('test/controller/home.test.js', () => {
  describe('GET /', () => {
    it('should status 200 and get the body', () => {
      // load `GET /` request
      return app.httpRequest()
        .get('/')
        .expect(200) // set expectaion of status to 200
        .expect('hello world'); // set expectaion of body to 'hello world'
    });

    it('should send multi requests', async () => {
      await app.httpRequest()
        .get('/')
        .expect(200) v
        .expect('hello world'); // set expectaion of body to 'hello world'

      // once more
      const result = await app.httpRequest()
        .get('/')
        .expect(200)
        .expect('hello world');

      // varify via assert
      assert(result.status === 200);
    });
  });
});

app.httpRequest based on SuperTest supports a majority of HTTP methods, and it provides rich interfaces to construct request, such as a JSON POST request.

// app/controller/home.js
class HomeController extends Controler {
  async post() {
    this.ctx.body = this.ctx.request.body;
  }
}

// test/controller/home.test.js
it('should status 200 and get the request body', () => {
  // mock CSRF token，explain later
  app.mockCsrf();
  return app.httpRequest()
    .post('/post')
    .type('form')
    .send({
      foo: 'bar',
    })
    .expect(200)
    .expect({
      foo: 'bar',
    });
});

See details at SuperTest Document。

mock CSRF

The security plugin of framework would enable CSRF prevention as default. Typically, tests have to precede with a request of page in order to parse CSRF token from the response, and then use the token in later POST requests. But egg-mock provides the app.mockCsrf() function to skip the verifiation of the CSRF token of requests sent by SuperTest.

app.mockCsrf();
return app.httpRequest()
  .post('/post')
  .type('form')
  .send({
    foo: 'bar',
  })
  .expect(200)
  .expect({
    foo: 'bar',
  });

Service Test

Service is easier to test than Controller. Creating a ctx, and then get the instance of Service via ctx.service.${serviceName}, and then use the instance to test.

For example:

// app/service/user.js
class UserService extends Service {
  async get(name) {
    return await userDatabase.get(name);
  }
}

And a test:

describe('get()', () => {
  // using generator function because of asynchronous invoking
  it('should get exists user', async () => {
    // create ctx
    const ctx = app.mockContext();
    // get service.user via ctx
    const user = await ctx.service.user.get('fengmk2');
    assert(user);
    assert(user.name === 'fengmk2');
  });

  it('should get null when user not exists', async () => {
    const ctx = app.mockContext();
    const user = await ctx.service.user.get('fengmk1');
    assert(!user);
  });
});

Of cause it's just a sample, acutal code would probably be more complicated.

Extend Test

It's extendable of Application, Request, Response and Context as well as Helper, and we are able to write specific test cases for extended functions or properties.

Application

When an app instance is created by egg-mock, the extended functions and properties are already available on the instance and can be tested directly.

For example, we extend the application in app/extend/application to support cache based on ylru.

const LRU = Symbol('Application#lru');
const LRUCache = require('ylru');
module.exports = {
  get lru() {
    if (!this[LRU]) {
      this[LRU] = new LRUCache(1000);
    }
    return this[LRU];
  },
};

A corresponding test:

describe('get lru', () => {
  it('should get a lru and it work', () => {
    // set cache
    app.lru.set('foo', 'bar');
    // get cache
    assert(app.lru.get('foo') === 'bar');
  });
});

As you can see, it's easy.

Context

Compared to Application, you need only one more step for Context tests, which is to create an Context instance via app.mockContext.

Such as adding a property named isXHR to app/extend/context.js to present whether or not the request was submitted via XMLHttpRequest.

module.exports = {
  get isXHR() {
    return this.get('X-Requested-With') === 'XMLHttpRequest';
  },
};

A corresponding test:

describe('isXHR()', () => {
  it('should true', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'XMLHttpRequest',
      },
    });
    assert(ctx.isXHR === true);
  });

  it('should false', () => {
    const ctx = app.mockContext({
      headers: {
        'X-Requested-With': 'SuperAgent',
      },
    });
    assert(ctx.isXHR === false);
  });
});

Request

Extended properties and function are available on ctx.request, so they can be tested directly.

For example, provide a isChrome property to app/extend/request.js to varify requests whether they are from Chrome or not.

const IS_CHROME = Symbol('Request#isChrome');
module.exports = {
  get isChrome() {
    if (!this[IS_CHROME]) {
      const ua = this.get('User-Agent').toLowerCase();
      this[IS_CHROME] = ua.includes('chrome/');
    }
    return this[IS_CHROME];
  },
};

A corresponding test:

describe('isChrome()', () => {
  it('should true', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'Chrome/56.0.2924.51',
      },
    });
    assert(ctx.request.isChrome === true);
  });

  it('should false', () => {
    const ctx = app.mockContext({
      headers: {
        'User-Agent': 'FireFox/1',
      },
    });
    assert(ctx.request.isChrome === false);
  });
});

Response

Identical with Request, Response test could be based on ctx.reponse directly, accessing all the extended functions and properties.

For example, provide an isSuccess property to indicate current status code equal to 200 or not.

module.exports = {
  get isSuccess() {
    return this.status === 200;
  },
};

The corresponding test:

describe('isSuccess()', () => {
  it('should true', () => {
    const ctx = app.mockContext();
    ctx.status = 200;
    assert(ctx.response.isSuccess === true);
  });

  it('should false', () => {
    const ctx = app.mockContext();
    ctx.status = 404;
    assert(ctx.response.isSuccess === false);
  });
});

Helper

Similiar to Service, Helper is avaliable on ctx, which can be tested directly.

Such as app/helper/format.js:

module.exports = {
  money(val) {
    const lang = this.ctx.get('Accept-Language');
    if (lang.includes('zh-CN')) {
      return `￥ ${val}`;
    }
    return `$ ${val}`;
  },
};

A corresponding test:

describe('money()', () => {
  it('should RMB', () => {
    const ctx = app.mockContext({
      // mock headers of ctx
      headers: {
        'Accept-Language': 'zh-CN,zh;q=0.5',
      },
    });
    assert(ctx.helper.money(100) === '￥ 100');
  });

  it('should US Dolar', () => {
    const ctx = app.mockContext();
    assert(ctx.helper.money(100) === '$ 100');
  });
});

Mock Function

Except functions mentioned above, like app.mockContext() and app.mockCsrf(), egg-mock provides quite a few mocking functions to make writing tests easier.

To prevent console logs through mock.consoleLevel('NONE')
To mock session data through app.mockSession(data)

describe('GET /session', () => {
  it('should mock session work', () => {
    app.mockSession({
      foo: 'bar',
      uid: 123,
    });
    return app.httpRequest()
      .get('/session')
      .expect(200)
      .expect({
        session: {
          foo: 'bar',
          uid: 123,
        },
      });
  });
});

Remember to restore mock data in an afterEach hook, otherwise it would take effect with all the tests that supposed to be independent to each other.

describe('some test', () => {
  // before hook

  afterEach(mock.restore);

  // it tests
});

When you use egg-mock/bootstrap, resetting work would be done automaticly in an afterEach hook. Do need to write these code any more.

The following will describe the common usage of egg-mock.

Mock Properties And Functions

Egg-mock extended from mm moudle contains full features of it, so we can directly mock any objects' properties and functions.

Mock Properties

Mock app.config.baseDir to return a given value - /tmp/mockapp.

mock(app.config, 'baseDir', '/tmp/mockapp');
assert(app.config.baseDir === '/tmp/mockapp');

Mock Functions

Mock fs.readFileSync to return a given function.

mock(fs, 'readFileSync', filename => {
  return 'hello world';
});
assert(fs.readFileSync('foo.txt') === 'hello world');

See more detail in mm API, include advanced usage like mock.data()，mock.error() and so on.

Mock Service

Service, a standard built-in member of the framework, is offered a specialized function to conveniently mock its result, which is app.mockService(service, methodName, fn).

For example, mock the method get(name) in app/service/user to return a nonexistent user.

it('should mock fengmk1 exists', () => {
  app.mockService('user', 'get', () => {
    return {
      name: 'fengmk1',
    };
  });

  return app.httpRequest()
    .get('/user?name=fengmk1')
    .expect(200)
    // return an originally nonexistent user
    .expect({
      name: 'fengmk1',
    });
});

Using app.mockServiceError(service, methodName, error) to mock exception.

For example, mock the method get(name) in app/service/user to throw an exception.

it('should mock service error', () => {
  app.mockServiceError('user', 'get', 'mock user service error');
  return app.httpRequest()
    .get('/user?name=fengmk2')
    // service exception causing the 500 status code
    .expect(500)
    .expect(/mock user service error/);
});

Mock HttpClient

External HTTP requests should be performed though HttpClient, a built-in member of Egg, and app.mockHttpclient(url, method, data) is able to simulate various network exceptions of requests performed by app.curl and ctx.curl.

For example, we submit a request in app/controller/home.js.

class HomeController extends Controller {
  async httpclient () {
    const res = await this.ctx.curl('https://eggjs.org');
    this.ctx.body = res.data.toString();
  }
}

Then mock it's response.

describe('GET /httpclient', () => {
  it('should mock httpclient response', () => {
    app.mockHttpclient('https://eggjs.org', {
      // parameter allowed to be a buffer / string / json,
      // will be finally converted to buffer
      // according to options.dataType
      data: 'mock eggjs.org response',
    });
    return app.httpRequest()
      .get('/httpclient')
      .expect('mock eggjs.org response');
  });
});

Sample Code

All sample code can be found in eggjs/exmaples/unittest

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

unittest.md

unittest.md

title: Unit Testing

Why Unit Testing

Test Framework

Mocha

AVA

Assertion Library

Test Rule

Directory Structure

Test Tool

Test Preparation

mock

app

ctx

Testing Order

Asynchronous Test

Controller Test

mock CSRF

Service Test

Extend Test

Application

Context

Request

Response

Helper

Mock Function

Mock Properties And Functions

Mock Properties

Mock Functions

Mock Service

Mock HttpClient

Sample Code

Files

unittest.md

Latest commit

History

unittest.md

File metadata and controls

title: Unit Testing

Why Unit Testing

Test Framework

Mocha

AVA

Assertion Library

Test Rule

Directory Structure

Test Tool

Test Preparation

mock

app

ctx

Testing Order

Asynchronous Test

Controller Test

mock CSRF

Service Test

Extend Test

Application

Context

Request

Response

Helper

Mock Function

Mock Properties And Functions

Mock Properties

Mock Functions

Mock Service

Mock HttpClient

Sample Code