Pular para o conteúdo principal

ADR 0001 — Adoção do Pest PHP como framework de testes

Introdução ao documento​

Este ADR registra a decisão de adotar o Pest PHP como framework de testes do projeto activity-delivery-api.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Contexto​

  • O projeto necessita de um framework de testes robusto para garantir qualidade e prevenir regressões em uma API com múltiplos endpoints, autenticação dupla (API Key + JWT) e integrações externas (Novu, S3).
  • O ecossistema Laravel oferece nativamente o PHPUnit, mas o Pest PHP provê uma sintaxe mais expressiva e concisa.
  • Evidência: composer.json — dependência pestphp/pest ^3.8, pestphp/pest-plugin-laravel

Decisão​

  1. Adotar Pest PHP 3.8 como framework de testes, utilizando o plugin pest-plugin-laravel para integração nativa com o framework.
  2. Estruturar testes em tests/Unit/ e tests/Feature/ seguindo a convenção Laravel.
  3. Utilizar RefreshDatabase trait para isolamento de banco em cada teste.
  4. Configurar cobertura de código via XDebug e upload para Codecov no CI.

Consequências​

Positivas​

  • Sintaxe mais expressiva e legível (it(), expect(), beforeEach()) reduz boilerplate.
  • Compatibilidade total com PHPUnit (testes existentes continuam funcionando).
  • Suporte nativo a cobertura, paralelismo e plugins específicos do Laravel.
  • 140 testes / 375 assertions demonstram adoção bem-sucedida.

Negativas​

  • Dependência adicional (pestphp/pest) no ambiente de desenvolvimento.
  • Desenvolvedores acostumados exclusivamente com PHPUnit precisam se familiarizar com a API do Pest.

Alternativas consideradas​

  • PHPUnit puro — mais verboso, sem a expressividade do Pest, mas nativo no Laravel.
  • Codeception — framework mais pesado, não alinhado com o padrão do ecossistema Laravel.

Pendências​

  • Nenhuma.