Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt
View on GitHubFebruary 1, 2026
Select agents to install to:
npx add-skill https://github.com/dbt-labs/dbt-agent-skills/blob/main/skills/adding-dbt-unit-test/SKILL.md -a claude-code --skill adding-dbt-unit-testInstallation paths:
.claude/skills/adding-dbt-unit-test/# Add unit test for a dbt model
## What are unit tests in dbt
In software programming, unit tests validate small portions of your functional code, and they work much the same way in dbt. dbt unit tests allow you to validate your SQL modeling logic on a small set of static inputs _before_ you materialize your full model in production. dbt unit tests enable test-driven development, benefiting developer efficiency and code reliability.
Unit tests allow enforcing that all the unit tests for a model pass before it is materialized (i.e. dbt won't materialize the model in the database if *any* of its unit tests do not pass).
## When to use
You should unit test a model:
- Adding Model-Input-Output scenarios for the intended functionality of the model as well as edge cases to prevent regressions if the model logic is changed at a later date.
- Verifying that a bug fix solves a bug report for an existing dbt model.
More examples:
- When your SQL contains complex logic:
- Regex
- Date math
- Window functions
- `case when` statements when there are many `when`s
- Truncation
- Complex joins (multiple joins, self-joins, or joins with non-trivial conditions)
- When you're writing custom logic to process input data, similar to creating a function.
- Logic for which you had bugs reported before.
- Edge cases not yet seen in your actual data that you want to be confident you are handling properly.
- Prior to refactoring the transformation logic (especially if the refactor is significant).
- Models with high "criticality" (public, contracted models or models directly upstream of an exposure).
## When not to use
Cases we don't recommend creating unit tests for:
- Built-in functions that are tested extensively by the warehouse provider. If an unexpected issue arises, it's more likely a result of issues in the underlying data rather than the function itself. Therefore, fixture data in the unit test won't provide valuable information.
- common SQL spec