@fc/test-utils

Pacote privado com recursos genéricos de teste e o catálogo central de amostras versionadas do monorepo.

Fronteira do pacote

Este pacote não contém regras, builders ou geradores próprios de um domínio. Apoios que conhecem um motor de cálculo ficam na pasta tests/ do pacote correspondente, ainda que sejam reutilizados por mais de uma aplicação.

Exemplos:

• a geração de testes de paridade .calc fica em packages/calculos-previdenciarios/tests/paridade-calc/;
• os builders PrevJud ficam em packages/calculos-previdenciarios/tests/apoioPrevjud.ts;
• fábricas específicas de RGPS e RPPS ficam junto às respectivas suítes;
• transportes em memória ficam locais às suítes que os utilizam.

Módulos

O pacote não tem barrel raiz nem barrels de pasta: @fc/test-utils, @fc/test-utils/amostras, @fc/test-utils/anonimizacao e @fc/test-utils/html-formatado não resolvem. Cada módulo é publicado por subpath, e o consumidor importa o arquivo que declara o símbolo.

Subpath	Conteúdo
@fc/test-utils/datas	gerarData — conversão de datas brasileiras para cenários de teste
@fc/test-utils/amostras/calculos	Fontes .calc versionadas (amostrasCalculosRgps, amostrasAtrasados, fontesCalculosPrev*, caso*)
@fc/test-utils/amostras/documentos	Fontes de documentos (fontesCnis, fontesCartasConcessao, obterFonteDocumentoPrevidenciario, documento*)
@fc/test-utils/amostras/catalogoAmostras	catalogoAmostras (identificador, domínio e formato para inventário) e os atalhos tc*, rmi*, cnis*, carta*
@fc/test-utils/anonimizacao/anonimizarDadosPessoais	anonimizarDadosPessoais
@fc/test-utils/anonimizacao/encontrarIdentificadoresPessoaisValidos	encontrarIdentificadoresPessoaisValidos
@fc/test-utils/contratos-privacidade-fixtures	Valores usados pelo sanitizador e pela cerca de privacidade
@fc/test-utils/htmlFormatado/corpusCanonico	CORPUS_HTML_FORMATADO
@fc/test-utils/htmlFormatado/saidaCanonica	SAIDA_CANONICA_HTML_FORMATADO
@fc/test-utils/htmlFormatado/conteudo*	CONTEUDO_CHATGPT_HTML, CONTEUDO_GOOGLE_DOCS_HTML, CONTEUDO_LIBRE_OFFICE_HTML, CONTEUDO_WORD_HTML, um por arquivo

anonimizacao/padroes e anonimizacao/tipos saem pelo mesmo wildcard, mas são apoio interno dos dois módulos publicados.

Dois subpaths não são módulos a importar num teste, e sim arquivos de setupFiles do Vitest: @fc/test-utils/setup-sem-timers-orfaos, que reprova a suíte que deixa temporizador vivo, e @fc/test-utils/setup-relogio-na-virada, que desloca new Date() e Date.now() para um instante determinado, de onde o tempo segue correndo no ritmo real; sem esse instante, o setup não faz nada.

Fonte única de amostras

Todas as fontes versionadas ficam em src/amostras/, mesmo quando ainda possuem um único consumidor. A organização separa formato e domínio:

amostras/
├── calculos/
│   ├── prev-atrasados/*.calc
│   ├── prev-rpps/*.calc
│   └── prev-tc/*.calc
├── documentos/
│   ├── carta-concessao/*.txt
│   ├── cnis/*.txt
│   ├── rdctc/*.txt
│   ├── rdctc-glifos/*.pdf + *.json
│   ├── hiscre/*.txt
│   ├── pdf-fabrica/*.txt
│   ├── pje/*.txt
│   ├── planilha-google/*.txt
│   ├── plenus/*.txt
│   ├── prevjud/*.json
│   └── tempo/*.txt
├── calculos.ts
├── catalogoAmostras.ts
└── documentos.ts

Textos e arquivos .calc são mantidos no formato bruto. Todos os cálculos usam a extensão .calc, inclusive os antigos casos JSON; os módulos do catálogo interpretam o conteúdo em memória quando uma suíte ainda consome objetos. Documentos são agrupados pelo tipo, nunca pelo aplicativo consumidor. Dados tabulares exclusivos de um consumidor permanecem junto aos testes desse consumidor. Documentos JSON, como o PrevJud, preservam seu formato documental. JSONs criados apenas para envolver uma propriedade texto não são versionados. O export catalogoAmostras (em amostras/catalogoAmostras) oferece identificador, domínio e formato para inventário.

As fontes usam amostra-NNN.ext, com sequência independente e estável em cada pasta. Números removidos não são reutilizados; novas fontes recebem o número posterior ao maior existente. Identificadores descritivos são definidos nos módulos consumidores. Os CSVs que registravam o resultado do parser antigo não fazem parte do acervo: eram referências temporárias de volumetria e deixaram de representar um comportamento que precise ser preservado.

Resultados esperados e snapshots continuam junto ao consumidor. PDFs só são versionados quando o conteúdo foi substituído por valores sintéticos ou por sequências mínimas de glifos, sem fluxos de texto da origem, imagens, anotações, anexos ou metadados da origem. Cada PDF traz um manifesto JSON adjacente com procedência, revisão humana, hash SHA-256 e gabarito. O catálogo TypeScript continua restrito às fontes carregadas em memória; a cerca de privacidade descobre os binários e seus manifestos diretamente no acervo. Documentos reais e a cobertura ampla permanecem no corpus protegido fora do Git.

Geradores devem gravar novas fontes sob src/amostras/. A saída do gerador de arquivos .calc é apenas uma candidata a fixture: a sanitização estrutural remove campos conhecidos, metadados e credenciais, mas não prova anonimização de texto livre nem de chaves futuras. O timestamp exigido pelo envelope .calc é a exceção: permanece com um valor canônico neutro. Antes da escrita, o fluxo emite inventário sem valores, bloqueia identificador, e-mail ou credencial residual e exige que a origem seja declarada como sintética ou anonimizada com revisão humana. Datas e históricos semanticamente relevantes podem ser preservados, desde que cobertos por essa declaração. Conteúdo idêntico reaproveita a fonte canônica para que execuções repetidas não criem deriva.

A cerca central percorre os corpora previdenciários versionados e recusa CPF, NIT ou processo CNJ com dígito verificador válido, além de titular, número de benefício e código de autenticidade sem marcador de anonimização. Nos arquivos .calc, ela também inspeciona a estrutura para impedir identificadores em campos conhecidos, metadados, credenciais e timestamp não canônico. Para PDFs, ela exige manifesto de procedência revisada, declarações de remoção e hash idêntico ao binário; o teste do domínio decodifica o conteúdo e repete a procura por identificadores válidos.

Testes de paridade web/API verificam que duas superfícies calculam os mesmos campos, mas não validam o resultado jurídico. Casos de ouro registram valores esperados e fonte de validação separadamente no pacote do domínio.

Critério para código novo

Um recurso só deve entrar aqui se não conhecer regras de um pacote específico. Se importar tipos ou classes de um domínio para construir cenários, comparar resultados ou gerar testes, deve ficar em tests/ desse pacote e, quando necessário, ser exposto por um subpath explicitamente identificado como suporte de testes.

Comandos

pnpm --filter @fc/test-utils lint
pnpm --filter @fc/test-utils typecheck
pnpm --filter @fc/test-utils test:run