Skill to add unit tests to a dbt project by dbeatty10 · Pull Request #13 · dbt-labs/dbt-agent-skills

dbeatty10 · 2026-01-20T20:44:34Z

resolves #

Description

Checklist

I have read the contributing guide and understand what's expected of me
I have signed the CLA
I have run this code in development and it appears to resolve the stated issue
I have opened an issue to add/update docs, or docs changes are not required/relevant for this PR
I have run changie new to create a changelog entry

jasnonaz

Bunch of comments, mostly around splitting out some logic in here that probably doesn't need to live in the main skill.

I feel like this is a lot of what, some how and very little why. To the extent we can bake in more opinioned / high signal heuristics for the models we should attempt to.

jasnonaz · 2026-01-20T21:11:55Z

+dbt unit test uses a trio of the model, given inputs, and expected outputs (Model-Inputs-Outputs):
+
+1. `model` - when building this model
+2. `given` inputs - given a set of source, seeds, and models as preconditions


Suggested change

2. `given` inputs - given a set of source, seeds, and models as preconditions

2. `given` inputs - given a set of source, seeds, macros and models as preconditions

Since macros go under overrides rather than under given, I'm not going to commit this as-is.

But good point that macros fall under the inputs / pre-conditions umbrella (along with project variables and environment variables).

So we'll either want to add that info here or just leave it to the later sections that cover those scenarios

jasnonaz · 2026-01-20T21:23:24Z

+## `sql`
+
+Using this format:
+- Provides more flexibility for the unit testing column that have a data type not supported by the `dict` or `csv` formats


THIS is great - this is the stuff we keep

jasnonaz · 2026-01-20T21:26:46Z

+
+# Special cases
+
+## Unit testing incremental models


incremental and versioned examples should live in their own file with callouts that these are special cases and the model should look into it. For the most part - keep the prose,, move the code.

Addressed in e395b1d

jasnonaz · 2026-01-20T21:30:28Z

+1. There was an error in the way the unit test was constructed (false positive)
+2. There is an bug is the model (true positive)
+
+It takes expert judgement to determine one from the other.


Can we have some guidance on how to determine one from the other?

jasnonaz · 2026-01-20T21:32:33Z

+
+```
+
+### Fixture files


Is this needed given the above section talking about files?

Partially addressed in 5719ff4.

Can revisit to consolidate any duplicated content.

Co-authored-by: Jason Ganz <jason.ganz64@gmail.com>

…skills into dbeatty/unit-tests

b-per · 2026-01-21T12:00:34Z

@@ -0,0 +1,3 @@
+# Caveats for BigQuery


I really think we need this type of info! Thanks for adding.

My comments:

is caveat the correct word here? if we add recommendations and best practices for other parts in dbt for BQ, those might not be caveats. I like instructions_bigquery.md or something like that

we could add all of those under a specific folder for adapter/warehouse specific instructions

we should call out the name of the file in any skill that would need to get this information, otherwise the LLM will not look at it

we should call out the name of the file in any skill that would need to get this information, otherwise the LLM will not look at it

✅ Done!

is caveat the correct word here? if we add recommendations and best practices for other parts in dbt for BQ, those might not be caveats. I like instructions_bigquery.md or something like that

One definition of caveat is "specific stipulations, conditions, or limitations", so it is a good descriptor in this case. We can call it whatever we want though, and I don't feel strongly either way.

we could add all of those under a specific folder for adapter/warehouse specific instructions

Are you thinking something like this within a subfolder with simply the name of the adapter/warehouse?

my-skill/ ├── SKILL.md └── adapter/ ├── bigquery.md (adapter/warehouse specific instructions - loaded when needed) ├── databricks.md (adapter/warehouse specific instructions - loaded when needed) ├── redshift.md (adapter/warehouse specific instructions - loaded when needed) └── snowflake.md (adapter/warehouse specific instructions - loaded when needed)

Or flat like this?

my-skill/ ├── SKILL.md ├── bigquery.md (adapter/warehouse specific instructions - loaded when needed) ├── databricks.md (adapter/warehouse specific instructions - loaded when needed) ├── redshift.md (adapter/warehouse specific instructions - loaded when needed) └── snowflake.md (adapter/warehouse specific instructions - loaded when needed)

I was actually thinking of a third option (close to the 1st one)

my-skill1/ └── SKILL.md my-skill2/ └── SKILL.md adapter/ ├── bigquery.md (adapter/warehouse specific instructions - loaded when needed) ├── databricks.md (adapter/warehouse specific instructions - loaded when needed) ├── redshift.md (adapter/warehouse specific instructions - loaded when needed) └── snowflake.md (adapter/warehouse specific instructions - loaded when needed)

The adapter specific things we'd have to say will be short enough that we can have 1 file to cover all the skills.

Addressed in 2542c0f, fdaf6ab, and dd24b72.

We can move it around / rename it further as-needed.

…lder

b-per

TY Doug! Added some comments

b-per · 2026-01-21T14:30:32Z

+
+## What are unit tests in dbt
+
+In software programming, unit tests validate small portions of your functional code, and they work much the same way in dbt. dbt uwnit tests allow you to validate your SQL modeling logic on a small set of static inputs _before_ you materialize your full model in production. dbt unit tests enable test-driven development, benefiting developer efficiency and code reliability.


Suggested change

In software programming, unit tests validate small portions of your functional code, and they work much the same way in dbt. dbt uwnit tests allow you to validate your SQL modeling logic on a small set of static inputs _before_ you materialize your full model in production. dbt unit tests enable test-driven development, benefiting developer efficiency and code reliability.

In software programming, unit tests validate small portions of your functional code, and they work much the same way in dbt. dbt unit tests allow you to validate your SQL modeling logic on a small set of static inputs _before_ you materialize your full model in production. dbt unit tests enable test-driven development, benefiting developer efficiency and code reliability.

b-per · 2026-01-21T14:37:01Z

@@ -0,0 +1,42 @@
+See below for all the required and optional keys in the YAML definition of unit tests.


Yes to this type of info!!!

This is the information dense type of content that is maybe too dense for humans to reason through, but it is exactly what LLMs need!

b-per · 2026-01-21T14:39:32Z

+
+This example creates a new `dim_customers` model with a field `is_valid_email_address` that calculates whether or not the customer’s email is valid: 
+
+<file name='dim_customers.sql'>


We haven't used this `<file ...> syntax in the other skills. Open question, should we do it everywhere or should we not use it? I think we should be consistent though.

Updated to use the following syntax within bcf4292:

`models/schema.yml`

```yaml
# stuff
```

b-per · 2026-01-21T15:56:42Z

+- Verifying that a bug fix solves a bug report for an existing dbt model.
+
+More examples:
+- When your SQL contains complex logic:


Should we add complex joins logic?

b-per · 2026-01-21T15:57:55Z

+
+Self explanatory -- the title says it all!
+
+### 2. Mock the inputs


Should we recommend using dbt show to explore the existing inputs/outputs and sanitize them to make sure they don't contain sensitive data?

This is a fantastic idea!

Might even be a good stand-alone and reusable skill.

…lated to unit testing

dbeatty10 · 2026-01-25T16:43:29Z

From Benoit in internal slack:

I just did a quick demo/test of running the evals on top of your skill (video)

Doing it I saw that we might need to tweak the skill name and/or description

Would you be OK trying to add a scenario where you provide an existing dbt project as context and ask to add some unit tests (like you did by hand) ; but this time having one case without the skill and one case with the skill?

- Add complex joins to list of scenarios that warrant unit tests - Add tip to use dbt show for exploring input data with sanitization reminder

b-per · 2026-01-29T16:25:43Z

Merging this for now as a v1 🚀

dbeatty10 added 3 commits January 20, 2026 13:44

Skill to add unit tests to a dbt project

a9b0ac0

Skill to add unit tests to a dbt project

25810cf

Small cleanup

1abb074

jasnonaz requested changes Jan 20, 2026

View reviewed changes

dbeatty10 and others added 10 commits January 20, 2026 17:01

Start with a general "What are unit tests in dbt"

3fb0017

Make the workflow section bulleted

4d0bc0f

Update dbt-unit-tests/skills/add-unit-test/SKILL.md

4995b49

Co-authored-by: Jason Ganz <jason.ganz64@gmail.com>

Split the YAML specification into a different file in the skill

d27a66d

Merge branch 'dbeatty/unit-tests' of https://github.com/dbt-labs/llm-…

e281bc3

…skills into dbeatty/unit-tests

Split code examples into a different file in the skill

a4c2dbb

Split format code examples into separate file

62383ed

When to use each format

1b5224a

Split platform specific details into separate files

ea5c89a

Move fixture files section within the formats section

5719ff4

b-per reviewed Jan 21, 2026

View reviewed changes

dbeatty10 added 4 commits January 21, 2026 08:30

Split special cases into separate files

e395b1d

Move helper files accidentally in wrong location

2e60a1b

Move special cases into their own folder

fdaf6ab

Move adapter/warehouse-specific caveats and details into their own fo…

2542c0f

…lder

b-per reviewed Jan 21, 2026

View reviewed changes

dbeatty10 added 4 commits January 21, 2026 09:01

Update reference links to moved files

d5a4323

Move adapter/warehouse-specific data to be re-usable across skills re…

dd24b72

…lated to unit testing

Update syntax for file names in examples

bcf4292

Merge branch 'main' into dbeatty/unit-tests

cfe5f58

Address review comments #18 and #19

c6789e9

- Add complex joins to list of scenarios that warrant unit tests - Add tip to use dbt show for exploring input data with sanitization reminder

b-per marked this pull request as ready for review January 29, 2026 16:25

b-per requested a review from a team as a code owner January 29, 2026 16:25

b-per merged commit 531e6cc into main Jan 29, 2026
5 checks passed

	2. `given` inputs - given a set of source, seeds, and models as preconditions
	2. `given` inputs - given a set of source, seeds, macros and models as preconditions


		## What are unit tests in dbt

		In software programming, unit tests validate small portions of your functional code, and they work much the same way in dbt. dbt uwnit tests allow you to validate your SQL modeling logic on a small set of static inputs _before_ you materialize your full model in production. dbt unit tests enable test-driven development, benefiting developer efficiency and code reliability.

		@@ -0,0 +1,42 @@
		See below for all the required and optional keys in the YAML definition of unit tests.


		This example creates a new `dim_customers` model with a field `is_valid_email_address` that calculates whether or not the customer’s email is valid:

		<file name='dim_customers.sql'>


		Self explanatory -- the title says it all!

		### 2. Mock the inputs

Conversation

dbeatty10 commented Jan 20, 2026

Description

Checklist

Uh oh!

jasnonaz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dbeatty10 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

b-per left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dbeatty10 commented Jan 25, 2026

Uh oh!

b-per commented Jan 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dbeatty10 Jan 22, 2026 •

edited

Loading