> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streambuild.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# stb test

> Execute SQL-native model and macro tests against ClickHouse.

Discover, assemble, and execute tests under `tests/`:

```bash theme={null}
stb test
stb test tests/order_events/test_line_total.sql
stb test tests/order_events/
stb test --select order_items
stb test --select +order_items+
stb test --verbose
```

Positional paths and repeated selectors are combined. Paths must resolve inside the project's
`tests/` directory.

Selectors support:

* a bare model name
* `pipeline:<name>`
* leading `+` for upstream graph expansion
* trailing `+` for downstream graph expansion

`--verbose` shows every diff row instead of a bounded failure preview. `--target-dir` replaces the
project-level artifact root.

StreamBuild compiles the full project, executes selected cases independently, and writes the exact
runtime SQL under `target/run/tests/`. Warehouse errors are rendered in command output but are not
persisted there. Test failures and execution errors exit 1. A project with no discovered tests
exits 0; requested selectors or paths that match no tests are errors.

`test` works in both direct and virtual-environment modes. Test queries use CTE-assembled model
logic rather than persisted live or staged model relations.