ServicesAboutNotesContact Get in touch →
EN FR
Note

dbt Unit Testing Implementation

Hub note for implementing dbt unit tests — from YAML syntax and mocking patterns to BigQuery workarounds and CI/CD integration.

Planted
dbtbigquerytesting

dbt introduced native unit testing in version 1.8 (May 2024). This hub covers implementation: syntax, mocking patterns, BigQuery-specific issues, project organization, and CI/CD integration. For where unit tests fit in the overall testing approach, see testing strategy hub. For which models warrant unit tests, see dbt Unit Tests When to Write Them.

Prerequisites

Reading Order

1. dbt Unit Test YAML Syntax The complete reference for writing unit test YAML: required elements (name, model, given, expect), the three input formats (dict, csv, sql), optional configuration (tags, meta, enabled), and version-specific features across dbt 1.8, 1.9, and 1.11.

2. dbt Unit Tests BigQuery Workarounds BigQuery-specific gotchas that will trip you up: STRUCT fields must be complete, ARRAY comparisons fail with standard equality, column_transformations with to_json_string(), slot cost implications, and a troubleshooting table for the most common errors.

3. dbt Unit Test Mocking Dependencies How to mock everything your model touches: multiple refs and sources, macro overrides for deterministic timestamps, variable overrides for threshold testing, and the this keyword pattern for testing incremental merge logic.

4. dbt Unit Test File Organization Where to put test files (_unit_tests.yml co-located with models), external CSV fixtures, naming conventions (test_<model>_<scenario>), and why unit tests concentrate in the mart layer.

5. dbt Unit Test CLI Commands Running, filtering, and debugging unit tests from the command line. The test_type:unit selector, tag-based filtering, --debug for generated SQL inspection, and the --exclude-resource-type flag for production builds.

6. dbt Unit Test CI/CD Workflow A production-ready GitHub Actions workflow for BigQuery: unique datasets per CI run, the --empty flag for cost optimization, always-run cleanup, and the separation of unit tests (CI) from data tests (production).

The Decision Flow

Do I need unit tests at all?
    → [[dbt Unit Tests When to Write Them]]


Yes — how do I write one?
    → [[dbt Unit Test YAML Syntax]]


My model has complex dependencies
    → [[dbt Unit Test Mocking Dependencies]]


I'm on BigQuery and hitting errors
    → [[dbt Unit Tests BigQuery Workarounds]]


Where do the test files go?
    → [[dbt Unit Test File Organization]]


How do I run them in CI?
    → [[dbt Unit Test CI/CD Workflow]]

This hub covers the implementation fundamentals. The source article series continues with:

  • Part 2: Real-World Examples and Patterns — testing incremental models, snapshot logic, window functions, and marketing analytics patterns