Pular para conteúdo

Como rodar

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-15

Audiência: dev que clonou o repositório e quer subir o app, rodar os testes e passar o gate local. Para a organização do código, veja o Guia do código; para variáveis de ambiente e toggles, a Configuração.

Pré-requisitos

  • JDK 25 (a versão de docs/app.json → toolchain.java). Com outro JDK como padrão da máquina, aponte o JAVA_HOME para o 25 ao chamar o Gradle.
  • Docker — o Postgres de dev (docker-compose.dev.yml) e o de teste (xadm-comum-teste) sobem em container.

Rodar em desenvolvimento

./gradlew run          # sobe o Postgres de dev (docker compose, porta 5433) e o app na 8080

O run ativa o perfil dev (MICRONAUT_ENVIRONMENTS=dev, application-dev.yml). Quem já tem o próprio Postgres exporta DATASOURCES_DEFAULT_URL e o compose não sobe. Webhook ligado; poll desligado até existir PIED_TOKEN.

Conferência rápida:

curl http://localhost:8080/health
curl -X POST http://localhost:8080/webhook/pied \
  -H 'Content-Type: application/json' \
  -d '{"event":"order.created","data":{"id":1}}'

Testes

Os testes são divididos por source set:

  • ./gradlew test — só unitários (src/test/java: função pura, fake, WireMock, ArchUnit). Não sobe Docker e roda em segundos: é o loop rápido de dev.
  • ./gradlew integrationTest — os @MicronautTest (src/integrationTest/java), contra um Postgres real do PostgresTestResource da casa (xadm-comum-teste): um postgres:18-alpine compartilhado por JVM, injetado por classe via PostgresTestPropertyProvider (a classe implementa a interface e usa @TestInstance(PER_CLASS)).
  • Onde cada teste mora: precisa de bean context, DataSource ou HTTP client Micronaut → src/integrationTest; função pura, fake, WireMock ou ArchUnit → src/test.
  • Padrão do teste de integração (decisão 0013): @MicronautTest(transactional = false), sem JDBC cru. Seed e leitura vão pelos repositórios de produção; o que eles não expõem (limpeza entre testes, seed com timestamp no passado, contagem do outbox mensagem_m2m, atalhos de FSM) vive em support/BancoFixture, o único ponto com SQL de baixo nível. O @BeforeEach limpa com fixture.apagarTudo(), por DELETE e poupando as tabelas semeadas por migration. Com a transação de teste padrão, um write via repositório @Transactional ficaria sem commit: travaria contra uma segunda conexão e sumiria para leituras por outra conexão.
  • Trava vira falha: a task de teste cai em 15 min (build.gradle.kts), cada teste em 2 min (src/test/resources/junit-platform.properties) e a conexão de teste em 5 s (application-test.yml).

Gate local

./gradlew check        # checkstyle + test + integrationTest + fronteiras (ArchUnit) + % de cobertura
./gradlew coverage     # testes + relatório JaCoCo (build/reports/jacoco/test/html/index.html)

O check é o que o CI roda. A cobertura é visível no log, não bloqueante.

Gate lento ou travando

Nunca rode --no-daemon. Sem daemon o Micronaut refaz o annotation processing do zero a cada run e empilha JVMs órfãs (~1,5 GB cada) até a RAM saturar. O daemon fica ligado (org.gradle.daemon=true); itere com ./gradlew test e rode integrationTest/check quando mexer no banco. O container do Postgres de teste não se mata à mão: o Ryuk do Testcontainers o recolhe quando a JVM do teste cai. Com o check pendurado por containers órfãos (SIGKILL repetido), remova só os do Testcontainers, pelo rótulo (docker rm -f $(docker ps -aq --filter "label=org.testcontainers=true")), e rode de novo — filtrar pela imagem postgres:18-alpine derruba também o Postgres de dev do docker-compose.dev.yml (Java/Micronaut, Armadilhas).

Lib da casa ainda não publicada

O build procura br.com.xadm primeiro no registro e depois no ~/.m2 (Bibliotecas da casa). Para testar contra uma versão da xadm-commons que ainda não saiu, publique-a no mavenLocal a partir do repo da lib e declare o número no build.gradle.kts. A /xadm-release recusa dependência da casa que não esteja no registro. Com o registro fora do ar, o Gradle não cai no local: use ./gradlew --offline.