Aula 5 — Back-End I — TDD top-down

Identificação

Disciplina

IN02 · Desenvolvimento Web

Módulo

2 — Ciclo Comum

Aula

5 de 11

Carga horária do dia

6h (2h + 2h + 2h)

Modalidade

Presencial · Metodologia ativa

Pré-aula

Autoestudo guiado

Resumo

A aula 5 abre o bloco de back-end com uma premissa forte: todo código nasce de um teste que falha. Em vez de escrever o servidor primeiro e testar depois, configuramos Jest + ts-jest + supertest, escrevemos specs falhando do topo (controller via supertest) para a base (helper puro) e só então implementamos — começando sempre pelo controller e pelas rotas, depois service, repository, helpers.

O fechamento aplica refactor com testes verdes (extrair asyncHandler, mover validações para helpers) e localiza o trabalho na visão Computational do RM-ODP. Saímos com um GET /users/:id em TypeScript completo, com testes em todas as 4 camadas testadas hoje.

Objetivos de aprendizagem

OA-1Configurar um projeto TypeScript com jest, ts-jest e supertest, com .spec.ts ao lado de cada arquivo.
OA-2Escrever specs RED top-down: controller (supertest), service (mockando repository), repository (mockando pool), helper puro.
OA-3Implementar GREEN começando pelo controller e pelas rotas, depois descer para service, repository, helpers.
OA-4Aplicar GREEN nas demais camadas (service, repository com SQL parametrizado, helpers e classe de erro).
OA-5Aplicar AAA (Arrange / Act / Assert) e os matchers principais: toBe, toEqual, toMatchObject, rejects.toThrow.
OA-6Refatorar com testes verdes: extrair asyncHandler, mover validações para helpers, sem regredir comportamento.

Pré-requisitos

Aula 1 concluída: dev web e fundamentos de HTTP.
Aula 2 e 3 concluídas: modelagem e CRUD em SQL no banco da equipe.
Aula 4 concluída: JOINs e queries analíticas — esse SQL passará a ser invocado pela aplicação.
Node.js LTS instalado, npm funcional e git configurado.
Editor com plugin TypeScript e Jest (VS Code é o recomendado).

Cronograma do dia

📚 Bloco 1 · Autoestudo

08h00 — 10h00

Estudo individual orientado pelo material da aula 5.

Leitura completa do Material da Aula 5 (TDD, setup TS, setup Jest, AAA, specs, GREEN, refactor).
Inicializar repositório local com npm init -y e instalar dependências (runtime + dev).
Configurar tsconfig.json em strict mode e jest.config.ts com ts-jest.
Caderno de bordo: anotar 2 dúvidas sobre mocks ou matchers para a daily.

🎓 Bloco 2 · Instrução PE — Aula em metodologia ativa

10h00 — 12h00

Encontro síncrono com o professor especialista. 15 minutos de daily seguidos de 1h45 de aula.

10h00 — 10h15 · Daily: dúvidas trazidas do autoestudo.
10h15 — 12h00 · Setup, specs RED top-down, GREEN do controller para a base, refactor.

🍴 Intervalo · Almoço

12h00 — 14h00

Janela livre.

🛠️ Bloco 3 · Desenvolvimento do projeto

14h00 — 16h00

Janela de trabalho da equipe sobre o projeto integrador.

Aplicar TDD top-down em uma entidade do projeto (não users) com GET /:entidade/:id.
Escrever os 4 specs (controller, service, repository, helper) antes de qualquer linha de código de produção.
Implementar GREEN sempre começando por controller e rotas.
Refatorar com testes verdes: extrair asyncHandler ou validação em helper.
Abrir Merge Request feat(api): GET /:entidade/:id com TDD top-down com evidência de npm test verde.

Detalhamento da instrução PE (10h00 — 12h00)

10h00
10h15

DailyDaily de abertura

Cada aluno traz, em 1 minuto: o que conseguiu instalar, qual configuração ainda travou, qual conceito (mock, matcher, supertest) ficou nebuloso. O professor consolida os pontos e calibra os exemplos.

10h15
10h25

TalkPor que TDD top-down

Apresentação rápida do ciclo RED → GREEN → REFACTOR. Por que começamos pelo controller e não pelo helper. Como o spec se torna a especificação executável que evita "invenção" de funcionalidade.

10h25
10h35

CodingSetup ao vivo: TS + Jest + supertest

O professor faz npm init, instala as dependências, monta tsconfig.json e jest.config.ts, roda npm test em projeto vazio (sem testes — saída verde imediata). Alunos replicam em paralelo.

10h35
10h50

REDSpec do controller via supertest

Em pares: escrever userController.spec.ts com 2 cenários (200 e 404) mockando userService. Rodar npm test e celebrar a falha — esse vermelho é o objetivo. O professor circula validando o uso de jest.mock e mockResolvedValue.

10h50
11h00

REDSpecs de service, repository e helper

Os outros 3 specs em sequência rápida: service mocka repo (caminho feliz e NotFoundError); repository mocka pool.query e prova uso de $1; helper isValidEmail com casos felizes e infelizes. Tudo vermelho ao final.

11h00
11h15

GREENController e rotas — sempre primeiro

Ao vivo: o professor implementa app.ts, routes/userRoutes.ts e controllers/userController.ts — apenas o necessário para o spec do controller virar verde (depende ainda das demais camadas). Mostra a pirâmide subir.

11h15
11h25

GREENService e model

Em pares: implementar userService.ts e models/user.ts (interface User) para passar os 2 testes do service. Depois rodar todos os specs: o do service vira verde; o do controller ainda falha porque o repository não existe.

11h25
11h35

GREENRepository, pool e SQL parametrizado

Implementar db/pool.ts e repositories/userRepository.ts com pool.query("... WHERE id = $1", [id]). O professor reforça em voz alta: nunca concatenar string com input do usuário. Após esse passo o spec do controller também passa.

11h35
11h45

GREENHelpers, errors e middleware

Implementar errors/AppError.ts (AppError + NotFoundError), middlewares/errorHandler.ts e helpers/email.ts. Rodar npm test — todos verdes. Comemoração curta.

11h45
11h55

REFACTORRefatoração com testes verdes

Em pares: extrair o padrão try/catch + next(e) em um asyncHandler em helpers/asyncHandler.ts e simplificar o controller. Rodar npm test a cada passo — só prossegue enquanto a barra estiver verde.

11h55
12h00

AtivaSíntese

Cada aluno escreve "o teste que mais me ajudou hoje foi..." e cita um spec específico. O professor anuncia a entrega da tarde: aplicar o mesmo padrão a uma entidade do projeto.

Estratégias de metodologia ativa

Celebrar o vermelho — alunos rodam npm test com specs sem código de produção e veem a falha como um marco esperado, não como um erro.
Pirâmide subindo — implementação visualmente acumulativa: a cada camada adicionada, mais um spec vira verde. O painel de testes serve de feedback contínuo.
Pareamento ping-pong — em pares, uma pessoa escreve o spec, a outra implementa o código de produção; trocam papéis a cada ciclo.
Refactor de oficina — extrair asyncHandler só com testes verdes; cada micro-passo seguido de npm test.
Predição antes da execução — antes de rodar um spec, alunos predizem qual saída esperam, reforçando o modelo mental do TDD.

Recursos e ferramentas

Categoria	Recurso	Uso
Slides	`slides/slide-lesson-5.html`	Exposição na instrução PE
Material	`materials/lesson-5-material.html`	Autoestudo
Runtime	Node.js LTS, npm	Executar testes e servidor
Linguagem	TypeScript, `tsx`	Compilação e watch mode em dev
Framework HTTP	Express + `@types/express`	Servidor e roteamento
Driver de banco	`pg` + `@types/pg`	Pool de conexões e SQL parametrizado
Testes	`jest`, `ts-jest`, `@types/jest`, `supertest`, `@types/supertest`	Specs unitários e HTTP em memória
Repositório	`src/` com 6 camadas e `.spec.ts` ao lado	Estrutura padrão do projeto

Verificação de aprendizagem

CR-1Configurou Jest + ts-jest + supertest e fez o primeiro npm test rodar verde antes de qualquer spec.
CR-2Escreveu os 4 specs em estado RED (controller via supertest, service mockando repo, repository mockando pool, helper puro) antes de qualquer código de produção.
CR-3Implementou GREEN começando por controller e rotas, e depois desceu para service, repository, helpers — nessa ordem.
CR-4Usou SQL parametrizado com $1 no repository e o spec correspondente prova esse uso via toHaveBeenCalledWith.
CR-5Realizou pelo menos uma refatoração (ex.: asyncHandler) sem regredir nenhum teste e abriu Merge Request feat(api): GET /:entidade/:id com TDD top-down com npm test verde anexado.

Critério mínimo

Aluno que sair às 16h sem os 4 specs verdes sobre uma entidade do projeto está em débito técnico para a aula 6 — onde o CRUD HTTP completo será construído sobre essa fundação.

Conexão com a aula 6

A aula 6 (Back-End II) expande o que foi feito hoje: do GET isolado para o CRUD HTTP completo (POST, PUT, DELETE) com validações de payload, tratamento robusto de erros (400, 422), e o ciclo TDD top-down se repete para cada novo método.

Os 4 specs de hoje viram base reutilizável — o padrão (mock service no controller, mock repo no service, mock pool no repository) se repete para cada operação.
O AppError ganha subclasses adicionais: ValidationError (422), BadRequestError (400).
Validação de payload migra para um helper puro testado isoladamente — outra peça que nasce de um spec.

Para o autoestudo da aula 6

Antes das 8h do próximo dia: ler o material da aula 6, listar os 3 endpoints da entidade do projeto que faltam (POST, PUT, DELETE) e esboçar os specs de controller correspondentes — em RED, sem implementação.