dbt Unit Test: teste a lógica SQL antes de materializar

ANÁLISE EDITORIAL

Um teste de dados costuma perguntar se a tabela pronta contém nulos, duplicatas ou valores fora da regra. A Skill dbt Unit Test trabalha antes disso: ajuda um agente a isolar a lógica SQL de um modelo, fornecer entradas pequenas e controladas e comparar a saída com um resultado esperado antes de materializar o modelo completo. É uma forma prática de testar regras de transformação, desde que o agente trabalhe em desenvolvimento, use fixtures sintéticas e não trate comandos potencialmente destrutivos como simples preparação.

O que esta Skill faz

A adding-dbt-unit-test ensina um agente a criar definições YAML de testes unitários para modelos dbt. O fluxo identifica o modelo SQL, mapeia cada dependência direta usada por ref() ou source(), constrói dados simulados em given e descreve a saída esperada em expect. Depois, orienta a execução seletiva do teste e a leitura da diferença entre resultado real e esperado.

O foco é a lógica da transformação, não a qualidade de todo o conjunto de dados. Casos como expressões regulares, datas, janelas, ramificações case when, truncamento, correções de bugs e regras críticas de negócio tendem a aproveitar melhor o método. A documentação oficial do dbt sobre testes unitários faz a mesma distinção: entradas estáticas permitem validar SQL antes da materialização completa.

Para quem serve

A Skill serve a profissionais de analytics engineering, engenharia de dados e desenvolvimento que já mantêm um projeto dbt e querem usar um agente para preparar testes reproduzíveis. Também ajuda revisores que recebem uma mudança de modelo e precisam transformar exemplos de negócio em casos de teste explícitos, em vez de conferir manualmente uma tabela grande.

Ela é especialmente útil quando a equipe sabe qual comportamento deseja proteger, mas ainda não escreveu o YAML. Não substitui a pessoa que define a regra de negócio, escolhe os casos-limite e confirma se a saída esperada está correta. Um agente pode produzir um teste perfeitamente válido que apenas cristaliza uma premissa errada.

Origem e curadoria

A origem é o repositório oficial dbt-labs/dbt-agent-skills, mantido pela organização dbt Labs. Em 11/09/2026, a API pública do GitHub registrava 709 estrelas, repositório público, não arquivado e licença Apache-2.0. O número pertence à coletânea inteira, não mede adoção isolada desta pasta. Como está abaixo do piso editorial de 1.000 estrelas, a entrada foi aceita somente pela exceção de projeto oficial, sem alegação de popularidade.

A auditoria fixou o commit 540d7d55704421e287e40cd3ab302826ecdb0ef3 e leu o diretório completo da Skill. A pesquisa por nome e caminho em GitHub, GitLab e Hugging Face não encontrou uma origem canônica alternativa. O inventário do Bastidores não encontrou o repositório, a pasta, o pacote, o nome nem uma página com a mesma finalidade.

Compatibilidade e pré-requisitos

O arquivo segue o formato de SKILL.md e pode ser carregado por agentes compatíveis com a especificação Agent Skills. O repositório documenta instalação para clientes diferentes, mas a compatibilidade real depende de cada cliente aceitar Skills e permitir leitura e edição do projeto. O pacote do Bastidores não instala um cliente.

Para executar o que a Skill propõe, você precisa de um projeto dbt configurado, com dbt_project.yml, modelos SQL no projeto atual, perfil ou conexão de desenvolvimento válida e o adaptador adequado ao warehouse. A documentação oficial informa que testes unitários estão disponíveis desde dbt v1.8. O recurso cobre modelos SQL do projeto atual e não suporta materialized views, SQL recursivo nem consultas introspectivas.

As definições devem ficar em um arquivo YAML dentro de um caminho de modelos, normalmente models/. O diretório tests/ é reservado aos data tests. Junções exigem nomes de tabela com alias, e todas as referências diretas precisam aparecer como entradas simuladas para evitar falhas de compilação.

Instalação com revisão

O download local desta página contém 16 arquivos textuais: SKILL.md, treze referências Markdown, LICENSE e ORIGEM.md. Compare o SHA-256 informado no final da página, extraia em uma pasta de revisão e leia o conteúdo antes de copiar dbt-unit-test para o diretório de Skills aceito pelo seu agente. O ZIP não instala dbt, adaptadores ou dependências e não executa comandos.

Se preferir a origem, clone o repositório, faça checkout do commit auditado e copie somente a pasta indicada. Não aponte um ambiente controlado diretamente para main, pois o ramo pode mudar depois desta curadoria. O arquivo tile.json da coletânea declara versão 1.3.1, enquanto o SKILL.md desta unidade não declara versão própria.

Configure o uso antes do primeiro pedido

Defina ao agente qual projeto pode ser lido, quais arquivos podem ser alterados, qual alvo dbt é permitido e se comandos estão autorizados. Uma regra segura é permitir inicialmente apenas a criação ou edição do YAML e exigir revisão humana do diff antes de qualquer dbt test, dbt run ou dbt build. Não coloque senha de warehouse, token ou conteúdo de profiles.yml no prompt.

Peça fixtures sintéticas e mínimas. A própria Skill recomenda começar pelo formato dict, que permite declarar somente as colunas relevantes. Caso seja necessário observar dados existentes com dbt show, remova informações pessoais ou confidenciais antes de convertê-las em fixture. Uma amostra copiada de produção pode virar um vazamento persistente no Git.

Primeiro uso seguro

Um pedido inicial útil seria: “Use dbt Unit Test para propor testes do modelo dim_clientes. Leia apenas o modelo, seu YAML e as dependências diretas. Crie fixtures sintéticas para e-mail válido, domínio desconhecido e entrada sem arroba. Não execute dbt e mostre o diff para aprovação”. Isso limita o agente à preparação documental e deixa o primeiro efeito externo sob controle humano.

Depois de revisar o YAML, execute o teste por nome ou use o seletor test_type:unit. A referência do comando dbt test explica que o comando roda testes definidos no projeto. Quando você usa dbt build, o fluxo ordena recursos do DAG e pode executar o teste unitário, materializar o modelo e então rodar data tests. Essa abrangência merece uma seleção precisa.

Estrutura mínima do teste

Uma definição contém name, model, uma lista given para as entradas e um bloco expect para a saída. A referência oficial da propriedade unit_tests é a fonte adequada para chaves, configurações e formatos atuais. A Skill inclui exemplos para dict, CSV e SQL, além de fixtures externas.

Comece pequeno. Cada linha simulada deve existir para provar uma regra ou um limite. Se o caso envolve uma expressão case, inclua ao menos uma entrada para cada ramo significativo e uma para o comportamento padrão. Se envolve data, escolha bordas como mudança de mês ou fuso quando elas realmente participam da lógica. Quantidade de linhas não é cobertura por si só.

Unit test não é data test

O teste unitário compara a saída da lógica SQL com uma saída esperada a partir de entradas controladas. O data test consulta dados já existentes para localizar violações, como nulos ou duplicatas. A página oficial de data tests descreve essa segunda função. Os dois tipos se complementam e não devem ser apresentados como substitutos.

Uma transformação pode passar em fixtures bem escolhidas e ainda receber dados inválidos em produção. Também pode passar em data tests genéricos enquanto calcula uma classificação incorreta. Use testes unitários para lógica conhecida e data tests para propriedades dos conjuntos materializados.

O alerta crítico sobre –empty

Os pais diretos do modelo precisam existir no warehouse para determinados fluxos de teste. A Skill orienta verificar as relações e, quando necessário, construir versões sem linhas com dbt run --empty. Ela também traz um aviso claro: esse comando pode substituir modelos existentes por versões com esquema e zero linhas. Não execute em uma relação que contenha dados a preservar.

Trate --empty como mudança de estado. Confirme o alvo, a seleção, o ambiente e o impacto antes de autorizar. Prefira um schema de desenvolvimento isolado. A documentação do dbt run deve ser consultada para o comportamento atual do comando. Em muitos casos, dbt build --select modelo é o fluxo recomendado, mas ele também materializa recursos e não deve ser disparado às cegas.

Casos especiais cobertos

As referências incluídas tratam modelos incrementais, dependências efêmeras, modelos versionados e sobrescrita de macros, variáveis de projeto ou variáveis de ambiente. Para modelos incrementais, a saída esperada representa o que seria inserido ou mesclado, não o estado final completo da tabela. A Skill também explica que uma dependência efêmera precisa usar entrada no formato SQL.

Há notas específicas para BigQuery, Redshift, Postgres, Snowflake e Spark. Isso importa porque tipos e estruturas não se comportam de forma idêntica. BigQuery exige todos os campos de um STRUCT na fixture. A documentação ainda registra restrições próprias de Redshift. Não copie um exemplo de outro adaptador sem conferir a referência correspondente.

Resultado esperado

O resultado saudável é um arquivo YAML pequeno, legível e associado ao modelo certo, com entradas suficientes para reproduzir a regra, saída esperada revisada e comando seletivo documentado. Antes da execução, o diff deve mostrar somente os arquivos autorizados. Depois, o log deve identificar o teste pelo nome e terminar com código 0 para passagem ou 1 para falha.

Uma falha é útil quando a diferença mostra exatamente qual valor real divergiu do esperado. Corrija a lógica ou a expectativa com base na regra de negócio, não apenas para tornar a execução verde. Preserve o caso que revelou o defeito para evitar regressão futura.

Permissões e riscos

Os 16 arquivos do pacote são texto e não agem sozinhos. Quando carregada por um agente com ferramentas, a Skill pode levar à leitura de SQL, criação ou edição de YAML e execução de comandos que consultam ou alteram relações no warehouse. O custo e o alcance dependem do seletor, do alvo e do adaptador configurado.

Use menor privilégio, schema de desenvolvimento, seleção explícita e revisão do diff. Nunca entregue credenciais no prompt ou no repositório. Não permita que o agente escolha produção por conveniência. Fixtures devem ser sintéticas ou anonimizadas, e o log de teste não deve ser publicado se contiver nomes internos, SQL confidencial ou dados de clientes.

Erros comuns e como corrigir

Node not found durante a compilação

Inclua em given toda dependência direta referenciada pelo modelo. Confira nomes, pacotes e versões. Para uma fonte, use a forma indicada pela referência da Skill.

O YAML foi salvo em tests/

Mova a definição para um arquivo YAML dentro de model-paths, normalmente models/. O diretório tests/ é usado por data tests e fixtures, não para descobrir a propriedade unit_tests.

A junção não compila

Confirme que os nomes de tabela receberam alias no SQL testado. Essa é uma exigência documentada para testar lógica de join.

A relação upstream não existe

Verifique a relação no ambiente de desenvolvimento. Se a equipe autorizar uma versão sem linhas, revise cuidadosamente a seleção antes de usar --empty. Não aplique o comando sobre dados que devam permanecer.

O teste passa, mas não protege a regra

Revise cada fixture e associe-a a um ramo ou limite concreto. Adicione o caso que já falhou em produção e não use apenas exemplos felizes.

Tipos diferem entre adaptadores

Abra a referência específica de BigQuery, Redshift, Postgres, Snowflake ou Spark. Ajuste literais e estruturas ao mecanismo configurado, sem inventar equivalência.

O que a revisão editorial confirmou

A pasta auditada contém um SKILL.md e treze referências Markdown. Não há scripts, executáveis, binários ou dependências nessa unidade. A licença Apache-2.0 permite redistribuição com a licença e os avisos preservados. O pacote do Bastidores mantém os arquivos sem modificar seu conteúdo e acrescenta somente ORIGEM.md.

A revisão comparou a orientação com a documentação oficial do dbt atualizada em 10/09/2026. Confirmamos a disponibilidade desde v1.8, as limitações de modelos SQL, a localização do YAML, os formatos de fixture, o seletor test_type:unit e o risco de --empty. Não executamos a Skill em um warehouse, não validamos todos os adaptadores e não certificamos um projeto dbt.

Quando não usar

Não use esta Skill para testar materialized views, SQL recursivo, consultas introspectivas ou modelos de outro projeto, pois esses cenários estão fora do suporte descrito. Também não a use como licença para explorar dados de produção, copiar linhas reais para fixtures ou executar builds amplos sem autorização.

Para verificar nulos, unicidade, relacionamentos ou regras sobre dados já materializados, comece com data tests. Para desempenho de warehouse, custo, segurança de acesso ou revisão completa de arquitetura, use processos específicos. Um unit test bem escrito cobre uma regra de transformação, não todo o sistema.

Versão, licença e pacote auditado

Origem: dbt-labs/dbt-agent-skills, pasta skills/dbt/skills/adding-dbt-unit-test, commit 540d7d55704421e287e40cd3ab302826ecdb0ef3, licença Apache-2.0. A coletânea declara versão 1.3.1; a Skill não declara versão própria. O pacote local contém 16 arquivos textuais, tem 20.583 bytes e SHA-256 a45e2e882cca0efd60374d3fcbdc56a2a6667d6b52443acd520e3aeedcaa63b7.

O botão de download entrega o espelho documental auditado. O botão do repositório abre a origem oficial em nova aba. São ações distintas. O ZIP não inclui dbt, adaptador, Python, warehouse, projeto de usuário, perfil, SQL privado, dados, resultados, executáveis nem credenciais.

Checklist antes de executar

• Fixei o commit e conferi os 16 arquivos do pacote.
• Estou em um projeto dbt e em um alvo de desenvolvimento autorizado.
• O YAML ficará dentro de model-paths.
• Mapeei todas as dependências diretas do modelo.
• Usei fixtures sintéticas e removi dados sensíveis.
• Associei cada linha a uma regra ou caso-limite.
• Revisei o diff antes de permitir comandos.
• Limitei a execução por nome ou seletor explícito.
• Não autorizarei --empty sobre relações com dados a preservar.
• Conferi a referência do adaptador usado.

Fontes oficiais consultadas

• SKILL.md fixado no GitHub.
• Referências oficiais incluídas na Skill.
• Licença Apache-2.0 do repositório.
• dbt Developer Hub: testes unitários.
• dbt Developer Hub: referência de unit_tests.
• dbt Developer Hub: data tests.
• dbt Developer Hub: dbt build.
• dbt Developer Hub: dbt test.