Integration tests serve as a bridge between unit tests and end-to-end tests, providing a more holistic view of how components interact within your application. Supertest simplifies the process of testing HTTP requests and responses, allowing developers to focus on writing meaningful tests without getting bogged down by boilerplate code.

In this tutorial, we will cover the following key topics:

  • Setting up Supertest with an Express application
  • Writing integration tests for various HTTP methods
  • Validating response data and status codes
  • Best practices for organizing and maintaining your tests

Setting Up Supertest

To begin, ensure you have Node.js and npm installed. Create a new project and install the necessary dependencies:

mkdir supertest-example
cd supertest-example
npm init -y
npm install express supertest --save
npm install jest --save-dev

Next, create a simple Express server in a file named server.js:

// server.js
const express = require('express');
const app = express();
app.use(express.json());

let users = [];

app.post('/users', (req, res) => {
    const user = req.body;
    users.push(user);
    res.status(201).json(user);
});

app.get('/users', (req, res) => {
    res.status(200).json(users);
});

module.exports = app;

In this example, we have a basic Express server with two endpoints: one for creating users and another for retrieving them.

Writing Integration Tests

Create a new file named server.test.js to write your integration tests using Supertest and Jest:

// server.test.js
const request = require('supertest');
const app = require('./server');

describe('User API', () => {
    it('should create a new user', async () => {
        const newUser = { name: 'John Doe', age: 30 };
        const response = await request(app)
            .post('/users')
            .send(newUser)
            .expect(201);

        expect(response.body).toEqual(newUser);
    });

    it('should retrieve all users', async () => {
        const response = await request(app)
            .get('/users')
            .expect(200);

        expect(response.body).toEqual(expect.arrayContaining([]));
    });
});

Explanation of the Test Cases

  1. Creating a New User:
  • We define a new user object and send a POST request to the /users endpoint.
  • We expect a 201 status code, indicating successful creation.
  • Finally, we assert that the response body matches the user object we sent.
  1. Retrieving All Users:
  • We send a GET request to the /users endpoint.
  • We expect a 200 status code and validate that the response body is an array, which may contain our previously created user.

Validating Response Data and Status Codes

Supertest allows you to chain multiple assertions together, making your tests concise and readable. You can also validate specific properties of the response:

it('should return a user with correct properties', async () => {
    const newUser = { name: 'Jane Doe', age: 25 };
    await request(app).post('/users').send(newUser).expect(201);

    const response = await request(app).get('/users').expect(200);
    const user = response.body[0];

    expect(user).toHaveProperty('name', 'Jane Doe');
    expect(user).toHaveProperty('age', 25);
});

Best Practices for Organizing Tests

  1. Group Related Tests: Use describe blocks to group related tests, improving readability and organization.
  2. Use Before and After Hooks: Utilize beforeAll, beforeEach, afterAll, and afterEach hooks to set up and tear down any necessary state. This can help maintain a clean testing environment.
beforeEach(() => {
    users = []; // Reset users before each test
});
  1. Keep Tests Independent: Ensure that your tests do not depend on the results of other tests. This isolation helps in identifying failures quickly.
  1. Run Tests Automatically: Integrate your tests into your CI/CD pipeline to ensure they run automatically on every commit or pull request.

Conclusion

In this tutorial, we explored how to effectively use Supertest for integration testing in JavaScript. We covered setting up an Express server, writing integration tests for various HTTP methods, and validating response data. By following best practices for organizing and maintaining your tests, you can ensure that your application remains robust and reliable.

Learn more with useful resources: