feat(test): add --local to run tests without loading state

`sqlmesh lint --local` skips loading remote state, but `test` had no
equivalent, so a commit hook or an offline unit-test run still opened a
connection to the state backend.

Handle it the same way lint does: the flag is declared on the command
with expose_value=False and the gating happens in the group callback,
which is where Context is constructed before the subcommand runs. The
two commands now share a single OPTIONAL_LOCAL_COMMANDS tuple rather
than each special-casing its own name.

As with lint, multi-repository projects that depend on models which
exist only in remote state may see missing-reference errors under
--local; this is documented alongside the same caveat for lint.

Signed-off-by: Adegbite Ayoade <tripleaceme@gmail.com>

Author: tripleaceme

docs/concepts/tests.md

@@ -463,6 +463,14 @@ You can also run tests that match a pattern or substring using a glob pathname e
 $ sqlmesh test tests/test_*
 ```
 
+You can pass `--local` to run tests without loading state from the configured state connection:
+
+``` bash
+$ sqlmesh test --local
+```
+
+This keeps offline runs and commit hooks from opening a connection to the state backend. As with [`sqlmesh lint --local`](../guides/linter.md), in multi-repository setups, or when running tests for only a subset of projects, `--local` may cause errors because SQLMesh will not resolve references or schemas from models that exist only in remote state.
+
 ### Testing using notebooks
 
 You can execute tests on demand using the `%run_test` notebook magic as follows:

docs/reference/cli.md

@@ -630,6 +630,12 @@ Options:
                        useful for debugging.
   --select-model TEXT  Select specific models to run unit tests for. Can be
                        specified multiple times.
+  --local              Run tests using only locally loaded project files
+                       without loading state. In multi-repository setups, or
+                       when running tests for only a subset of projects, this
+                       may cause errors because SQLMesh will not resolve
+                       references or schemas from models that exist only in
+                       remote state.
   --help               Show this message and exit.
 ```
 

sqlmesh/cli/main.py

@@ -42,6 +42,8 @@
 )
 SKIP_CONTEXT_COMMANDS = ("init", "ui")
 LOCAL_ONLY_COMMANDS = ("format",)
+# Commands that are local-only when they're passed --local.
+OPTIONAL_LOCAL_COMMANDS = ("lint", "test")
 
 
 class _SQLMeshGroup(click.Group):
@@ -129,8 +131,12 @@ def cli(
     load = True
     # Local-only gating must hold for any number of --paths, so it stays outside the block below.
     load_state = ctx.invoked_subcommand not in LOCAL_ONLY_COMMANDS
-    # The parent callback constructs Context before Click invokes `lint`, so inspect its parsed args here.
-    if ctx.invoked_subcommand == "lint" and "--local" in ctx.meta["subcommand_args"]:
+    # The parent callback constructs Context before Click invokes the subcommand, so inspect its
+    # parsed args here.
+    if (
+        ctx.invoked_subcommand in OPTIONAL_LOCAL_COMMANDS
+        and "--local" in ctx.meta["subcommand_args"]
+    ):
         load_state = False
 
     if len(paths) == 1:
@@ -811,6 +817,12 @@ def create_test(
     multiple=True,
     help="Select specific models to run unit tests for.",
 )
+@click.option(
+    "--local",
+    is_flag=True,
+    expose_value=False,
+    help="Run tests using only locally loaded project files without loading state.",
+)
 @click.argument("tests", nargs=-1)
 @click.pass_obj
 @error_handler

tests/cli/test_cli.py

@@ -2530,6 +2530,59 @@ def test_lint_local_runs_without_state(runner: CliRunner, tmp_path: Path, mocker
     mock.assert_not_called()
 
 
+def test_test_still_loads_state(runner: CliRunner, tmp_path: Path, mocker):
+    """Guard that `test` explicitly passes `load_state=True` and still reaches state sync."""
+    mock = _setup_local_only_project(tmp_path, mocker)
+    init_spy = mocker.spy(Context, "__init__")
+
+    runner.invoke(cli, ["--paths", str(tmp_path), "test"])
+
+    assert init_spy.called, "Context was never constructed"
+    for call in init_spy.call_args_list:
+        assert "load_state" in call.kwargs, (
+            "CLI didn't pass load_state= explicitly; missing kwarg defaults to True silently"
+        )
+        assert call.kwargs["load_state"] is True, (
+            f"Context was constructed with load_state={call.kwargs['load_state']} for `test`"
+        )
+    assert mock.called, "state-sync was never accessed during `test`"
+
+
+def test_test_local_runs_without_state(runner: CliRunner, tmp_path: Path, mocker):
+    mock = _setup_local_only_project(tmp_path, mocker)
+    init_spy = mocker.spy(Context, "__init__")
+
+    result = runner.invoke(cli, ["--paths", str(tmp_path), "test", "--local"])
+
+    assert result.exit_code == 0, f"Test failed: {result.output}\nException: {result.exception}"
+    assert init_spy.called, "Context was never constructed"
+    for call in init_spy.call_args_list:
+        assert "load_state" in call.kwargs, (
+            "CLI didn't pass load_state= explicitly; missing kwarg defaults to True silently"
+        )
+        assert call.kwargs["load_state"] is False, (
+            f"Context was constructed with load_state={call.kwargs['load_state']} for `test --local`"
+        )
+    mock.assert_not_called()
+
+
+def test_test_local_runs_without_state_multiple_paths(
+    runner: CliRunner, tmp_path: Path, mocker
+) -> None:
+    """`--local` gating must hold for any number of --paths, matching `lint --local`."""
+    project_a = tmp_path / "a"
+    project_b = tmp_path / "b"
+    _create_local_only_project(project_a, "proj_a")
+    _create_local_only_project(project_b, "proj_b")
+    mock = _patch_state_access(mocker)
+
+    result = runner.invoke(
+        cli, ["--paths", str(project_a), "--paths", str(project_b), "test", "--local"]
+    )
+    assert result.exit_code == 0, f"Test failed: {result.output}\nException: {result.exception}"
+    mock.assert_not_called()
+
+
 @pytest.mark.parametrize("command", ["format"])
 def test_local_only_commands_skip_state_multiple_paths(
     runner: CliRunner, tmp_path: Path, mocker, command: str