dbt test Command

The dbt test command executes all tests defined in your project and reports which ones pass and which ones fail. Understanding how to run tests effectively — selecting subsets, reading output, and acting on failures — makes your data pipeline more reliable.

Basic Usage

dbt test

This runs every test in the project: generic tests from YAML files and singular tests from the tests/ folder. dbt executes them against your current target environment.

Selection Flags

The --select flag controls which tests run. It uses the same node selection syntax as dbt run.

Run tests for one model

dbt test --select stg_orders

Run tests for a model and all its parents

dbt test --select +fct_orders

Run tests for all models in a folder

dbt test --select staging

Run only a specific test type

dbt test --select test_type:not_null
dbt test --select test_type:unique
dbt test --select test_type:singular
dbt test --select test_type:generic

Run source tests only

dbt test --select source:ecommerce
dbt test --select source:ecommerce.orders

Run tests with a specific tag

dbt test --select tag:finance
dbt test --select tag:daily

Understanding Test Output

$ dbt test --select stg_orders

Running with dbt=1.8.3
Found 6 tests for stg_orders

1 of 6 START test not_null_stg_orders_order_id ......... [RUN]
1 of 6 PASS  test not_null_stg_orders_order_id ......... [PASS in 0.2s]

2 of 6 START test unique_stg_orders_order_id ........... [RUN]
2 of 6 PASS  test unique_stg_orders_order_id ........... [PASS in 0.3s]

3 of 6 START test not_null_stg_orders_customer_id ..... [RUN]
3 of 6 PASS  test not_null_stg_orders_customer_id ..... [PASS in 0.2s]

4 of 6 START test relationships_stg_orders_customer_id  [RUN]
4 of 6 FAIL  test relationships_stg_orders_customer_id  [FAIL 3 in 0.4s]

5 of 6 START test accepted_values_stg_orders_status ... [RUN]
5 of 6 WARN  test accepted_values_stg_orders_status ... [WARN 1 in 0.3s]

6 of 6 START test not_null_stg_orders_amount_dollars .. [RUN]
6 of 6 PASS  test not_null_stg_orders_amount_dollars .. [PASS in 0.2s]

Done. PASS=4 WARN=1 ERROR=1 SKIP=0 TOTAL=6

Reading the Summary Line

Done. PASS=4 WARN=1 ERROR=1 SKIP=0 TOTAL=6

PASS  = tests that returned zero failure rows
WARN  = tests that found issues but severity is set to 'warn'
ERROR = tests that found issues and severity is 'error' (default)
SKIP  = tests skipped because an upstream model failed
TOTAL = total tests attempted

Finding the Failing SQL

dbt compiles every test into SQL and stores it in target/compiled/. When a test fails, find and run that SQL in your warehouse:

# Find the compiled test SQL
cat target/compiled/my_project/models/staging/schema.yml/
    relationships_stg_orders_customer_id.sql

# Paste that SQL into your warehouse query editor to see failing rows

Storing Test Failures as Tables

Configure dbt to write failing rows into warehouse tables for easier investigation:

# dbt_project.yml
tests:
  +store_failures: true
  +store_failures_as: table
  +schema: test_failures

After a failing test, query the failures table:

select * from test_failures.relationships_stg_orders_customer_id

Excluding Tests

# Run everything except one model's tests
dbt test --exclude stg_products

# Run everything except a specific tag
dbt test --exclude tag:slow

Running dbt test in CI/CD

In a CI/CD pipeline (GitHub Actions, GitLab CI, etc.), run tests after every code change to catch regressions before merging:

# Example CI step
- name: Run dbt tests
  run: |
    dbt deps
    dbt build --target ci
    # dbt build runs models + tests together
    # exit code is non-zero if any ERROR-severity test fails
    # the CI pipeline fails and blocks the merge

Exit Codes

Exit code 0  →  All tests passed (or only warnings)
Exit code 1  →  One or more ERROR-severity tests failed
Exit code 2  →  dbt encountered a runtime error (not a test failure)

CI systems use the exit code to determine whether to block a deployment or merge.

dbt build vs dbt test

dbt test          Runs tests only, does not run or rebuild models
dbt build         Runs models + tests + seeds + snapshots in DAG order
                  Stops downstream work if a test fails

Use dbt build in scheduled production runs. Use dbt test during development when you want to check tests without rerunning all models.