Back-end5 min de leitura

Testes E2E no Node.js: Supertest, Banco de Testes Isolado e Testcontainers

Como montar um ambiente de testes E2E robusto no Express: criação dinâmica de schemas de banco de dados por suite, autenticação via factories, Supertest para roteamento real e o uso de Testcontainers para dependências.

12 de agosto de 2026

Testes Unitários garantem que a regra de negócio funciona, mas são cegos para o mundo externo. Se o arquivo de rotas esquecer de injetar um middleware, ou se a string de conexão do TypeORM estiver errada, a aplicação passa em todos os testes unitários e quebra no deploy. Os Testes End-to-End (E2E) existem para validar o fluxo completo: request HTTP → Roteamento → Middleware (Autenticação/Validação) → Controller → Use Case → Banco de Dados Real → Response.

Isolamento de Banco de Dados por Teste

O maior erro em testes E2E é usar um banco de dados compartilhado. Testes rodando em paralelo inserem dados que afetam as queries uns dos outros, causando os famosos "Flaky Tests" (testes que às vezes passam, às vezes falham). A solução é criar um Schema ou Database isolado para cada suíte (arquivo) de teste e derrubá-lo no final.

setupE2E.ts

1import { execSync } from 'child_process';
import { execSync } from 'child_process';
2import { randomUUID } from 'crypto';
import { randomUUID } from 'crypto';
3import { dataSource } from '../typeorm/data-source';
import { dataSource } from '../typeorm/data-source';
4

5// Esse arquivo é configurado no jest.config.ts (setupFilesAfterEnv)
// Esse arquivo é configurado no jest.config.ts (setupFilesAfterEnv)
6// Ele roda antes de cada arquivo de teste (.spec.ts)
// Ele roda antes de cada arquivo de teste (.spec.ts)
7

8const schemaId = `test_${randomUUID().replace(/-/g, '')}`;
const schemaId = `test_${randomUUID().replace(/-/g, '')}`;
9

10beforeAll(async () => {
beforeAll(async () => {
11  // Altera a URL de conexão do TypeORM para usar o novo schema
  // Altera a URL de conexão do TypeORM para usar o novo schema
12  const url = new URL(process.env.DATABASE_URL!);
  const url = new URL(process.env.DATABASE_URL!);
13  url.searchParams.set('schema', schemaId);
  url.searchParams.set('schema', schemaId);
14  process.env.DATABASE_URL = url.toString();
  process.env.DATABASE_URL = url.toString();
15

16  await dataSource.initialize();
  await dataSource.initialize();
17  // Cria o schema isolado no PostgreSQL
  // Cria o schema isolado no PostgreSQL
18  await dataSource.query(`CREATE SCHEMA IF NOT EXISTS ${schemaId}`);
  await dataSource.query(`CREATE SCHEMA IF NOT EXISTS ${schemaId}`);
19  
  
20  // Roda as migrations exclusivas para este schema
  // Roda as migrations exclusivas para este schema
21  execSync('npm run typeorm migration:run', { env: process.env });
  execSync('npm run typeorm migration:run', { env: process.env });
22});
});
23

24afterAll(async () => {
afterAll(async () => {
25  // Limpeza absoluta: apaga o schema inteiro no final
  // Limpeza absoluta: apaga o schema inteiro no final
26  await dataSource.query(`DROP SCHEMA IF EXISTS ${schemaId} CASCADE`);
  await dataSource.query(`DROP SCHEMA IF EXISTS ${schemaId} CASCADE`);
27  await dataSource.destroy();
  await dataSource.destroy();
28});
});

Supertest: Chamadas HTTP sem subir porta

O schema isolado por UUID garante que suites rodando em paralelo (com --maxWorkers=4 do Jest) nunca compartilhem dados. O DROP SCHEMA CASCADE no afterAll limpa tudo sem deixar lixo no banco de testes. Esse padrão também funciona com SQLite em memória para testes ainda mais rápidos, mas o PostgreSQL isolado garante que você esteja testando o comportamento real do banco em produção.

O supertest recebe a instância nativa do Express (app) e permite disparar requisições diretamente pela memória, sem precisar alocar a porta local :3333 e sem problemas de concorrência de portas rodando testes em paralelo.

Um teste E2E bem escrito verifica três camadas: o status HTTP (201, 422, 404), a estrutura da resposta (campos presentes, campos ausentes como password), e o efeito no banco (registro foi realmente criado). Verificar apenas o status HTTP não é suficiente — você pode retornar 201 sem ter salvo nada. Verificar apenas o banco não garante que a rota e o middleware estão funcionando.

CreateUserController.e2e-spec.ts

1import request from 'supertest';
import request from 'supertest';
2import { app } from '../../../infra/http/app';
import { app } from '../../../infra/http/app';
3import { dataSource } from '../../../infra/typeorm/data-source';
import { dataSource } from '../../../infra/typeorm/data-source';
4

5describe('CreateUserController (E2E)', () => {
describe('CreateUserController (E2E)', () => {
6  it('should create a new user and return 201', async () => {
  it('should create a new user and return 201', async () => {
7    // 1. Arrange & Act
    // 1. Arrange & Act
8    const response = await request(app)
    const response = await request(app)
9      .post('/users')
      .post('/users')
10      .send({
      .send({
11        name: 'Jane Doe',
        name: 'Jane Doe',
12        email: 'jane@example.com',
        email: 'jane@example.com',
13        password: 'secure_password',
        password: 'secure_password',
14      });
      });
15

16    // 2. Assert HTTP Response
    // 2. Assert HTTP Response
17    expect(response.status).toBe(201);
    expect(response.status).toBe(201);
18    expect(response.body).toHaveProperty('id');
    expect(response.body).toHaveProperty('id');
19    expect(response.body.email).toBe('jane@example.com');
    expect(response.body.email).toBe('jane@example.com');
20    expect(response.body).not.toHaveProperty('password');
    expect(response.body).not.toHaveProperty('password');
21

22    // 3. Assert Database Effect (Verifica se realmente salvou)
    // 3. Assert Database Effect (Verifica se realmente salvou)
23    const userInDb = await dataSource.query(
    const userInDb = await dataSource.query(
24      `SELECT * FROM users WHERE email = 'jane@example.com'`
      `SELECT * FROM users WHERE email = 'jane@example.com'`
25    );
    );
26    expect(userInDb).toHaveLength(1);
    expect(userInDb).toHaveLength(1);
27  });
  });
28

29  it('should return 422 if Zod validation fails', async () => {
  it('should return 422 if Zod validation fails', async () => {
30    const response = await request(app).post('/users').send({
    const response = await request(app).post('/users').send({
31      name: 'Jane',
      name: 'Jane',
32      email: 'invalid-email', // Vai ser barrado no middleware
      email: 'invalid-email', // Vai ser barrado no middleware
33      password: '123', // Muito curta
      password: '123', // Muito curta
34    });
    });
35

36    expect(response.status).toBe(422);
    expect(response.status).toBe(422);
37    expect(response.body.message).toContain('Validação');
    expect(response.body.message).toContain('Validação');
38  });
  });
39});
});

Testcontainers: Se sua API depende do Redis, Kafka ou MongoDB, não obrigue o dev a instalar e gerenciar esses serviços manualmente para rodar os testes. Use a biblioteca testcontainers-node para subir containers Docker efêmeros programaticamente no beforeAll global e injetar as portas dinâmicas nas variáveis de ambiente.

Conclusão

A Pirâmide de Testes ensina: tenha muitos testes unitários (rápidos e focados) e poucos E2E (lentos e abrangentes). Cubra 100% dos fluxos alternativos e de erros nos Testes Unitários com Repositórios em Memória. Use os Testes E2E apenas para os 'Caminhos Felizes' principais (Login, Checkout, Cadastro) para garantir que toda a fiação (Banco, Express, Middlewares, DI) está conectada corretamente.