Skip to main content

Test and document your project

Add tests to your models

Adding tests to a project helps validate that your models are working correctly.

To add tests to your project:

  1. Create a new YAML file in the models directory, named models/schema.yml

  2. Add the following contents to the file:

    models/schema.yml
    version: 2

    models:
    - name: customers
    columns:
    - name: customer_id
    tests:
    - unique
    - not_null

    - name: stg_customers
    columns:
    - name: customer_id
    tests:
    - unique
    - not_null

    - name: stg_orders
    columns:
    - name: order_id
    tests:
    - unique
    - not_null
    - name: status
    tests:
    - accepted_values:
    values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
    - name: customer_id
    tests:
    - not_null
    - relationships:
    to: ref('stg_customers')
    field: customer_id

  3. Run dbt test, and confirm that all your tests passed.

When you run dbt test, dbt iterates through your YAML files, and constructs a query for each test. Each query will return the number of records that fail the test. If this number is 0, then the test is successful.

FAQs

 What tests are available for me to use in dbt? Can I add my own custom tests?
 
 
 Does my test file need to be named `schema.yml`?
 
 
 

Document your models

Adding documentation to your project allows you to describe your models in rich detail, and share that information with your team. Here, we're going to add some basic documentation to our project.

  1. Update your models/schema.yml file to include some descriptions, such as those below.

    models/schema.yml
    version: 2

    models:
    - name: customers
    description: One record per customer
    columns:
    - name: customer_id
    description: Primary key
    tests:
    - unique
    - not_null
    - name: first_order_date
    description: NULL when a customer has not yet placed an order.

    - name: stg_customers
    description: This model cleans up customer data
    columns:
    - name: customer_id
    description: Primary key
    tests:
    - unique
    - not_null

    - name: stg_orders
    description: This model cleans up order data
    columns:
    - name: order_id
    description: Primary key
    tests:
    - unique
    - not_null
    - name: status
    tests:
    - accepted_values:
    values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']

  2. Run dbt docs generate to generate the documentation for your project. dbt introspects your project and your warehouse to generate a JSON file with rich documentation about your project.

  1. Click the link above the file tree in the Develop interface to launch documentation in a new tab.

FAQs

 
 

Next steps

Once you test and document your project, you're ready to Schedule a job.

Before moving on from testing, make a change and see how it affects your results:

  • Write a test that fails, for example, omit one of the order statuses in the accepted_values list. What does a failing test look like? Can you debug the failure?
  • Run the tests for one model only. If you grouped your stg_ models into a directory, try running the tests for all the models in that directory.
  • Use a docs block to add a Markdown description to a model.
0