Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt

Use this file to discover all available pages before exploring further.

​
sqb scenario

Run end-to-end scenario tests. Scenarios materialize fixture inputs as physical relations, build the real project graph against them, and evaluate expected outputs and assertions. See Scenarios for concepts and authoring details.

​
sqb scenario test

Run scenario tests against the warehouse. 
sqb scenario test [selectors...] [flags]

​
Flags

FlagDescription
--retainKeep scenario-owned warehouse artifacts for inspection
--localRun locally against DuckDB using captured JSONL snapshots
--strictTreat missing/stale local snapshots as errors instead of skips
--sync-snapshotsCapture missing/stale snapshots before local run (requires --local)
--refreshRecapture all selected snapshots before local run (requires --local)
--forceBypass snapshot capture safety limits
--max-snapshot-rowsOverride per-relation row limit for capture
--max-snapshot-total-rowsOverride total row limit for capture
--max-snapshot-bytesOverride per-relation byte limit for capture
--max-snapshot-total-bytesOverride total byte limit for capture
--no-sql-validationSkip compile-time SQL syntax validation

​
Selectors

Zero or more selectors can be provided. Without selectors, all discovered scenarios run.
SelectorExample
Scenario namesqb scenario test daily_revenue_minimal
Multiple namessqb scenario test daily_revenue_minimal daily_revenue_multi_order
.sql file pathsqb scenario test tests/scenarios/revenue/daily_revenue_minimal.sql
Foldersqb scenario test tests/scenarios/revenue
Scenario-root-relative foldersqb scenario test revenue
Mixed selector types are supported and de-duplicated by scenario name.

​
Remote examples

# Run all scenarios
sqb scenario test

# Run one scenario
sqb scenario test daily_revenue_minimal

# Run and retain warehouse artifacts
sqb scenario test daily_revenue_minimal --retain

# Run all scenarios in a folder
sqb scenario test revenue

​
Local examples

# Run locally (requires prior capture)
sqb scenario test --local

# Run locally, capture missing/stale snapshots first
sqb scenario test --local --sync-snapshots

# Run locally, recapture everything first
sqb scenario test --local --refresh

# Fail on missing/stale snapshots instead of skipping
sqb scenario test --local --strict

​
Output

Remote scenarios report per-scenario PASS/FAIL with nested check rows: 
daily_revenue_minimal                                            PASS
    check     expected daily_revenue                             PASS
    check     assertion no_negative_revenue                      PASS

PASS=1  FAIL=0  TOTAL=1
Local scenarios add ERROR and SKIP statuses: 
PASS=2  FAIL=0  ERROR=0  SKIP=1  TOTAL=3
Failed scenarios suggest rerunning with --retain for inspection. Local runs always keep the DuckDB file at target/run/scenarios/<scenario_name>/local.duckdb.

​
sqb scenario capture

Capture scenario input fixtures from the warehouse as JSONL snapshots for local replay. 
sqb scenario capture [selectors...] [flags]

​
Flags

FlagDescription
--retainKeep warehouse fixture artifacts after capture
--forceBypass snapshot capture safety limits
--max-snapshot-rowsOverride per-relation row limit
--max-snapshot-total-rowsOverride total row limit
--max-snapshot-bytesOverride per-relation byte limit
--max-snapshot-total-bytesOverride total byte limit
--no-sql-validationSkip compile-time SQL syntax validation

​
Examples

# Capture all scenarios
sqb scenario capture

# Capture one scenario
sqb scenario capture daily_revenue_minimal

# Capture and retain warehouse artifacts
sqb scenario capture daily_revenue_minimal --retain
Snapshots are written to tests/_scenario_snapshots/<scenario_name>/ with a scenario.json manifest and JSONL files for each fixture relation. These files can be committed to version control.

​
Runtime artifacts

Both remote and local scenario runs write runtime artifacts to target/run/scenarios/<scenario_name>/: 
target/run/scenarios/daily_revenue_minimal/
  cleanup/
    prepare.sql
    final.sql
  fixtures/
    ref__stg_orders.sql
    ref__stg_payments.sql
  models/
    marts/daily_revenue.sql
  checks/
    expected__daily_revenue.sql
    assertion__no_negative_revenue.sql
Local runs additionally write to a local/ subdirectory and create local.duckdb.