dbt Tests: A Practical Guide

Kumaran C.S

7 min read

·

Oct 8, 2026

--

Listen

Share

Press enter or click to view image in full size

dbt tests are SQL queries that look for problems. A test passes when it returns zero rows and fails when it returns any.

There are two main kinds:

• Generic tests: reusable, configured in .yml files
• Singular tests: custom SQL files for one-off checks

Note: in dbt 1.8 and later, the preferred key is data_tests:. The older tests: key still works. Use whichever your version supports, but stay consistent.

There is also a third kind, unit tests (dbt 1.8+), covered later in this guide. They test your transformation logic on small mocked inputs, rather than checking the real data.

1. Generic tests (built in)

dbt ships with four:

Press enter or click to view image in full size

# models/staging/shop/_shop__models.yml
version: 2

models:
  - name: stg_shop__orders
    columns:
      - name: order_id
        data_tests:
          - unique
          - not_null
      - name: status
        data_tests:
          - accepted_values:
              values: ['placed', 'shipped', 'returned', 'cancelled']
      - name: customer_id
        data_tests:
          - not_null
          - relationships…