O Que É um Golden File?
Um golden file é uma referência versionada da saída esperada contra a qual um teste compara sua saída real.
Quando uma função produz uma saída grande ou complexa, como código gerado, um documento renderizado ou uma estrutura serializada, escrever asserções à mão é tedioso e frágil. O teste com golden file armazena uma versão conhecida como boa dessa saída como um arquivo no repositório, e então falha o teste se a nova saída diferir. É a mesma ideia por trás do snapshot testing.
Como golden files funcionam
Você roda o código uma vez, inspeciona a saída cuidadosamente e a salva como o golden file. Execuções posteriores regeram a saída e fazem o diff contra o golden. Uma correspondência passa; uma divergência falha e mostra o diff, levando você a corrigir o código ou, se a mudança for intencional, atualizar o golden.
Golden file versus snapshot
Os conceitos se sobrepõem bastante. "Golden file" é o termo mais antigo e neutro em relação a linguagem, comum em Go e em testes de sistemas, enquanto "snapshot" é a versão gerenciada por framework popularizada pelo ferramental JavaScript. Ambos comparam a saída atual a uma baseline armazenada; snapshots apenas automatizam o gerenciamento do arquivo.
Um exemplo rápido
Um teste lê o golden file e afirma que a saída gerada corresponde a ele exatamente, com uma flag de update para regerá-lo deliberadamente.
want := readFile("testdata/output.golden")
got := Generate(input)
if got != want { t.Errorf("mismatch") }Armadilhas a evitar
- Atualizar goldens por reflexo sem ler o diff.
- Goldens tão grandes que nenhum revisor consegue verificá-los.
- Saída não determinística (timestamps, ordenação) causando diffs falsos.
- Tratar uma mudança de golden como trivial em vez de revisá-la.
Golden files no CI
No CI o golden file é somente-leitura: o pipeline deve falhar em uma divergência, nunca regerá-la silenciosamente. Manter a saída determinística, fazendo stub de relógios e ordenando coleções, previne diffs falsos. Rodar essas comparações em runners rápidos mantém ágil até mesmo suítes grandes de golden.
Principais conclusões
- Um golden file é uma baseline versionada da saída esperada.
- Os testes fazem o diff da saída real contra ele, como o snapshot testing.
- No CI o golden é somente-leitura; revise toda mudança de golden.