Supertest para JavaScript (Node.js): guia completo com exemplos práticos

Bem-vindo ao PythonLib! Neste artigo, vamos explorar detalhadamente a biblioteca Supertest — uma das ferramentas mais populares para testes HTTP no ecossistema Node.js. Se você desenvolve aplicações web com Express, Koa, Fastify ou qualquer outro framework, o Supertest será seu aliado indispensável para criar testes de integração robustos e confiáveis.

1. O que é e para que serve

Supertest é uma biblioteca de alto nível para testar servidores HTTP em Node.js. Ela oferece uma API intuitiva e expressiva para enviar requisições HTTP à sua aplicação e verificar as respostas. A grande vantagem do Supertest é que ele permite testar o servidor sem precisar rodá-lo em uma porta real — a biblioteca utiliza mecanismos internos do Node.js para simular a conexão HTTP, tornando os testes rápidos e isolados.

Para que serve o Supertest? No desenvolvimento web moderno, a qualidade do código é fundamental. Testes de integração que verificam o funcionamento dos seus endpoints de API ajudam a identificar regressões, erros no processamento de requisições e problemas com validação de dados. O Supertest permite escrever esses testes de forma concisa e legível, usando encadeamento de métodos (chaining) e asserções integradas para verificar status, cabeçalhos, corpo da resposta e muito mais. A biblioteca funciona perfeitamente com runners de teste populares como Jest, Mocha, Jasmine e AVA.

A biblioteca foi criada por TJ Holowaychuk (autor do Express, Koa e vários outros projetos conhecidos) e desde então é mantida pela comunidade. O Supertest é construído sobre a biblioteca SuperAgent — um poderoso cliente HTTP para Node.js e navegadores. Isso significa que você tem acesso a todos os recursos do SuperAgent, incluindo suporte a diferentes tipos de dados, upload de arquivos, manipulação de cookies e muito mais.

2. Instalação

A instalação do Supertest é feita através do gerenciador de pacotes npm. Recomenda-se instalar a biblioteca como dependência de desenvolvimento (devDependency), já que ela não é necessária no ambiente de produção.

npm install --save-dev supertest

Se você usa yarn:

yarn add --dev supertest

Para trabalhar com TypeScript, você também pode precisar instalar os tipos:

npm install --save-dev @types/supertest

Observe que o Supertest requer Node.js versão 14 ou superior. Certifique-se também de ter um runner de testes instalado (como Jest ou Mocha).

3. Início rápido — exemplo mínimo funcional

Vamos criar uma aplicação Express simples e escrever um teste para ela usando o Supertest. Este exemplo mostrará o mecanismo básico de funcionamento da biblioteca.

Primeiro, crie o arquivo app.js com sua aplicação:

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

app.get('/', (req, res) => {
  res.status(200).json({ message: 'Olá, Mundo!' });
});

app.get('/user', (req, res) => {
  res.status(200).json({ name: 'João Silva', age: 30 });
});

module.exports = app;

Agora, crie o arquivo de teste app.test.js:

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

describe('GET /', () => {
  it('deve retornar Olá, Mundo!', async () => {
    const response = await request(app)
      .get('/')
      .expect(200);

    expect(response.body).toEqual({ message: 'Olá, Mundo!' });
  });
});

describe('GET /user', () => {
  it('deve retornar dados do usuário', async () => {
    const response = await request(app)
      .get('/user')
      .expect('Content-Type', /json/)
      .expect(200);

    expect(response.body.name).toBe('João Silva');
    expect(response.body.age).toBe(30);
  });
});