用途:为 dbt SQL 模型编写单元测试,用静态输入验证建模逻辑,测试失败时 dbt 不会物化该模型。
主要能力:采用“模型—给定输入—预期输出”结构,可模拟 ref、source、seed 等上游节点数据,支持 dict(默认)、csv、sql 三种数据格式,支持 fixture 文件、增量模型、版本化模型、ephemeral 依赖及特殊覆盖场景。
使用方式:在 models 目录的 YAML 中定义 unit_tests,指定 model、given 输入与 expect 输出;输入用 ref('my_model') 或 source('schema','name') 引用。运行 dbt build --select hello_world 可先跑单元测试再物化;仅跑单元测试用 dbt test --select "hello_world,test_type:unit",或按名称 dbt test --select test_is_valid_email_address。建议仅在开发或 CI 运行,生产可用 --exclude-resource-type 或 DBT_EXCLUDE_RESOURCE_TYPES 排除。
适用场景:正则、日期运算、窗口函数、多条件 case、复杂 join、自定义处理逻辑、曾出缺陷的逻辑、边界情况、重构前及高关键性模型。
限制:仅支持当前项目的 SQL 模型;不支持 Python 模型、snapshot、seed、source、analysis 等非模型节点,不支持跨项目或包内模型、materialized view、递归 SQL、内省查询;增量模型不支持校验最终表状态。dict/csv 可只写相关列,sql 格式须提供全部列且是 ephemeral 依赖的唯一选择;不支持 Jinja。测试须放在 model-paths 的 YAML 中,fixture 放在 test-paths 的 fixtures 子目录。各仓库(BigQuery、Redshift、Postgres、Snowflake、Spark)存在特定注意事项与数据类型差异,需查阅对应参考文件。可用 config: enabled: false 禁用测试。失败时日志显示 actual differs from expected 及数据差异。