Testing Node.js with Jest and Supertest

You deployed a bug that deleted user data because the UPDATE query was missing a WHERE clause. The tests passed because they did not verify the query was correct. Testing Node.js applications is not about hitting a coverage percentage — it is about catching the specific bugs that happen in production: missing error handling, incorrect database queries, and unhandled promise rejections. This article covers the testing pyramid for Node.js, integration testing with Supertest, mocking external services, and the CI pipeline that prevents bugs from reaching production.

Why Jest and Supertest for Node.js Testing

Testing is non-negotiable in production Node.js. Jest is the de facto test runner for its zero-config setup, built-in mocking, and parallel execution. Supertest complements it by providing a high-level abstraction for HTTP assertions, allowing you to test Express routes without spinning up a real server. Together, they catch regressions early, enforce API contracts, and give you confidence to deploy. In production, a failing test suite is a deploy blocker — treat it as such. Jest’s snapshot testing can also detect unintended UI changes, but for APIs, Supertest’s request-response assertions are your bread and butter.

npm install --save-dev jest supertest

Setting Up Your Test Environment

Start by configuring Jest in package.json or jest.config.js. Use testEnvironment: 'node' to avoid jsdom overhead. Set clearMocks: true to prevent state leakage between tests. For Supertest, export your Express app from a separate module (e.g., app.js) and import it in tests — never listen on a port during tests. Use beforeAll and afterAll for setup/teardown like database connections. In production, use environment variables to switch between test and real databases. A common pitfall: forgetting to call done() or return a promise in async tests — Jest will timeout.

module.exports = {
  testEnvironment: 'node',
  clearMocks: true,
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};

Writing Your First API Test

A basic test for a GET endpoint: import request from Supertest, pass your app, and chain HTTP methods. Use await or return the promise. Assert status code, headers, and body shape. For JSON APIs, use expect(response.body).toMatchObject(...) to avoid brittle exact matches. Test both success and error paths. In production, always test 4xx and 5xx responses — they’re the most common failure points. Never hardcode IDs; generate them dynamically or use fixtures.

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

describe('GET /api/users', () => {
  it('should return a list of users', async () => {
    const res = await request(app)
      .get('/api/users')
      .expect('Content-Type', /json/)
      .expect(200);

    expect(res.body).toMatchObject({
      users: expect.arrayContaining([
        expect.objectContaining({ id: expect.any(Number), name: expect.any(String) })
      ])
    });
  });

  it('should return 500 on server error', async () => {
    // Simulate error by mocking the database call
    jest.spyOn(db, 'findAll').mockRejectedValue(new Error('DB down'));
    const res = await request(app).get('/api/users').expect(500);
    expect(res.body).toMatchObject({ error: 'Internal Server Error' });
  });
});

Testing Authentication and Authorization

Protected endpoints require tokens. Generate a valid JWT in beforeEach using a test secret. For role-based access, create helper functions that return tokens with different claims. Test that unauthenticated requests return 401, and unauthorized (wrong role) return 403. In production, never use the same secret for tests and real JWTs — use a dedicated test secret. Also test token expiration: mock Date.now or use jest.useFakeTimers. A common bug: forgetting to set Authorization header correctly.

const request = require('supertest');
const app = require('../app');
const jwt = require('jsonwebtoken');

const testSecret = 'test-secret';
const adminToken = jwt.sign({ role: 'admin' }, testSecret, { expiresIn: '1h' });
const userToken = jwt.sign({ role: 'user' }, testSecret, { expiresIn: '1h' });

describe('DELETE /api/users/:id', () => {
  it('should reject unauthenticated requests', async () => {
    await request(app)
      .delete('/api/users/1')
      .expect(401);
  });

  it('should reject non-admin users', async () => {
    await request(app)
      .delete('/api/users/1')
      .set('Authorization', `Bearer ${userToken}`)
      .expect(403);
  });

  it('should allow admin to delete', async () => {
    await request(app)
      .delete('/api/users/1')
      .set('Authorization', `Bearer ${adminToken}`)
      .expect(200);
  });
});

Mocking External Dependencies

Real APIs and databases make tests slow and flaky. Use Jest’s jest.mock to replace modules. For HTTP calls, mock axios or node-fetch. For databases, mock your ORM (e.g., jest.mock('mongoose')). Always restore mocks after tests to avoid cross-test contamination. In production, mock at the boundary — don’t mock internals of your own code. A common mistake: mocking too much, which hides integration bugs. Use integration tests sparingly for critical paths.

jest.mock('stripe', () => ({
  charges: {
    create: jest.fn().mockResolvedValue({ id: 'ch_123', status: 'succeeded' })
  }
}));

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

describe('POST /api/charge', () => {
  it('should create a charge successfully', async () => {
    const res = await request(app)
      .post('/api/charge')
      .send({ amount: 2000, currency: 'usd' })
      .expect(200);

    expect(res.body).toMatchObject({ id: 'ch_123', status: 'succeeded' });
  });

  it('should handle Stripe error', async () => {
    const stripe = require('stripe');
    stripe.charges.create.mockRejectedValue(new Error('Card declined'));

    const res = await request(app)
      .post('/api/charge')
      .send({ amount: 2000, currency: 'usd' })
      .expect(402);

    expect(res.body).toMatchObject({ error: 'Payment failed' });
  });
});

Testing Database Interactions

For database tests, use an in-memory database or a test container. For MongoDB, mongodb-memory-server downloads a binary and runs it in-process. For SQL, use sqlite3 in memory. Seed data in beforeAll and clean up in afterAll. Test CRUD operations, unique constraints, and cascading deletes. In production, never run tests against a shared database — parallel test execution will cause conflicts. Use transactions to roll back changes after each test if possible.

const mongoose = require('mongoose');
const { MongoMemoryServer } = require('mongodb-memory-server');
const User = require('../models/User');

let mongoServer;

beforeAll(async () => {
  mongoServer = await MongoMemoryServer.create();
  await mongoose.connect(mongoServer.getUri());
});

afterAll(async () => {
  await mongoose.disconnect();
  await mongoServer.stop();
});

describe('User Model', () => {
  it('should create a user', async () => {
    const user = await User.create({ name: 'Alice', email: 'alice@test.com' });
    expect(user.name).toBe('Alice');
  });

  it('should enforce unique email', async () => {
    await User.create({ name: 'Bob', email: 'bob@test.com' });
    await expect(User.create({ name: 'Bob2', email: 'bob@test.com' })).rejects.toThrow();
  });
});

Testing Middleware and Error Handlers

Middleware like rate limiting, request validation, and error handlers should be tested in isolation. For custom error handlers, create a test route that throws an error and assert the response shape. Test that validation middleware returns 400 with proper error messages. In production, ensure your global error handler doesn’t leak stack traces. Use express-async-errors or wrap async routes to catch unhandled rejections.

const request = require('supertest');
const express = require('express');

const app = express();
app.get('/error', (req, res, next) => {
  next(new Error('Something broke'));
});
app.use((err, req, res, next) => {
  res.status(500).json({ error: 'Internal Server Error' });
});

describe('Error Handler', () => {
  it('should return 500 with generic message', async () => {
    const res = await request(app).get('/error').expect(500);
    expect(res.body).toMatchObject({ error: 'Internal Server Error' });
    expect(res.body).not.toHaveProperty('stack');
  });
});

Snapshot Testing for API Responses

Jest snapshots can detect unexpected changes in API responses. Use toMatchSnapshot() for complex response bodies. Update snapshots with --updateSnapshot when changes are intentional. In production, commit snapshots to version control and review them in PRs. A common pitfall: snapshots that include dynamic data like timestamps or IDs — use expect.any(Number) or custom serializers to ignore them.

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

describe('GET /api/config', () => {
  it('should match the config snapshot', async () => {
    const res = await request(app).get('/api/config').expect(200);
    // Ignore dynamic fields
    expect(res.body).toMatchSnapshot({
      updatedAt: expect.any(String),
      version: expect.any(Number)
    });
  });
});

Organizing Tests for Maintainability

Structure tests by feature, not by type. Use describe blocks for grouping. Keep test files close to the source files (e.g., __tests__ folder or .test.js alongside). Use factories or fixtures for test data. Avoid shared mutable state between tests. In production, enforce naming conventions with ESLint plugin jest/no-disabled-tests. A common anti-pattern: one giant test file — split into multiple files for parallel execution.

const User = require('../models/User');

const buildUser = (overrides = {}) => ({
  name: 'Test User',
  email: `test${Date.now()}@example.com`,
  role: 'user',
  ...overrides
});

module.exports = { buildUser };

Running Tests in CI/CD

In CI, run npm test with flags: --ci for warnings as errors, --maxWorkers=50% to avoid OOM, --coverage for reports. Use jest-junit for test result XML. Cache node_modules and Jest cache to speed up runs. Fail the build if tests fail or coverage drops below threshold. In production, also run a smoke test suite against the deployed environment. A common mistake: running tests with --watch in CI — it hangs forever.

name: Test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --ci --coverage --maxWorkers=2
      - uses: actions/upload-artifact@v3
        with:
          name: coverage
          path: coverage/

Performance Testing with Jest

Jest can measure performance using jest.useFakeTimers and performance.now(). For API response times, use Supertest’s expect with a custom timeout. In production, set a maximum response time in your tests (e.g., 200ms). Use --detectOpenHandles to find unclosed connections that cause memory leaks. A common issue: async operations not awaited, leading to false positives. Use expect.assertions(1) to ensure assertions run.

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

describe('GET /api/users performance', () => {
  it('should respond within 200ms', async () => {
    const start = Date.now();
    await request(app).get('/api/users').expect(200);
    const duration = Date.now() - start;
    expect(duration).toBeLessThan(200);
  });

  it('should not have open handles', async () => {
    // This test will fail if there are unclosed connections
    await request(app).get('/api/users').expect(200);
  });
});

Advanced: Testing File Uploads and WebSockets

Supertest supports file uploads via attach. For WebSockets, use socket.io-client in tests. Mock the WebSocket server or use a real one with a random port. Test that events are emitted and received correctly. In production, file upload tests should check file size limits, MIME types, and virus scanning. A common bug: forgetting to clean up uploaded files after tests.

const request = require('supertest');
const app = require('../app');
const path = require('path');

describe('POST /api/upload', () => {
  it('should upload a file', async () => {
    const res = await request(app)
      .post('/api/upload')
      .attach('file', path.join(__dirname, 'test-file.txt'))
      .expect(200);

    expect(res.body).toMatchObject({ filename: 'test-file.txt', size: expect.any(Number) });
  });

  it('should reject files over 5MB', async () => {
    // Create a large buffer
    const largeBuffer = Buffer.alloc(6 * 1024 * 1024);
    const res = await request(app)
      .post('/api/upload')
      .attach('file', largeBuffer, 'large.txt')
      .expect(413);

    expect(res.body).toMatchObject({ error: 'File too large' });
  });
});

Coverage Thresholds in Jest Config

Jest's coverage thresholds enforce minimum code coverage percentages, preventing regressions from slipping through. Configure them in jest.config.js under coverageThreshold. You can set global thresholds or per-file patterns. For example, require 80% branch coverage globally, but 100% for critical modules like authentication. Thresholds apply to statements, branches, functions, and lines. If coverage drops below the threshold, the test suite fails. This is a powerful gate for CI pipelines. To generate coverage reports, run jest --coverage. Combine with collectCoverageFrom to specify which files to include. Exclude test files, mocks, and configuration files. Be realistic: start with 70-80% and increase gradually. Avoid 100% targets for non-critical code—they often lead to brittle tests. Use // istanbul ignore next comments sparingly for edge cases that are impossible to test.

module.exports = {
  testEnvironment: 'node',
  collectCoverageFrom: ['src/**/*.js', '!src/**/*.test.js'],
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80
    },
    './src/auth/**/*.js': {
      statements: 100,
      branches: 100,
      functions: 100,
      lines: 100
    }
  }
};

Testing File Uploads with .attach()

Supertest's .attach() method allows you to simulate file uploads in your tests. This is essential for endpoints that accept multipart/form-data, such as profile picture uploads or CSV imports. To use .attach(), pass the field name and the file path or a Buffer. For example, request(app).post('/upload').attach('avatar', 'test/fixtures/avatar.jpg'). You can also attach multiple files or mix fields with .field(). For better performance, use a Buffer instead of reading from disk each time. Create a test helper that generates a dummy file buffer. Always test both success and error cases: missing file, wrong type, size limits. Use middleware like multer to handle uploads; test that middleware correctly parses the file. Remember to clean up uploaded files in afterAll if your app saves them to disk. For cloud storage, mock the upload service to avoid external calls.

const request = require('supertest');
const app = require('../app');
const path = require('path');

describe('POST /upload', () => {
  it('uploads a file successfully', async () => {
    const response = await request(app)
      .post('/upload')
      .attach('file', path.resolve(__dirname, 'fixtures', 'test.txt'));
    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('filename');
  });

  it('rejects upload without file', async () => {
    const response = await request(app).post('/upload');
    expect(response.status).toBe(400);
  });

  it('rejects oversized file', async () => {
    const largeBuffer = Buffer.alloc(10 * 1024 * 1024 + 1); // 10MB+1
    const response = await request(app)
      .post('/upload')
      .attach('file', largeBuffer, 'large.txt');
    expect(response.status).toBe(413);
  });
});

Global Setup/Teardown for MongoDB Memory Server

When testing database interactions, using a real MongoDB instance introduces flakiness and dependency. mongodb-memory-server provides an in-memory MongoDB that starts and stops per test suite. Jest's globalSetup and globalTeardown hooks allow you to start the server once before all tests and stop it after. Configure them in jest.config.js. In globalSetup, start the MongoDB memory server and set the connection URI to an environment variable. In globalTeardown, stop the server. Your test files then connect to this URI. This approach is fast and isolated. Ensure each test suite uses a separate database or collection to avoid cross-contamination. Use beforeEach to drop collections. For parallel test execution, use unique database names per worker. The memory server downloads a MongoDB binary on first run; cache it in CI to speed up builds.

module.exports = {
  globalSetup: './tests/setup.js',
  globalTeardown: './tests/teardown.js',
  testEnvironment: 'node'
};

Middleware Unit Testing with jest.fn()

Middleware functions are the backbone of Express apps. Testing them in isolation with jest.fn() mocks ensures they behave correctly without spinning up the full server. To test a middleware, create mock req, res, and next objects. res should have stubs for methods like status, json, send. Use jest.fn() to track calls and arguments. For example, test that an auth middleware calls next() on valid token and returns 401 on invalid. You can also test error-handling middleware by passing an error to next and verifying the response. This approach is fast and focused. Combine with jest.spyOn to verify that next was called with specific arguments. For middleware that modifies req, check the modified properties. This technique is essential for high-coverage, low-level testing.

const authMiddleware = require('../middleware/auth');

describe('auth middleware', () => {
  it('calls next() for valid token', () => {
    const req = { headers: { authorization: 'Bearer validtoken' } };
    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
    const next = jest.fn();

    authMiddleware(req, res, next);

    expect(next).toHaveBeenCalled();
    expect(res.status).not.toHaveBeenCalled();
  });

  it('returns 401 for missing token', () => {
    const req = { headers: {} };
    const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
    const next = jest.fn();

    authMiddleware(req, res, next);

    expect(res.status).toHaveBeenCalledWith(401);
    expect(next).not.toHaveBeenCalled();
  });
});