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!
- dbt Cloud
- dbt CLI
- Create a new YAML file in the
models
directory, namedmodels/schema.yml
- Add the following contents to the file:
models/schema.yml
version: 2models:- name: customerscolumns:- name: customer_idtests:- unique- not_null- name: stg_customerscolumns:- name: customer_idtests:- unique- not_null- name: stg_orderscolumns:- name: order_idtests:- unique- not_null- name: statustests:- accepted_values:values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']- name: customer_idtests:- not_null- relationships:to: ref('stg_customers')field: customer_id
- Execute
dbt test
, and confirm that all your tests passed.
info
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?
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?
Why do model and source yml files always start with `version: 2`?
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.
- dbt Cloud
- dbt CLI
- Update your
models/schema.yml
file to include some descriptions, such as those below.
models/schema.yml
version: 2models:- name: customersdescription: One record per customercolumns:- name: customer_iddescription: Primary keytests:- unique- not_null- name: first_order_datedescription: NULL when a customer has not yet placed an order.- name: stg_customersdescription: This model cleans up customer datacolumns:- name: customer_iddescription: Primary keytests:- unique- not_null- name: stg_ordersdescription: This model cleans up order datacolumns:- name: order_iddescription: Primary keytests:- unique- not_null- name: statustests:- accepted_values:values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
- 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. - [CLI] Execute
dbt docs serve
to launch the documentation in a local website. [Cloud] Click the link above the file tree in the develop interface to launch documentation in a new tab.
tip
Great work ⭐️! You've just built your first dbt project that's tested and documented!
FAQs
How do I write long-form explanations in my descriptions?
How do I share my documentation with my team members?
Extra exercises
- dbt Cloud
- dbt CLI
- 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.