Integration tests in Node.js with Mocha/Chai

# Mastering API Testing with Mocha and Chai: A Comprehensive Guide for Backends

In the realm of backend development, the reliability and robustness of APIs are fundamental pillars. Ensuring your endpoints respond correctly, even under adverse conditions, is a task that demands attention and the right tools. This article delves into the world of automated testing, focusing on how to set up and utilize Mocha and Chai, two powerful and widely adopted libraries in the Node.js ecosystem, for testing your API endpoints. We'll also cover essential strategies for setting up and tearing down testing environments, ensuring your tests are isolated, repeatable, and reliable.

The Importance of API Testing

APIs are the backbone of communication between different systems and services. A faulty API can lead to data inconsistencies, service disruptions, and a frustrating experience for the end-user. Automated API tests allow us to:

• Detect Bugs Early: Identify issues in business logic, input validation, and error handling before they reach production.
• Ensure Consistency: Guarantee that API responses remain predictable and correct over time, especially after refactoring or new implementations.
• Facilitate Refactoring: Provide a safety net that allows you to modify code with confidence, knowing that tests will indicate if something has been broken.
• Document Behavior: Tests serve as a form of executable documentation, demonstrating how the API is expected to behave.

Setting Up the Test Environment: Mocha and Chai

Mocha is a flexible JavaScript testing framework that runs on Node.js and in the browser, enabling asynchronous testing and detailed test reports. Chai is an assertion library that can be used with Mocha, offering an expressive syntax for verifying that your test results meet expectations.

Installation

First, let's initialize a Node.js project (if you don't have one already) and install Mocha and Chai as development dependencies:

npm init -y
npm install --save-dev mocha chai @types/mocha @types/chai ts-node typescript

We'll also need to configure TypeScript for our project. Create a tsconfig.json file in the project's root with the following content:

{
  \"compilerOptions\": {
    \"target\": \"ES2016\",
    \"module\": \"CommonJS\",
    \"outDir\": \"./dist\",
    \"rootDir\": \"./src\",
    \"strict\": true,
    \"esModuleInterop\": true,
    \"skipLibCheck\": true,
    \"forceConsistentCasingInFileNames\": true,
    \"moduleResolution\": \"node\",
    \"types\": [\"mocha\", \"chai\"]
  },
  \"include\": [\"src/**/*.ts\"],
  \"exclude\": [\"node_modules\"]
}

Now, let's create a src directory for our code and a test subdirectory for our tests.

Directory Structure

my-api-project/
├── src/
│   └── server.ts         # Your server code
├── test/
│   └── api.test.ts       # Your API tests
├── tsconfig.json
├── package.json
└── node_modules/

Configuring Mocha

You can configure Mocha via a mocha.opts file in the test/ directory or directly in your package.json. For this guide, we'll use package.json. Add the following script:

// package.json
\"scripts\": {
  \"test\": \"mocha -r ts-node/register src/test/**/*.ts"
}

This script instructs Mocha to use ts-node to transpile and execute the TypeScript files in the src/test/ folder.

Testing API Endpoints

Let's assume we have a simple Express server with a /users endpoint that returns a list of users.

Server Example (src/server.ts)

import express, { Request, Response } from 'express';

const app = express();
const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;

// Middleware to parse JSON
app.use(express.json());

// Sample data
let users = [
  { id: 1, name: 'Alice', email: '[e-mail]' },
  { id: 2, name: 'Bob', email: '[e-mail]' },
];

// GET /users endpoint
app.get('/users', (req: Request, res: Response) => {
  res.status(200).json(users);
});

// POST /users endpoint
app.post('/users', (req: Request, res: Response) => {
  const newUser = req.body;
  if (!newUser.name || !newUser.email) {
    return res.status(400).json({ message: 'Name and email are required' });
  }
  const id = users.length > 0 ? Math.max(...users.map(u => u.id)) + 1 : 1;
  users.push({ ...newUser, id });
  res.status(201).json({ ...newUser, id });
});

// GET /users/:id endpoint
app.get('/users/:id', (req: Request, res: Response) => {
    const id = parseInt(req.params.id, 10);
    const user = users.find(u => u.id === id);
    if (user) {
        res.status(200).json(user);
    } else {
        res.status(404).json({ message: 'User not found' });
    }
});

// DELETE /users/:id endpoint
app.delete('/users/:id', (req: Request, res: Response) => {
    const id = parseInt(req.params.id, 10);
    const initialLength = users.length;
    users = users.filter(u => u.id !== id);
    if (users.length < initialLength) {
        res.status(204).send(); // No Content
    } else {
        res.status(404).json({ message: 'User not found' });
    }
});

const server = app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

export { app, server }; // Export app and server for testing

Test Example (src/test/api.test.ts)

To interact with our API in tests, we'll use the supertest library, which provides a high-level HTTP wrapper for testing frameworks like Mocha.

npm install --save-dev supertest

Now, let's write the tests:

// src/test/api.test.ts
import chai from 'chai';
import chaiHttp from 'chai-http';
import { app, server } from '../server'; // Import the Express app and server instance

// Configure chai to use chai-http
chai.use(chaiHttp);

const expect = chai.expect;

describe('API User Endpoints', () => {
  // Global variables for the describe block
  let request: chai.SuperTest<chai.Test>;

  // --- Setup and Teardown ---

  // beforeEach: Executes before each test (it block)
  beforeEach(() => {
    // Create a new request instance for each test
    // This ensures tests are isolated
    request = chai.request(app);
  });

  // after: Executes once after all tests in 'describe' have finished
  after((done) => {
    // Close the server after all tests have run
    server.close(() => {
      console.log('Server closed after all tests');
      done(); // Call done() to indicate teardown is complete
    });
  });

  // --- Tests ---

  it('should GET all users', async () => {
    const res = await request.get('/users');
    expect(res).to.have.status(200);
    expect(res.body).to.be.an('array');
    expect(res.body.length).to.be.greaterThan(0);
    expect(res.body[0]).to.have.property('id');
    expect(res.body[0]).to.have.property('name');
    expect(res.body[0]).to.have.property('email');
  });

  it('should POST a new user', async () => {
    const newUser = { name: 'Charlie', email: '[e-mail]' };
    const res = await request.post('/users').send(newUser);

    expect(res).to.have.status(201);
    expect(res.body).to.be.an('object');
    expect(res.body).to.have.property('id');
    expect(res.body.name).to.equal('Charlie');
    expect(res.body.email).to.equal('[e-mail]');

    // Additional verification: fetch the newly created user to confirm
    const getRes = await request.get(`/users/${res.body.id}`);
    expect(getRes).to.have.status(200);
    expect(getRes.body.name).to.equal('Charlie');
  });

  it('should return 400 if name or email is missing during POST', async () => {
    const incompleteUser = { name: 'David' }; // Missing email
    const res = await request.post('/users').send(incompleteUser);

    expect(res).to.have.status(400);
    expect(res.body).to.have.property('message', 'Name and email are required');
  });

  it('should GET a specific user by ID', async () => {
      // Assuming Alice (id=1) exists
      const res = await request.get('/users/1');
      expect(res).to.have.status(200);
      expect(res.body).to.be.an('object');
      expect(res.body.id).to.equal(1);
      expect(res.body.name).to.equal('Alice');
  });

  it('should return 404 if user is not found by ID', async () => {
      const nonExistentId = 999;
      const res = await request.get(`/users/${nonExistentId}`);
      expect(res).to.have.status(404);
      expect(res.body).to.have.property('message', 'User not found');
  });

  it('should DELETE a user by ID', async () => {
      // We need a user to delete. Let's create one first.
      const createUserRes = await request.post('/users').send({ name: 'Eve', email: '[e-mail]' });
      expect(createUserRes).to.have.status(201);
      const userIdToDelete = createUserRes.body.id;

      // Now, delete the user
      const deleteRes = await request.delete(`/users/${userIdToDelete}`);
      expect(deleteRes).to.have.status(204); // No Content status for successful DELETE

      // Verification: try to fetch the deleted user
      const getRes = await request.get(`/users/${userIdToDelete}`);
      expect(getRes).to.have.status(404);
      expect(getRes.body).to.have.property('message', 'User not found');
  });

   it('should return 404 if trying to delete a non-existent user', async () => {
      const nonExistentId = 999;
      const res = await request.delete(`/users/${nonExistentId}`);
      expect(res).to.have.status(404);
      expect(res.body).to.have.property('message', 'User not found');
  });

});

// Remember to export the server so the 'after' hook can close it
export { request };

Setting Up and Tearing Down Test Environments

Effective setup and teardown strategies are crucial to ensure your tests are reliable and do not interfere with each other.

• before: Executes once before all tests in a describe block. Useful for initializing resources that will be shared by all tests (e.g., connecting to a test database).
• beforeEach: Executes before each individual test (it). Essential for ensuring each test starts with a clean and predictable state. In our example, we recreate the chai.request(app) instance to isolate each test. If we were using a database, this would be the place to clear tables or reset data.
• after: Executes once after all tests in a describe block have finished. Ideal for releasing global resources (e.g., closing the database connection, stopping the test server). In our example, we use server.close() to ensure the test process terminates correctly.
• afterEach: Executes after each individual test (it). Useful for cleaning up resources created specifically by a test (e.g., deleting a file created, removing a specific record from the database).

In the example above, we use beforeEach to isolate tests and after to close the server. For more complex tests involving databases, you might need before to set up the database and afterEach to clean up data created by each test, ensuring idempotency.

Running the Tests

Simply run the command defined in your package.json:

npm test

You should see the results of your tests in the console.

Conclusion

Mastering API testing with Mocha and Chai is a fundamental step for any backend developer serious about the quality and maintainability of their code. By implementing robust setup and teardown strategies, you ensure that your tests are a reliable representation of your API's behavior, allowing you to innovate and refactor with confidence. Remember, tests are not a luxury, but a necessity for building resilient, high-performance backend applications.