Test and document your project

Add tests to your models

Adding tests to a project helps validate that your models are working correctly. So let's add some tests to our project!

  1. Create a new YAML file in the models directory, named models/schema.yml
  2. Add the following contents to the file:
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
  1. Execute dbt test, and confirm that all your tests passed.
Passing tests when using dbt Cloud
Passing tests when using dbt Cloud

FAQs

 What tests are available for me to use in dbt? Can I add my own custom tests?
 How do I test one model at a time?
 One of my tests failed, how can I debug it?
 Does my test file need to be named `schema.yml`?
 Do all my tests go in one file?
 What tests should I add to my project?
 When should I run my tests?

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.
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']
  1. [dbt CLI only] Execute 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.
  2. [dbt CLI only] Execute dbt docs serve to launch the documentation in a local website.

FAQs

 How do I write long-form explanations in my descriptions?
 How do I share my documentation with my team members?

Extra exercises

  • 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.