Teste com golden file

Spec: ISO/IEC/IEEE 29119-4 Spec: ISO/IEC 25010 Evidence: Test-backed

Visão geral

Um golden file é um registro de “esta é a aparência da saída correta” contra o qual um teste compara a cada execução. O NextPDF usa goldens para detectar alterações que ninguém pretendia fazer: um stream (fluxo de bytes) comprimido de outra forma, um parágrafo que se moveu ou uma coordenada que desviou. Esta página explica como isso funciona e como um golden continua confiável, em vez de virar uma referência desatualizada que ninguém lê.

Por que isso importa

A geração de PDF é um pipeline longo, com muitos pontos em que desvios podem surgir silenciosamente. Uma refatoração que “não muda nada” pode reordenar operadores sem alarde, alterar uma matriz de transformação ou deslocar uma célula de tabela por uma quantidade minúscula. Testes de unidade raramente detectam isso: eles verificam um valor que você pensou em checar, não os milhares de bytes que você não checou. Técnicas baseadas em estrutura e técnicas baseadas em especificação detectam erros diferentes, e nenhuma engloba a outra (ISO/IEC/IEEE 29119-4, Annex A). Um golden file é a especificação por exemplo que fixa a saída inteira, não apenas uma asserção.

O risco existe nos dois sentidos. Um golden rígido demais falha a cada mudança inofensiva e acaba sendo revalidado cegamente até não provar mais nada. Um golden frouxo demais deixa passar regressões reais. Acertar esse equilíbrio é a parte difícil.

A versão resumida

Um golden file é uma saída de referência fixada, gerada a partir de um comportamento do motor reconhecidamente correto e versionada no repositório.
Um teste golden gera a saída novamente e a compara (diff) com a referência fixada; qualquer diferença reprova o teste e exige uma decisão humana.
O NextPDF compara no nível que é significativo, mas estável: texto extraído e operadores estruturais normalizados, não bytes brutos, porque os bytes brutos carregam ruído (timestamps, ordenação de subconjuntos, compressão) que não é uma regressão.
Atualizar um golden é um ato deliberado e revisado, controlado por um interruptor explícito GOLDEN_UPDATE — nunca um “aceitar qualquer coisa que tenha mudado” automático.
O golden difere do teste de snapshot e do teste de caracterização de uma forma decisiva: um golden nunca é atualizado automaticamente.

Como o NextPDF aborda o tema

A infraestrutura de golden do motor usa um diff de duas camadas explícito, em vez de uma comparação de bytes:

Generate Render the fixture input through the current engine.
Layer 1 — text Extract human-readable text from the content stream; diff against the text golden. Catches dropped or reordered content and encoding regressions.
Layer 2 — structure Extract ordered PDF operators, normalise coordinates to a fixed precision, diff against the operator golden. Catches layout shifts and broken structure.
Decide Any diff fails the test; a human judges whether it is a regression or an intended change.

Como uma comparação golden do NextPDF é executada: gere o PDF, extraia as camadas significativas (texto e, em seguida, operadores estruturais normalizados), compare cada uma com a referência fixada e reprove com um relatório legível por humanos em qualquer diferença.

O que ele deliberadamente não compara é tão importante quanto o que ele compara. A saída em bytes brutos fica fora porque timestamps, ordenação de subconjuntos de fontes e compressão de streams a tornam frágil sem torná-la mais correta. A comparação de imagens em nível de pixel fica fora deste nível porque exige um renderizador externo e traz variações do ambiente para o teste. As coordenadas de ponto flutuante são normalizadas para uma precisão fixa, de modo que ruídos de arredondamento sem significado não se disfarcem de regressão. Essa é a diferença entre um golden que testa o comportamento e um que testa ruído ambiental transitório.

Essa escolha também dá nome ao perfil de reprodutibilidade da página: estrutural. O NextPDF documenta três perfis — bitwise (os bytes exatos se reproduzem), structural (o grafo de objetos e a sequência de operadores se reproduzem, permitindo variações benignas no nível dos bytes) e semantic (o significado se reproduz). Os testes golden neste nível verificam o perfil estrutural por construção. É por isso que suas referências sobrevivem a uma atualização da biblioteca de compressão, mas ainda assim reprovam uma tabela que se moveu.

O que as evidências dizem

Evidence: Test-backed A comparação em duas camadas (extração de texto e, em seguida, comparação de operadores estruturais normalizados) é a metodologia golden documentada do próprio motor, com comparação de bytes brutos, diff de imagem e ponto flutuante exato explicitamente fora de escopo pelas razões acima. A suíte golden é uma suíte de testes declarada e executável separadamente, distinta das suítes de snapshot e de caracterização.

Evidence: Test-backed O mecanismo que mantém os goldens honestos é concreto: as referências golden são artefatos gerados, não escritos à mão. Sobrescrevê-las é controlado por um interruptor de ambiente GOLDEN_UPDATE explícito, documentado como uma operação rara e sempre revisada. Em contraste, os testes de snapshot no motor são gerados novamente na primeira execução e reconhecem o desvio por meio de um flag de atualização. Já os testes de caracterização fixam o comportamento legado sem afirmar que ele está correto. As três são ferramentas intencionalmente diferentes.

Evidence: Standard-backed Um golden é uma especificação por exemplo. Spec: ISO/IEC/IEEE 29119-4, Annex A observa que técnicas baseadas em especificação e técnicas baseadas em estrutura capturam classes diferentes de erro, e que uma estratégia deve combiná-las. É por isso que os goldens ficam ao lado dos testes de unidade e estruturais, não no lugar deles, na pirâmide de testes.

Exemplo prático

Um teste golden é mecanicamente simples; a disciplina está no fluxo de trabalho em torno dele:

<?php

declare(strict_types=1);

// 1. The fixture: a fixed HTML input committed next to the test.
//    tests/Golden/fixtures/html-inputs/002-basic-table.html

// 2. The pinned references, generated once from known-good behaviour:
//    002-basic-table.text.golden       (Layer 1 — extracted text)
//    002-basic-table.operators.golden  (Layer 2 — normalised operators)

// 3. The run compares; ANY difference fails:
//    vendor/bin/phpunit --testsuite Golden

// 4. An intended behaviour change is the ONLY time references move,
//    and it is explicit and reviewed — never automatic:
//    GOLDEN_UPDATE=1 vendor/bin/phpunit --testsuite Golden
//
//    The regenerated *.golden files land in the diff of the same change
//    that altered behaviour, so a reviewer sees the output delta next to
//    the code delta and signs off on both together.

O exemplo é o processo. O código de teste apenas compara (diff). O que torna o golden confiável é que uma referência alterada é revisada como saída na mesma alteração que modificou o motor.

Equívoco comum

O erro mais comum é tratar o teste golden como um teste byte a byte. Os goldens do NextPDF não são os bytes do arquivo — são o texto extraído dele e seus operadores estruturais normalizados. Verificar bytes brutos falharia com uma nova versão do zlib, uma tag de subconjunto diferente ou um timestamp gerado novamente, nenhum dos quais é uma regressão. Em uma semana, o teste seria revalidado até se tornar inútil. (Quando os bytes exatos realmente precisam se reproduzir, esse é o perfil de reprodutibilidade bitwise, separado e mais rígido, não um golden.)

O segundo erro é supor que uma suíte golden verde prova a corretude. Ela prova a ausência de mudança. Um golden gerado a partir de uma saída com bug protege fielmente esse bug. Os goldens protegem contra regressões a partir de uma baseline reconhecidamente correta; eles não estabelecem que a baseline era boa. É para isso que servem os níveis de unidade, estrutural e de conformidade.

Limites e fronteiras

Um teste golden responde exatamente a uma pergunta: a saída mudou em relação à referência fixada? Ele não diz se a referência algum dia foi correta. Ele também não mede desempenho, conformidade ou segurança. Esses são outros níveis. O tamanho do corpus de fixtures, a taxa de aprovação da suíte e qualquer número de cobertura são sinais de qualidade vivos, gerados a partir de artefatos de integração contínua e publicados com o build. Eles intencionalmente não são declarados aqui, onde poderiam ficar desatualizados.

O layout exato dos diretórios, os detalhes internos do comparador e o interruptor de atualização pertencem à infraestrutura de testes do motor e podem evoluir. A configuração de testes é a autoridade caso algum dia discorde desta explicação. Esta página não faz nenhuma afirmação sobre ferramentas de snapshot ou golden de qualquer outra biblioteca.

Documentos relacionados

A pirâmide de testes do NextPDF — onde o nível golden se encaixa entre os cinco e o que ele prova de forma única.
Teste de mutação, explicado — como o NextPDF verifica que seus testes, incluindo os goldens, de fato detectam falhas.
Tipos estritos, em todos os lugares — a análise estática que remove uma classe de defeitos antes mesmo de qualquer golden ser executado.

Glossário

Golden file — uma saída de referência fixada, gerada a partir de um comportamento do motor reconhecidamente correto e versionada, contra a qual um teste compara (diff) a cada execução. Nunca atualizada automaticamente.
Diff de duas camadas — a comparação golden do NextPDF: texto extraído (Camada 1) mais operadores estruturais normalizados (Camada 2), em vez de bytes brutos.
Teste de snapshot — uma técnica relacionada, mas distinta, em que a referência é gerada novamente na primeira execução e o desvio é reconhecido por meio de um flag de atualização.
Teste de caracterização — um teste que fixa o comportamento existente sem afirmar que ele está correto, normalmente para tornar uma refatoração segura.
Perfil de reprodutibilidade — o nível no qual a saída deve se reproduzir: bitwise (bytes exatos), structural (grafo de objetos e sequência de operadores, com variação benigna de bytes permitida) ou semantic (significado). Os testes golden aqui verificam o perfil estrutural.
GOLDEN_UPDATE — o interruptor de ambiente explícito que autoriza a sobrescrita das referências golden; uma operação rara e revisada.