altimate-code 0.5.20 → 0.5.21

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.21] - 2026-04-13
+
+### Added
+
+- **Automated dbt unit test generation** — generate dbt unit tests (v1.8+) from your terminal with `/dbt-unit-tests` or the `dbt_unit_test_gen` tool. Detects testable SQL constructs (CASE/WHEN, JOINs, NULLs, window functions, division, incremental models) and assembles complete YAML with type-correct mock data across 7 dialects. Includes `input: this` mocks for incremental models, `format: sql` for ephemeral deps, and handles seeds/snapshots as first-class `ref()` deps. Five-phase skill workflow: Analyze → Generate → Refine → Validate → Write. Requires dbt-core 1.8+. (#673)
+- **Manifest parse cache** — `loadRawManifest()` caches by path+mtime so large manifests (100MB+) are parsed once per session, not once per tool call.
+- **Model/source descriptions in manifest** — `DbtModelInfo` and `DbtSourceInfo` now surface descriptions from `schema.yml`, giving downstream tools richer semantic context.
+- **`adapter_type` on `DbtManifestResult`** — exposes the dbt adapter type (snowflake, bigquery, etc.) from manifest metadata for dialect auto-detection.
+
+### Fixed
+
+- **MCP env-var `$${VAR}` escape and chain-injection vulnerability** — the two-layer env-var resolution design allowed `$${VAR}` escapes to be re-resolved (breaking literal `${VAR}` passthrough) and enabled variable-chain injection where `EVIL_VAR="${SECRET}"` could exfiltrate secrets the config never referenced. Collapsed to a single resolution pass scoped to `env` and `headers` fields only. (#697, relates to #656)
+- **MCP server environment variables passed as literals** — `${VAR}`, `${VAR:-default}`, and `{env:VAR}` patterns in MCP server `env` blocks were passed as literal strings to child processes, causing auth failures for tools like `gitlab-mcp-server`. (#666, closes #656)
+- **`sql_explain` and `altimate_core_validate` input hardening** — reject empty/placeholder SQL and warehouse names before hitting the warehouse. `sql_explain` now generates dialect-aware EXPLAIN statements for 12+ warehouse types. Driver errors are translated into actionable guidance (e.g., "No warehouses configured — run `warehouse_add`"). `altimate_core_validate` now runs even without a schema (previously hard-failed), with a `(no schema)` indicator and clear instructions for providing schema context. (#693, closes #691)
+- **`sql_explain` alternatives for unsupported warehouses** — BigQuery, Oracle, and SQL Server now return specific guidance (dry-run API, `DBMS_XPLAN`, `SET SHOWPLAN_TEXT ON`) instead of a generic "not supported" message.
+
 ## [0.5.20] - 2026-04-09
 
 ### Added

package/package.json

@@ -14,24 +14,24 @@
   "scripts": {
     "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
   },
-  "version": "0.5.20",
+  "version": "0.5.21",
   "license": "MIT",
   "dependencies": {
     "@altimateai/altimate-core": "0.2.6"
   },
   "optionalDependencies": {
-    "@altimateai/altimate-code-linux-arm64": "0.5.20",
-    "@altimateai/altimate-code-windows-x64": "0.5.20",
-    "@altimateai/altimate-code-windows-x64-baseline": "0.5.20",
-    "@altimateai/altimate-code-darwin-x64": "0.5.20",
-    "@altimateai/altimate-code-windows-arm64": "0.5.20",
-    "@altimateai/altimate-code-linux-x64-baseline": "0.5.20",
-    "@altimateai/altimate-code-linux-arm64-musl": "0.5.20",
-    "@altimateai/altimate-code-linux-x64-musl": "0.5.20",
-    "@altimateai/altimate-code-linux-x64": "0.5.20",
-    "@altimateai/altimate-code-darwin-x64-baseline": "0.5.20",
-    "@altimateai/altimate-code-linux-x64-baseline-musl": "0.5.20",
-    "@altimateai/altimate-code-darwin-arm64": "0.5.20"
+    "@altimateai/altimate-code-linux-x64-musl": "0.5.21",
+    "@altimateai/altimate-code-linux-x64-baseline": "0.5.21",
+    "@altimateai/altimate-code-windows-arm64": "0.5.21",
+    "@altimateai/altimate-code-darwin-arm64": "0.5.21",
+    "@altimateai/altimate-code-windows-x64-baseline": "0.5.21",
+    "@altimateai/altimate-code-linux-arm64": "0.5.21",
+    "@altimateai/altimate-code-linux-x64-baseline-musl": "0.5.21",
+    "@altimateai/altimate-code-darwin-x64-baseline": "0.5.21",
+    "@altimateai/altimate-code-windows-x64": "0.5.21",
+    "@altimateai/altimate-code-darwin-x64": "0.5.21",
+    "@altimateai/altimate-code-linux-x64": "0.5.21",
+    "@altimateai/altimate-code-linux-arm64-musl": "0.5.21"
   },
   "peerDependencies": {
     "pg": ">=8",

package/skills/dbt-test/SKILL.md

@@ -81,6 +81,8 @@ 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](references/unit-test-guide.md) for the full unit test framework.
 
 ### Quick Pattern

package/skills/dbt-unit-tests/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dbt-unit-tests
+description: Generate dbt unit tests automatically for any model. Analyzes SQL logic (CASE/WHEN, JOINs, window functions, NULLs), creates type-correct mock inputs from manifest schema, and assembles complete YAML. Use when a user says "generate tests", "add unit tests", "test this model", or "test coverage" for dbt models.
+---
+
+# dbt Unit Test Generation
+
+## Requirements
+**Agent:** builder or migrator (requires file write access)
+**Tools used:** dbt_unit_test_gen, dbt_manifest, dbt_lineage, altimate_core_validate, altimate_core_testgen, bash (runs `altimate-dbt` commands), read, glob, write, edit
+
+## When to Use This Skill
+
+**Use when the user wants to:**
+- Generate unit tests for a dbt model
+- Add test coverage to an existing model
+- Create mock data for testing
+- Test-driven development (TDD) for dbt
+- Verify CASE/WHEN logic, NULL handling, JOIN behavior, or aggregation correctness
+- Test incremental model logic
+
+**Do NOT use for:**
+- Adding schema tests (not_null, unique, accepted_values) -> use `dbt-test`
+- Creating or modifying model SQL -> use `dbt-develop`
+- Writing descriptions -> use `dbt-docs`
+- Debugging build failures -> use `dbt-troubleshoot`
+
+## The Iron Rules
+
+1. **Never guess expected outputs.** Compute them by running SQL against mock data when possible. If you cannot run SQL, clearly mark expected outputs as placeholders that need verification.
+2. **Never skip upstream dependencies.** Every ref() and source() the model touches MUST have a mock input. Miss one and the test won't compile.
+3. **Use sql format for ephemeral models.** Dict format fails silently for ephemeral upstreams.
+4. **Never weaken a test to make it pass.** If the test fails, the model logic may be wrong. Investigate before changing expected values.
+5. **Compile before committing.** Always run `altimate-dbt test --model <name>` to verify tests compile and execute.
+
+## Core Workflow: Analyze -> Generate -> Refine -> Validate -> Write
+
+### Phase 1: Analyze the Model
+
+Before generating any tests, deeply understand the model:
+
+```bash
+# 1. Ensure manifest is compiled
+altimate-dbt compile --model <name>
+
+# 2. Read the model SQL
+read <model_sql_file>
+
+# 3. Parse the manifest for dependencies
+dbt_unit_test_gen(manifest_path: "target/manifest.json", model: "<name>")
+```
+
+**What to look for:**
+- Which upstream refs/sources does this model depend on?
+- What SQL constructs need testing? (CASE/WHEN, JOINs, window functions, aggregations)
+- What edge cases exist? (NULLs, empty strings, zero values, boundary dates)
+- Is this an incremental model? (needs `is_incremental` override tests)
+- Are any upstream models ephemeral? (need sql format)
+
+### Phase 2: Generate Tests
+
+The `dbt_unit_test_gen` tool does the heavy lifting:
+
+```text
+dbt_unit_test_gen(
+  manifest_path: "target/manifest.json",
+  model: "fct_orders",
+  max_scenarios: 5
+)
+```
+
+This returns:
+- Complete YAML with mock inputs and expected outputs
+- Semantic context: model/column descriptions, column lineage, compiled SQL
+- List of anti-patterns that informed edge case generation
+- Warnings about ephemeral deps, missing columns, etc.
+
+**If the tool reports missing columns** (placeholder rows in the YAML), discover them:
+```bash
+altimate-dbt columns --model <upstream_model_name>
+altimate-dbt columns-source --source <source_name> --table <table_name>
+```
+Then update the generated YAML with real column names.
+
+### Phase 3: Refine Expected Outputs
+
+**This is the critical step that differentiates good tests from bad ones.**
+
+The tool generates placeholder expected outputs based on column types. You MUST refine them:
+
+**Option A: Compute by running SQL (preferred)**
+```bash
+# Run the model against mock data to get actual output
+altimate-dbt test --model <name>
+# If the test fails, the error shows actual vs expected — use actual as expected
+```
+
+**Option B: Manual computation**
+Read the model SQL carefully and mentally execute it against the mock inputs.
+For each test case:
+1. Look at the mock input rows
+2. Trace through the SQL logic (CASE/WHEN branches, JOINs, aggregations)
+3. Write the correct expected output
+
+**Option C: Use the warehouse (most accurate)**
+```bash
+# Build a CTE query with mock data and run the model SQL against it
+altimate-dbt execute --query "WITH mock_stg_orders AS (SELECT 1 AS order_id, 100.00 AS amount) SELECT * FROM (<model_sql>) sub"
+```
+
+### Phase 4: Validate
+
+```bash
+# 1. Run the unit tests
+altimate-dbt test --model <name>
+
+# 2. If tests fail, read the error carefully
+#    - Compilation error? Missing ref, wrong column name, type mismatch
+#    - Assertion error? Expected output doesn't match actual
+
+# 3. Fix and retry (max 3 iterations)
+```
+
+### Phase 5: Write to File
+
+Place unit tests in one of these locations (match project convention):
+- `models/<layer>/_unit_tests.yml` (dedicated file)
+- `models/<layer>/schema.yml` (append to existing)
+
+```bash
+# Check existing convention
+glob models/**/*unit_test*.yml models/**/*schema*.yml
+
+# Write or append
+edit <yaml_file>  # if file exists
+write <yaml_file> # if creating new
+```
+
+## Test Case Categories
+
+### Happy Path (always generate)
+Standard inputs that exercise the main logic path. 2 rows minimum.
+
+### NULL Handling
+Set nullable columns to NULL in the last row. Verify COALESCE/NVL/IFNULL behavior.
+
+### Boundary Values
+Zero amounts, empty strings, epoch dates, MAX values. Tests robustness.
+
+### Edge Cases
+- Division by zero (if model divides)
+- Non-matching JOINs (LEFT JOIN with no match)
+- Single-row aggregation
+- Duplicate key handling
+
+### Incremental
+For incremental models only. Use `overrides.macros.is_incremental: true` to test the incremental path.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing a ref() in given | Parse manifest for ALL depends_on nodes |
+| Wrong column names in mock data | Use manifest columns, not guesses |
+| Wrong data types | Use schema catalog types |
+| Expected output is just mock input | Actually compute the transformation |
+| Dict format for ephemeral model | Use `format: sql` with raw SQL |
+| Not testing NULL path in COALESCE | Add null_handling test case |
+| Hardcoded dates with current_timestamp | Use overrides.macros to mock timestamps |
+| Testing trivial pass-through | Skip models with no logic |
+
+## YAML Format Reference
+
+```yaml
+unit_tests:
+  - name: test_<model>_<scenario>
+    description: "What this test verifies"
+    model: <model_name>
+    overrides:                    # optional
+      macros:
+        is_incremental: true      # for incremental models
+      vars:
+        run_date: "2024-01-15"    # for date-dependent logic
+    given:
+      - input: ref('upstream_model')
+        rows:
+          - { col1: value1, col2: value2 }
+      - input: source('source_name', 'table_name')
+        rows:
+          - { col1: value1 }
+      - input: ref('ephemeral_model')
+        format: sql
+        rows: |
+          SELECT 1 AS id, 'test' AS name
+          UNION ALL
+          SELECT 2 AS id, 'other' AS name
+    expect:
+      rows:
+        - { output_col1: expected1, output_col2: expected2 }
+```
+
+## Reference Guides
+
+| Guide | Use When |
+|-------|----------|
+| [references/unit-test-yaml-spec.md](references/unit-test-yaml-spec.md) | Full YAML specification and format details |
+| [references/edge-case-patterns.md](references/edge-case-patterns.md) | Catalog of edge cases by SQL construct |
+| [references/incremental-testing.md](references/incremental-testing.md) | Testing incremental models |
+| [references/altimate-dbt-commands.md](references/altimate-dbt-commands.md) | Full CLI reference |

package/skills/dbt-unit-tests/references/altimate-dbt-commands.md

@@ -0,0 +1,66 @@
+# altimate-dbt Command Reference
+
+All dbt operations use the `altimate-dbt` CLI. Output is JSON to stdout; logs go to stderr.
+
+```bash
+altimate-dbt <command> [args...]
+altimate-dbt <command> [args...] --format text    # Human-readable output
+```
+
+## First-Time Setup
+
+```bash
+altimate-dbt init                          # Auto-detect project root
+altimate-dbt init --project-root /path     # Explicit root
+altimate-dbt init --python-path /path      # Override Python
+altimate-dbt doctor                        # Verify setup
+altimate-dbt info                          # Project name, adapter, root
+```
+
+## Build & Run
+
+```bash
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
+altimate-dbt run --model <name> [--downstream]      # materialize only
+altimate-dbt test --model <name>                     # run tests only
+```
+
+## Compile
+
+```bash
+altimate-dbt compile --model <name>
+altimate-dbt compile-query --query "SELECT * FROM {{ ref('stg_orders') }}" [--model <context>]
+```
+
+## Execute SQL
+
+```bash
+altimate-dbt execute --query "SELECT count(*) FROM {{ ref('orders') }}" --limit 100
+```
+
+## Schema & DAG
+
+```bash
+altimate-dbt columns --model <name>                         # column names and types
+altimate-dbt columns-source --source <src> --table <tbl>    # source table columns
+altimate-dbt column-values --model <name> --column <col>    # sample values
+altimate-dbt children --model <name>                        # downstream models
+altimate-dbt parents --model <name>                         # upstream models
+```
+
+## Packages
+
+```bash
+altimate-dbt deps                                           # install packages.yml
+altimate-dbt add-packages --packages dbt-utils,dbt-expectations
+```
+
+## Error Handling
+
+All errors return JSON with `error` and `fix` fields:
+```json
+{ "error": "dbt-core is not installed", "fix": "Install it: python3 -m pip install dbt-core" }
+```
+
+Run `altimate-dbt doctor` as the first diagnostic step for any failure.

package/skills/dbt-unit-tests/references/edge-case-patterns.md

@@ -0,0 +1,189 @@
+# Edge Case Patterns by SQL Construct
+
+## CASE/WHEN
+
+**What to test:** Every branch, including ELSE/default.
+
+```yaml
+# Test the TRUE branch
+- { status: "completed", amount: 100 }
+# Expected: { category: "done" }
+
+# Test the FALSE/ELSE branch
+- { status: "unknown", amount: 100 }
+# Expected: { category: "other" }
+
+# Test NULL input
+- { status: null, amount: 100 }
+# Expected: depends on whether NULL matches any WHEN
+```
+
+**Common bugs:**
+- NULL doesn't match `WHEN status = 'active'` — it falls to ELSE
+- Multiple WHEN clauses: first match wins, test ordering
+
+## COALESCE / NVL / IFNULL
+
+**What to test:** NULL in each position.
+
+```yaml
+# COALESCE(a, b, c) — test a=NULL
+- { a: null, b: "fallback", c: "default" }
+# Expected: { result: "fallback" }
+
+# COALESCE(a, b, c) — test a=NULL, b=NULL
+- { a: null, b: null, c: "default" }
+# Expected: { result: "default" }
+
+# All non-null
+- { a: "primary", b: "fallback", c: "default" }
+# Expected: { result: "primary" }
+```
+
+## JOINs
+
+**What to test:** Matching rows, non-matching rows, NULL join keys.
+
+```yaml
+# LEFT JOIN — matching row
+orders: [{ order_id: 1, customer_id: 1 }]
+customers: [{ customer_id: 1, name: "Alice" }]
+# Expected: { order_id: 1, name: "Alice" }
+
+# LEFT JOIN — no match (customer missing)
+orders: [{ order_id: 2, customer_id: 99 }]
+customers: [{ customer_id: 1, name: "Alice" }]
+# Expected: { order_id: 2, name: null }
+
+# JOIN with NULL key
+orders: [{ order_id: 3, customer_id: null }]
+customers: [{ customer_id: 1, name: "Alice" }]
+# Expected: depends on join type
+```
+
+**Common bugs:**
+- INNER JOIN drops rows when key is NULL or missing
+- Fan-out: duplicate keys in right table multiply left rows
+
+## Window Functions
+
+**What to test:** Ordering, partitioning, boundary rows.
+
+```yaml
+# ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date)
+- { customer_id: 1, order_date: "2024-01-01", amount: 50 }
+- { customer_id: 1, order_date: "2024-01-15", amount: 75 }
+- { customer_id: 2, order_date: "2024-01-10", amount: 30 }
+# Expected:
+# { customer_id: 1, order_date: "2024-01-01", row_num: 1 }
+# { customer_id: 1, order_date: "2024-01-15", row_num: 2 }
+# { customer_id: 2, order_date: "2024-01-10", row_num: 1 }
+```
+
+**What to test for LAG/LEAD:**
+- First/last row in partition (LAG returns NULL for first row)
+- Single-row partition
+
+## Aggregations (GROUP BY)
+
+**What to test:** Multiple groups, single group, empty group.
+
+```yaml
+# SUM(amount) GROUP BY customer_id
+- { customer_id: 1, amount: 50 }
+- { customer_id: 1, amount: 25 }
+- { customer_id: 2, amount: 100 }
+# Expected:
+# { customer_id: 1, total_amount: 75 }
+# { customer_id: 2, total_amount: 100 }
+
+# Single row group
+- { customer_id: 3, amount: 10 }
+# Expected: { customer_id: 3, total_amount: 10 }
+
+# NULL in aggregated column
+- { customer_id: 4, amount: null }
+# Expected: { customer_id: 4, total_amount: null }  # SUM of NULLs = NULL
+```
+
+## Division
+
+**What to test:** Normal, divide by zero, NULL.
+
+```yaml
+# amount / quantity
+- { amount: 100, quantity: 4 }
+# Expected: { unit_price: 25 }
+
+# Divide by zero
+- { amount: 100, quantity: 0 }
+# Expected: depends — NULL, error, or COALESCE fallback?
+
+# NULL divisor
+- { amount: 100, quantity: null }
+# Expected: { unit_price: null }
+```
+
+## Date/Timestamp Logic
+
+**What to test:** Boundaries, NULL dates, timezone edge cases.
+
+```yaml
+# DATEDIFF or date filtering
+- { event_date: "2024-01-01" }  # start of year
+- { event_date: "2024-12-31" }  # end of year
+- { event_date: "2024-02-29" }  # leap year
+- { event_date: null }           # NULL date
+```
+
+## Type Coercion
+
+**What to test:** Implicit casts that may fail.
+
+```yaml
+# String that looks like a number
+- { amount_str: "100.50" }  # CAST to DECIMAL
+- { amount_str: "not_a_number" }  # should this fail?
+- { amount_str: "" }  # empty string cast
+- { amount_str: null }  # NULL cast
+```
+
+## Incremental Models
+
+**What to test:** Full refresh vs incremental path.
+
+```yaml
+# Test 1: Full refresh (is_incremental = false, default)
+# All rows processed
+
+# Test 2: Incremental (is_incremental = true)
+unit_tests:
+  - name: test_incremental_new_rows_only
+    model: fct_orders
+    overrides:
+      macros:
+        is_incremental: true
+    given:
+      - input: this  # existing table state
+        rows:
+          - { order_id: 1, updated_at: "2024-01-14" }
+      - input: ref('stg_orders')
+        rows:
+          - { order_id: 1, updated_at: "2024-01-14" }  # old, should be skipped
+          - { order_id: 2, updated_at: "2024-01-15" }  # new, should be processed
+    expect:
+      rows:
+        - { order_id: 2, updated_at: "2024-01-15" }
+```
+
+## Empty Inputs
+
+**What to test:** Model behavior when upstream has zero rows.
+
+```yaml
+given:
+  - input: ref('stg_orders')
+    rows: []
+expect:
+  rows: []  # or specific default behavior
+```

package/skills/dbt-unit-tests/references/incremental-testing.md

@@ -0,0 +1,109 @@
+# Testing Incremental dbt Models
+
+Incremental models have two code paths controlled by `{% if is_incremental() %}`. Both paths must be tested.
+
+## The Two Paths
+
+```sql
+SELECT * FROM {{ ref('stg_orders') }}
+
+{% if is_incremental() %}
+  -- Incremental path: only process new rows
+  WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
+{% endif %}
+```
+
+## Test 1: Full Refresh
+
+```yaml
+unit_tests:
+  - name: test_fct_orders_full_refresh
+    description: "Full refresh processes all rows"
+    model: fct_orders
+    # No overrides needed — is_incremental defaults to false
+    given:
+      - input: ref('stg_orders')
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-10" }
+          - { order_id: 2, amount: 200, updated_at: "2024-01-15" }
+    expect:
+      rows:
+        - { order_id: 1, amount: 100, updated_at: "2024-01-10" }
+        - { order_id: 2, amount: 200, updated_at: "2024-01-15" }
+```
+
+## Test 2: Incremental — New Rows Only
+
+```yaml
+unit_tests:
+  - name: test_fct_orders_incremental_new_only
+    description: "Incremental run only processes rows newer than existing max"
+    model: fct_orders
+    overrides:
+      macros:
+        is_incremental: true
+    given:
+      - input: this   # mock the existing target table
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-10" }
+      - input: ref('stg_orders')
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-10" }  # old
+          - { order_id: 2, amount: 200, updated_at: "2024-01-15" }  # new
+    expect:
+      rows:
+        - { order_id: 2, amount: 200, updated_at: "2024-01-15" }
+```
+
+## Test 3: Incremental — Updated Rows
+
+If your model uses `unique_key` for merge/upsert:
+
+```yaml
+unit_tests:
+  - name: test_fct_orders_incremental_update
+    description: "Updated rows are captured in incremental run"
+    model: fct_orders
+    overrides:
+      macros:
+        is_incremental: true
+    given:
+      - input: this
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-10" }
+      - input: ref('stg_orders')
+        rows:
+          - { order_id: 1, amount: 150, updated_at: "2024-01-15" }  # updated
+    expect:
+      rows:
+        - { order_id: 1, amount: 150, updated_at: "2024-01-15" }
+```
+
+## Test 4: Incremental — Empty Source
+
+```yaml
+unit_tests:
+  - name: test_fct_orders_incremental_no_new_data
+    description: "No new rows when source has nothing newer"
+    model: fct_orders
+    overrides:
+      macros:
+        is_incremental: true
+    given:
+      - input: this
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-15" }
+      - input: ref('stg_orders')
+        rows:
+          - { order_id: 1, amount: 100, updated_at: "2024-01-10" }  # older
+    expect:
+      rows: []
+```
+
+## Key Points
+
+1. **Always mock `this`** when testing incremental path — it represents the existing target table
+2. **Set `is_incremental: true`** in overrides.macros to activate the incremental code path
+3. **Test both paths** — full refresh AND incremental
+4. **Include overlap rows** — rows that exist in both `this` and source to verify filtering
+5. **Test the merge key** — if `unique_key` is set, verify upsert behavior

package/skills/dbt-unit-tests/references/unit-test-yaml-spec.md

@@ -0,0 +1,174 @@
+# dbt Unit Test YAML Specification
+
+Available in dbt-core 1.8+ (released mid-2024).
+
+## Top-Level Structure
+
+Unit tests are defined under the `unit_tests:` key in any YAML file within your dbt project (typically `schema.yml` or `_unit_tests.yml`).
+
+```yaml
+unit_tests:
+  - name: <test_name>           # required, snake_case
+    description: <string>        # optional but recommended
+    model: <model_name>          # required, the model being tested
+    given: <list of inputs>      # required, mock input data
+    expect: <expected output>    # required, expected output rows
+    overrides: <overrides>       # optional, macro/var overrides
+    config: <config>             # optional, test configuration
+    tags: <list>                 # optional, for filtering
+```
+
+## Input Formats
+
+### Dict Format (default, preferred)
+
+```yaml
+given:
+  - input: ref('stg_orders')
+    rows:
+      - { order_id: 1, amount: 100.00, status: "completed" }
+      - { order_id: 2, amount: null, status: "pending" }
+```
+
+**Rules:**
+- Only include columns that the model actually uses
+- Column names must match the upstream model exactly
+- Use `null` for NULL values (not empty string)
+- Dates as strings: `"2024-01-15"`
+- Timestamps as strings: `"2024-01-15 10:30:00"`
+- Booleans: `true` / `false`
+- Numbers: no quotes (`100.00`, not `"100.00"`)
+
+### SQL Format (required for ephemeral models)
+
+```yaml
+given:
+  - input: ref('ephemeral_model')
+    format: sql
+    rows: |
+      SELECT 1 AS id, 'test' AS name
+      UNION ALL
+      SELECT 2 AS id, 'other' AS name
+```
+
+**When to use SQL format:**
+- Upstream model is materialized as `ephemeral`
+- Complex data types that dict can't represent
+- Need to use SQL functions in mock data
+
+### Empty Input
+
+```yaml
+given:
+  - input: ref('stg_orders')
+    rows: []
+```
+
+Tests behavior with no input rows (empty table).
+
+## Expected Output
+
+```yaml
+expect:
+  rows:
+    - { order_id: 1, net_revenue: 85.00 }
+    - { order_id: 2, net_revenue: 50.00 }
+```
+
+**Rules:**
+- Only include columns you want to assert on (subset is OK)
+- Row order matters — rows are compared positionally
+- Use exact values for numeric assertions
+- `null` to assert NULL output
+
+## Overrides
+
+### Macro Overrides
+
+```yaml
+overrides:
+  macros:
+    is_incremental: true          # boolean
+    current_timestamp: "2024-01-15 00:00:00"  # string
+```
+
+Common macros to override:
+- `is_incremental` — test incremental vs full-refresh path
+- `current_timestamp` / `current_date` — deterministic date testing
+
+### Variable Overrides
+
+```yaml
+overrides:
+  vars:
+    run_date: "2024-01-15"
+    lookback_days: 30
+```
+
+## Input Sources
+
+### ref() — Model references
+
+```yaml
+- input: ref('model_name')
+```
+
+### source() — Source table references
+
+```yaml
+- input: source('source_name', 'table_name')
+```
+
+### this — Self-reference for incremental models
+
+```yaml
+- input: this
+  rows:
+    - { order_id: 1, updated_at: "2024-01-14" }
+```
+
+Used with `overrides.macros.is_incremental: true` to mock the existing table state.
+
+## Configuration
+
+Tags can be set at the top level (sibling of `config`) or nested under `config`:
+
+```yaml
+unit_tests:
+  - name: test_example
+    model: fct_orders
+    tags: ["unit-test", "revenue"]
+    # ... rest of test
+```
+
+Or via config:
+
+```yaml
+unit_tests:
+  - name: test_example
+    model: fct_orders
+    config:
+      tags: ["unit-test", "revenue"]
+```
+
+## Naming Conventions
+
+- Test names: `test_<model>_<what_it_tests>`
+- Examples:
+  - `test_fct_orders_happy_path`
+  - `test_fct_orders_null_discount`
+  - `test_fct_orders_zero_quantity`
+  - `test_fct_orders_incremental_new_rows`
+
+## Running Unit Tests
+
+```bash
+dbt test --select test_type:unit                    # all unit tests
+dbt test --select test_type:unit,model_name:fct_orders  # unit tests for one model
+dbt build --select +fct_orders                      # build + all tests
+```
+
+## Official Documentation
+
+- https://docs.getdbt.com/docs/build/unit-tests
+- https://docs.getdbt.com/reference/resource-properties/unit-tests