# Tests

Tests in dex allow you to validate the quality and reliability of your data at every stage of the pipeline. They serve as guardrails that help catch issues like duplicates, nulls, invalid relationships, or any unexpected behavior before those issues impact downstream models, reports, or business decisions.

By embedding tests into your development workflow, you can ensure that your data is not only available—but also accurate, complete, and trustworthy.

### Why Tests Matter

Data can fail silently. A schema change in an external source, a missing join condition, or null values in a key column can propagate unnoticed through your entire stack. Tests help prevent that by making expectations about your data explicit and enforceable.

Tests are especially powerful in collaborative environments where multiple contributors are pushing changes. They provide confidence that your pipelines are working as intended and help reduce the risk of regressions.

### Supported Test Types

dex supports a flexible and extensible testing framework:

* **Generic tests**: Pre-built validations that you can apply to any column or model. These include:
  * `unique`: Ensures values in a column are distinct
  * `not_null`: Validates that a column contains no null values
  * `accepted_values`: Checks that a column only contains allowed values
  * `relationships`: Validates foreign key-like dependencies between models
* **dbt-expectations**: dex natively supports the [`dbt-expectations`](https://hub.getdbt.com/calogica/dbt_expectations/latest/) package, which provides advanced, expressive, data quality checks inspired by the Great Expectations framework. Examples include:
  * `expect_column_values_to_match_regex`
  * `expect_table_row_count_to_be_between`
  * `expect_column_stdev_to_be_between`
* **Custom tests**: You can also define your own test logic as standalone `.sql` files in the `tests/` directory. These can be used to encode business rules, edge cases, or other domain-specific validations.

{% hint style="info" %}
Don’t forget to install the required [Packages](/lakehouse-platform/develop-with-dex/packages.md) when using additional testing libraries.
{% endhint %}

### How to Create a Test

<figure><img src="/files/9TaBR0Hs5AYV5v1QkX2c" alt=""><figcaption><p>.yml file with tests</p></figcaption></figure>

Tests in dex are defined in `.yml` files alongside your models. Here's a step-by-step guide:

1. In your `models/` directory, locate or create a YAML file (e.g. `my_model.yml`).
2. Register the model and define the tests using the structure below:

```yaml
version: 2

models:
  - name: customers
    description: "Customer dimension table"
    columns:
      - name: customer_id
        description: "Primary key"
        tests:
          - not_null
          - unique

      - name: country
        description: "Customer country"
        tests:
          - accepted_values:
              values: ['US', 'CA', 'MX']
```

3. [Save and commit](/lakehouse-platform/version-control-with-git.md) your changes to the Git repository.

When the associated model is run, these tests will be executed automatically.

### Tests in Flows and Execution

Tests are tightly integrated into dex’s orchestration engine. Here's what happens during execution:

* When a model is run as part of a Flow, dex will automatically execute all registered tests associated with that model.
* If all tests pass, the flow proceeds to the next step or completes successfully.
* If any test fails, the entire flow will be marked as "Failed".
* Users will be notified through the Notification Center, allowing them to quickly identify, diagnose, and fix the issue.

{% hint style="info" %}
Tests are critical checkpoints. A failed test halts the flow, preventing broken or unvalidated data from propagating downstream.
{% endhint %}

### Best Practices

* Always test primary keys with `not_null` and `unique`
* Use `relationships` to enforce joins between tables (e.g., fact to dimension)
* Validate known business constraints with `accepted_values` or custom SQL
* Leverage dbt-expectations for expressive validations like distribution ranges, regex patterns, or row count checks
* Use descriptive `description` fields to clarify intent and purpose of tests


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dexlabs.io/lakehouse-platform/develop-with-dex/tests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.