Skip to main content

Test selection examples

Test selection works a little differently from other resource selection. This makes it very easy to:

  • run tests on a particular model
  • run tests on all models in a subdirectory
  • run tests on all models upstream / downstream of a model, etc.

Like all resource types, tests can be selected directly, by methods and operators that capture one of their attributes: their name, properties, tags, etc.

Unlike other resource types, tests can also be selected indirectly. If a selection method or operator includes a test's parent(s), the test will also be selected. See below for more details.

▶Changelog

Test selection is powerful, and we know it can be tricky. To that end, we've included lots of examples below:

Direct selection​

▶Changelog

Run generic tests only:

Run singular tests only:

In both cases, test_type checks a property of the test itself. These are forms of "direct" test selection.

Indirect selection​

These are examples of "indirect" selection: customers and orders select models (whether by name or path). Any tests defined on either customers or orders will be selected indirectly, and thereby included.

By default, a test will run when ANY parent is selected; we call this "eager" indirect selection. In this example, that would include any test that touches either customers or orders, even if it touches other models as well.

It is possible to prevent tests from running if one or more of its parents is unselected, however; we call this "cautious" indirect selection. This can be useful in environments when you're only building a subset of your DAG, and you want to avoid test failures by tests that depend on unbuilt resources. (Another way to achieve this is with deferral).

With dbt test --indirect-selection=cautious (or setting indirect_selection: cautious in a yaml selector) tests will be indirectly selected only if ALL of its parents are included by the selection criteria. If any parent is missing, that test won't run. Note that test exclusion is always greedy: if ANY parent is explicitly excluded, the test will be excluded as well.

Imagine a relationships test between customers and orders. By default, the selection criteria above would select that test "eagerly." If you opt for "cautious" indirect selection instead, the relationships test would not be selected by the criteria above, because one of its parents is unselected. It would be selected indirectly only ("cautiously") if both parents are selected:

$ dbt test --select customers orders --indirect-selection=cautious

Syntax examples​

The following examples should feel somewhat familiar if you're used to executing dbt run with the --select option to build parts of your DAG:

The same principle can be extended to tests defined on other resource types. In these cases, we will execute all tests defined on certain sources via the source: selection method:

More complex selection​

Through the combination of direct and indirect selection, there are many ways to accomplish the same outcome. Let's say we have a data test named assert_total_payment_amount_is_positive that depends on a model named payments. All of the following would manage to select and execute that test specifically:

As long as you can select a common property of a group of resources, indirect selection allows you to execute all the tests on those resources, too. In the example above, we saw it was possible to test all table-materialized models. This principle can be extended to other resource types, too:

Note that this functionality may change in future versions of dbt.

Run tests on tagged columns​

Because the column order_id is tagged my_column_tag, the test itself also receives the tag my_column_tag. Because of that, this is an example of direct selection.

models/<filename>.yml
version: 2

models:
- name: orders
columns:
- name: order_id
tests:
tags: [my_column_tag]
- unique

Currently, tests "inherit" tags applied to columns, sources, and source tables. They do not inherit tags applied to models, seeds, or snapshots. In all likelihood, those tests would still be selected indirectly, because the tag selects its parent. This is a subtle distinction, and it may change in future versions of dbt.

Run tagged tests only​

This is an even clearer example of direct selection: the test itself is tagged my_test_tag, and selected accordingly.

models/<filename>.yml
version: 2

models:
- name: orders
columns:
- name: order_id
tests:
- unique:
tags: [my_test_tag]