feat(test): select unit tests by name and require unique test names (#989)

* feat(test): require globally unique unit-test and scenario names

Unit-test names (TEST name or file stem) and scenario names now join the
global resource-name rule with models, sources, seeds, functions, Python
nodes, providers and hooks. A clash is a compile error naming both kinds and
files; cases of one parameterized test share its name. Fixtures that named a
test or scenario after its model are renamed.

* feat(test): select unit tests by name

sqb test and sqb build accept a unit-test name, bare or as test:<name>, with
glob patterns. Test selectors union with resource selectors, --case still
narrows, and selecting only tests runs them without building models. Every
other command rejects unit-test selectors with S013, and unknown names
suggest the closest selectable names.

Author: kvlonge

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/build.md

@@ -72,7 +72,7 @@ own option. `--version` works only directly after `sqb`, as in `sqb --version`:
 | `--selection-diagnostics` | Warn when a selected model will build on changed upstream models that are not selected; see [Selection and staleness](../concepts/planning/selection-and-staleness.md) |
 | `--manifest` | Generate `target/manifest.json` with plan-aware project metadata |
 | `SELECTOR ...` | Positional selectors, the same as `--select` |
-| `--select`, `-s` | Select specific models |
+| `--select`, `-s` | Select specific models, or unit tests by name (`test:<name>`); selecting only unit tests runs them without building models |
 | `--exclude` | Exclude specific models |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `build` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/test.md

@@ -23,12 +23,19 @@ Positional `SELECTOR` arguments work like `--select`, and both forms can be comb
 |------|-------------|
 | `--no-sql-analysis` | Disable compile-time SQL analysis (`--no-sql-validation` is an alias) |
 | `SELECTOR ...` | Positional selectors, the same as `--select` |
-| `--select`, `-s` | Select tests targeting specific models |
-| `--exclude` | Exclude tests targeting specific models |
+| `--select`, `-s` | Select tests by name (`order_status_rules` or `test:order_status_rules`), or the tests targeting specific models |
+| `--exclude` | Exclude tests by name, or the tests targeting specific models |
 | `--warehouse <name>` | Snowflake warehouse for this invocation; overrides the target's `query` [warehouse group](../concepts/project-configuration.md#command-group-warehouses) and the connection warehouse |
 
-Parameterized cases use parent-level selection. Selecting a target model includes every case in
-each matching `TEST` template; case names are not model selectors.
+Test names are globally unique, so a bare test name selects exactly that test. `test:<name>` is the
+explicit form and accepts the same glob patterns as names, such as `test:orders_*`. A bare pattern
+selects tests only when it matches no other resource. Test selectors are unioned with model
+selectors, so `sqb test test:order_status_rules stg_orders` runs that test and every test targeting
+`stg_orders`. Test selectors cannot use `+` graph expansion or `,` intersection. Only `sqb test` and
+`sqb build` accept test selectors; other commands reject them with `S013`.
+
+Parameterized cases use parent-level selection. Selecting a test or a target model includes every
+case of each matching `TEST` template, and `--case` narrows the run to one case name.
 
 Text output identifies each case as `<parent> [<case>]` and includes its source path and safe typed
 parameters. Structured JSON emits one check per case with stable source/block/case identity,
@@ -44,4 +51,10 @@ sqb test
 
 # Run tests for a specific model
 sqb test stg_orders
+
+# Run one test by name
+sqb test order_status_rules
+
+# Run one case of a parameterized test
+sqb test test:order_status_rules --case open_case
 ```

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/python-nodes/overview.md

@@ -162,7 +162,7 @@ sqb build --select tag:exports             # by tag
 sqb build --select +orders_export           # with upstreams
 ```
 
-Names are globally unique across models, sources, seeds, functions, loaders, tasks, assets, checks, providers, and hooks.
+Names are globally unique across models, sources, seeds, functions, loaders, tasks, assets, checks, providers, hooks, unit tests, and scenarios.
 
 ## Lifecycle: run, build, check
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/scenarios.md

@@ -44,7 +44,7 @@ tests/
       fulfillment__late_shipment.sql
 ```
 
-Folders are organizational only. The scenario name is the filename stem and must be globally unique across all discovered scenario files.
+Folders are organizational only. The scenario name is the filename stem. Like model, source, seed, and unit-test names, it must be globally unique across the project.
 
 ### Scenario format
 

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/selectors.md

@@ -80,6 +80,19 @@ sqb build --select seed:waffle_types
 sqb build --select source:raw__orders
 ```
 
+### Unit test
+
+`sqb test` and `sqb build` select SQL unit tests by name. Test names are globally unique, so a bare
+name works; `test:` is the explicit form and accepts glob patterns:
+
+```bash
+sqb test order_status_rules
+sqb test "test:orders_*" stg_customers
+```
+
+Test selectors are unioned with other selectors and cannot use `+` or `,`. Other commands reject
+them with `S013`.
+
 ## Graph expansion
 
 ### Upstream
@@ -163,6 +176,14 @@ error[S007]: unknown selector name 'missing_*'
 error[S009]: no models found under path 'models/nonexistent'.
 error[S000]: no SQL resources or Python nodes found with tag 'nonexistent_tag'
 error[S003]: path selector 'fact_orders~' requires names on both sides of '~'
+error[S013]: selector 'order_status_rules' selects a unit test; only `sqb test` and `sqb build` accept unit-test selectors
+```
+
+Unknown names suggest the closest selectable names, including unit tests:
+
+```
+error[S007]: unknown selector name 'order_status_rule'
+  = help: did you mean 'order_status_rules'?
 ```
 
 If a path selector omits the root directory, SQLBuild asks for the explicit form:

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/testing.md

@@ -548,7 +548,11 @@ CTE prefixes from other modes are not allowed. For example, `__source__` in a ma
 
 ## Multiple tests per file
 
-A single test file can contain multiple `TEST()` blocks. Each block must have a unique `name`:
+A single test file can contain multiple `TEST()` blocks. A test's name is its `name`, or the file
+stem when `name` is omitted. Test names are globally unique: a test cannot share a name with another
+test, a scenario, a model, a source, a seed, a function, or a Python node. Name the file or the block
+after the behavior it checks, such as `orders_status_rules`, rather than after the model. The cases
+of one parameterized test share its name. Each block in a file must have its own `name`:
 
 ```sql
 TEST (name "completed_orders_only");

src/sqlbuild/.agents/skills/sqlbuild/references/testing.md

@@ -23,6 +23,10 @@
 
 Files live under `tests/unit/` (any subfolder). Each file is a `TEST();` header, CTEs, and a
 required closing `SELECT 1`.
+A test's name is its `name` or the file stem. Test names are globally unique across tests,
+scenarios, models, sources, seeds, functions and Python nodes, so never name a test file after its
+model (`test_stg_orders.sql`, not `stg_orders.sql`). Run one test with `sqb test <test name>` or
+`sqb test test:<name>`; only `sqb test` and `sqb build` accept test selectors.
 
 ```sql
 -- tests/unit/test_stg_orders.sql

src/sqlbuild/cli/commands/_helpers/build_planning/defer_clone.py

@@ -32,6 +32,7 @@
 from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
 from sqlbuild.compiler.pipeline.main.clone_with_options import run_clone_pipeline_with_options
 from sqlbuild.compiler.pipeline.main.compiled_project import build_compiled_project
+from sqlbuild.compiler.pipeline.main.unit_test_selection import split_unit_test_selectors
 from sqlbuild.compiler.pipeline.models import (
     ClonePipelineConnection,
     ClonePipelineOptions,
@@ -44,7 +45,7 @@
     resolve_skipped_view_chain,
 )
 from sqlbuild.compiler.planner.main.selection.scope import build_planner_scope
-from sqlbuild.compiler.planner.models import PlannerScope
+from sqlbuild.compiler.planner.models import PlannerScope, UnitTestSelectorSplit
 from sqlbuild.compiler.planner.types import MaterializationType
 from sqlbuild.executor.clone.main.build_destination_transient_models import (
     build_destination_transient_models,
@@ -173,6 +174,17 @@ def run_defer_clone_boundary_prephase(
 ) -> DeferClonePrephaseOutcome:
     """Resolve defer-clone boundaries and clone them before build planning."""
 
+    split: UnitTestSelectorSplit = split_unit_test_selectors(
+        select=request.select,
+        exclude=request.exclude,
+        discovered_inputs=invocation.discovered_inputs,
+    )
+    if not split.sql_test_selection.models_selected:
+        return DeferClonePrephaseOutcome(
+            destination_target_name=invocation.effective_target_name,
+            boundary_selectors=(),
+            view_chain_selectors=(),
+        )
     cloned_project: CompiledProject
     boundary_selectors: tuple[str, ...]
     view_chain_selectors: tuple[str, ...]
@@ -187,8 +199,8 @@ def run_defer_clone_boundary_prephase(
         selected_target=request.selected_target,
         no_sql_validation=request.no_sql_validation,
         no_cache=request.no_cache,
-        select=request.select,
-        exclude=request.exclude,
+        select=split.select,
+        exclude=split.exclude,
         cli_vars=request.cli_vars,
         project_dir=invocation.effective_project_dir,
         auto_load_sources=invocation.should_load_sources,
@@ -208,7 +220,7 @@ def run_defer_clone_boundary_prephase(
             no_sql_validation=request.no_sql_validation,
             no_cache=request.no_cache,
             select=(*boundary_selectors, *view_chain_selectors),
-            caused_by_names=request.select,
+            caused_by_names=split.select,
             cli_vars=request.cli_vars,
             connection_config=invocation.connection_config,
             project_dir=invocation.effective_project_dir,

src/sqlbuild/cli/commands/_helpers/build_planning/planning.py

@@ -59,6 +59,7 @@ def _run_build_compile_pipeline(
             max_microbatches=request.max_microbatches,
             selection_diagnostics=request.selection_diagnostics,
             plan_sql_tests=request.run_tests,
+            accepts_unit_test_selectors=True,
         ),
         hooks=ConnectionHooks(
             on_progress=invocation.planning_progress.on_progress,

src/sqlbuild/cli/commands/_helpers/check/execution.py

@@ -24,6 +24,7 @@
 )
 from sqlbuild.compiler.discovery.models import DiscoveredCheckFunction
 from sqlbuild.compiler.pipeline.main.project_relation_targets import build_project_relation_targets
+from sqlbuild.compiler.pipeline.main.reject_unit_test_selectors import reject_unit_test_selectors
 from sqlbuild.compiler.pipeline.models import CompilePipelineResult
 from sqlbuild.compiler.python_nodes.main.graph import build_discovered_python_node_graph
 from sqlbuild.compiler.python_nodes.main.run_lifecycle import build_python_sql_run_lifecycle
@@ -57,6 +58,11 @@ def prepare_check_execution(
     python_graph: PythonNodeGraph = build_discovered_python_node_graph(
         discovered_inputs=invocation.discovered_inputs
     )
+    reject_unit_test_selectors(
+        select=request.select,
+        exclude=request.exclude,
+        discovered_inputs=invocation.discovered_inputs,
+    )
     check_names: frozenset[str] = resolve_selected_check_names(
         graph=python_graph,
         select=request.select,