OpenParable
Skip to content
← Back to skills

Dbt Test

Testing & Quality
dbt-test

Dbt Test is an Agent Skill for testing & quality published in the AltimateAI/altimate-code repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add schema tests, unit tests, and data quality checks to dbt models. Use when validating data integrity, adding test definitions to schema.yml, writing unit tests, or practicing test-driven development in dbt. Powered by altimate-dbt.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/AltimateAI/altimate-code/blob/HEAD/.opencode/skills/dbt-test/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/dbt-test, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

dbt Testing

Requirements

Agent: builder or migrator (requires file write access) Tools used: bash (runs altimate-dbt commands), read, glob, write, edit, altimate_core_testgen, altimate_core_validate

When to Use This Skill

Use when the user wants to:

  • Add tests to a model's schema.yml (unique, not_null, relationships, accepted_values)
  • Write dbt unit tests (mock inputs → expected outputs)
  • Create custom generic or singular tests
  • Debug why a test is failing
  • Practice test-driven development in dbt

Do NOT use for:

  • Creating or modifying model SQL → use dbt-develop
  • Writing model descriptions → use dbt-docs
  • Debugging build/compilation errors → use dbt-troubleshoot

The Iron Rule

Never modify a test to make it pass without understanding why it's failing.

A failing test is information. It means either:

  1. The data has a real quality issue (fix the data or the model)
  2. The test expectation is wrong (update the test with justification)
  3. The model logic is wrong (fix the model)

Option 2 requires explicit user confirmation. Do not silently weaken tests.

Schema Test Workflow

1. Discover Columns

altimate-dbt columns --model <name>
altimate-dbt column-values --model <name> --column <col>

2. Read Existing Tests

glob models/**/*schema*.yml models/**/*_models.yml
read <yaml_file>

3. Generate Tests

Auto-generate with altimate_core_testgen: Pass the compiled SQL and schema to generate boundary-value, NULL-handling, and edge-case test assertions automatically. This produces executable test SQL covering cases you might miss manually.

altimate_core_testgen(sql: <compiled_sql>, schema_context: <schema_object>)

Review the generated tests — keep what makes sense, discard trivial ones. Then apply test rules based on column patterns — see references/schema-test-patterns.md.

4. Write YAML

Merge into existing schema.yml (don't duplicate). Use edit for existing files, write for new ones.

5. Validate SQL

Before running, validate the compiled model SQL to catch syntax and schema errors early:

altimate_core_validate(sql: <compiled_sql>, schema_context: <schema_object>)

6. Run Tests

altimate-dbt test --model <name>          # run tests for this model
altimate-dbt build --model <name>         # build + test together

Unit Test Workflow

For automated unit test generation, use the dbt-unit-tests skill instead. It analyzes model SQL, generates type-correct mock data, and assembles complete YAML automatically.

See references/unit-test-guide.md for the full unit test framework.

Quick Pattern

unit_tests:
  - name: test_order_total_calculation
    model: fct_orders
    given:
      - input: ref('stg_orders')
        rows:
          - { order_id: 1, quantity: 3, unit_price: 10.00 }
          - { order_id: 2, quantity: 1, unit_price: 25.00 }
    expect:
      rows:
        - { order_id: 1, order_total: 30.00 }
        - { order_id: 2, order_total: 25.00 }

Common Mistakes

MistakeFix
Testing every column with not_nullOnly test columns that should never be null. Think about what NULL means.
Missing unique test on primary keysEvery primary key needs unique + not_null
accepted_values with incomplete listUse altimate-dbt column-values to discover real values first
Modifying a test to make it passUnderstand WHY it fails first. The test might be right.
No relationships test on foreign keysAdd relationships: {to: ref('parent'), field: parent_id}
Unit testing trivial logicDon't unit test SELECT a, b FROM source. Test calculations and business logic.

Reference Guides

GuideUse When
references/altimate-dbt-commands.mdNeed the full CLI reference
references/schema-test-patterns.mdAdding schema.yml tests by column pattern
references/unit-test-guide.mdWriting dbt unit tests
references/custom-tests.mdCreating generic or singular tests