diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md
index cf7b2b29a5a..7c182f1794d 100644
--- a/website/docs/reference/resource-properties/description.md
+++ b/website/docs/reference/resource-properties/description.md
@@ -14,6 +14,7 @@ description: "This guide explains how to use the description key to add YAML des
{ label: 'Analyses', value: 'analyses', },
{ label: 'Macros', value: 'macros', },
{ label: 'Data tests', value: 'data_tests', },
+ { label: 'Unit tests', value: 'unit_tests', },
]
}>
@@ -150,24 +151,81 @@ macros:
+You can add a description to a [singular data test](/docs/build/data-tests#singular-data-tests) or a [generic data test](/docs/build/data-tests#generic-data-tests).
+
```yml
+# Singular data test example
+
version: 2
data_tests:
- name: data_test_name
description: markdown_string
-
```
+
+
+
+
+```yml
+# Generic data test example
+
+version: 2
+models:
+ - name: model_name
+ columns:
+ - name: column_name
+ tests:
+ - unique:
+ description: markdown_string
+```
-The `description` property is available for generic and singular data tests beginning in dbt v1.9.
+The `description` property is available for [singular data tests](/docs/build/data-tests#singular-data-tests) or [generic data tests](/docs/build/data-tests#generic-data-tests) beginning in dbt v1.9.
+
+
+
+
+
+
+
+
+
+
+
+```yml
+unit_tests:
+ - name: unit_test_name
+ description: "markdown_string"
+ model: model_name
+ given: ts
+ - input: ref_or_source_call
+ rows:
+ - {column_name: column_value}
+ - {column_name: column_value}
+ - {column_name: column_value}
+ - {column_name: column_value}
+ - input: ref_or_source_call
+ format: csv
+ rows: dictionary | string
+ expect:
+ format: dict | csv | sql
+ fixture: fixture_name
+```
+
+
+
+
+
+
+
+The `description` property is available for [unit tests](/docs/build/unit-tests) beginning in dbt v1.8.
@@ -176,13 +234,17 @@ The `description` property is available for generic and singular data tests begi
## Definition
-A user-defined description. Can be used to document:
+
+A user-defined description used to document:
+
- a model, and model columns
- sources, source tables, and source columns
- seeds, and seed columns
- snapshots, and snapshot columns
- analyses, and analysis columns
- macros, and macro arguments
+- data tests, and data test columns
+- unit tests for models
These descriptions are used in the documentation website rendered by dbt (refer to [the documentation guide](/docs/build/documentation) or [dbt Explorer](/docs/collaborate/explore-projects)).
@@ -196,6 +258,18 @@ Be mindful of YAML semantics when providing a description. If your description c
## Examples
+This section contains examples of how to add descriptions to various resources:
+
+- [Add a simple description to a model and column](#add-a-simple-description-to-a-model-and-column)
+- [Add a multiline description to a model](#add-a-multiline-description-to-a-model)
+- [Use some markdown in a description](#use-some-markdown-in-a-description)
+- [Use a docs block in a description](#use-a-docs-block-in-a-description)
+- [Link to another model in a description](#link-to-another-model-in-a-description)
+- [Include an image from your repo in your descriptions](#include-an-image-from-your-repo-in-your-descriptions)
+- [Include an image from the web in your descriptions](#include-an-image-from-the-web-in-your-descriptions)
+- [Add a description to a data test](#add-a-description-to-a-data-test)
+- [Add a description to a unit test](#add-a-description-to-a-unit-test)
+
### Add a simple description to a model and column
@@ -400,3 +474,80 @@ models:
If mixing images and text, also consider using a docs block.
+### Add a description to a data test
+
+
+
+
+
+
+
+You can add a `description` property to a generic or singular data test.
+
+#### Generic data test
+
+This example shows a generic data test that checks for unique values in a column for the `orders` model.
+
+
+
+```yaml
+version: 2
+
+models:
+ - name: orders
+ columns:
+ - name: order_id
+ tests:
+ - unique:
+ description: "The order_id is unique for every row in the orders model"
+```
+
+
+#### Singular data test
+
+This example shows a singular data test that checks to ensure all values in the `payments` model are not negative (≥ 0).
+
+
+
+```yaml
+version: 2
+data_tests:
+ - name: assert_total_payment_amount_is_positive
+ description: >
+ Refunds have a negative amount, so the total amount should always be >= 0.
+ Therefore return records where total amount < 0 to make the test fail.
+
+```
+
+
+Note that in order for the test to run, the `tests/assert_total_payment_amount_is_positive.sql` SQL file has to exist in the `tests` directory.
+
+### Add a description to a unit test
+
+
+
+
+
+
+
+This example shows a unit test that checks to ensure the `opened_at` timestamp is properly truncated to a date for the `stg_locations` model.
+
+
+
+```yaml
+unit_tests:
+ - name: test_does_location_opened_at_trunc_to_date
+ description: "Check that opened_at timestamp is properly truncated to a date."
+ model: stg_locations
+ given:
+ - input: source('ecom', 'raw_stores')
+ rows:
+ - {id: 1, name: "Rego Park", tax_rate: 0.2, opened_at: "2016-09-01T00:00:00"}
+ - {id: 2, name: "Jamaica", tax_rate: 0.1, opened_at: "2079-10-27T23:59:59.9999"}
+ expect:
+ rows:
+ - {location_id: 1, location_name: "Rego Park", tax_rate: 0.2, opened_date: "2016-09-01"}
+ - {location_id: 2, location_name: "Jamaica", tax_rate: 0.1, opened_date: "2079-10-27"}
+```
+
+