feat: add support for gvar test files

Author: 1drturtle

README.md

@@ -30,14 +30,23 @@ Language Server Protocol (LSP) implementation targeting Avrae-style draconic ali
 - Tests only (with coverage): `make test` or `uv run pytest tests --cov=src`.
 - CLI smoke test without installing: `uv run python -m avrae_ls --analyze path/to/alias.txt`.
 
-## Alias tests
+## Alias and gvar tests
 
-- Create files ending with `.alias-test` (or `.aliastest`) next to your alias file. Each test starts with an invocation, followed by `---` and the expected result; you can stack multiple tests in one file by repeating this pattern (optional metadata after a second `---` per test).
+- `avrae-ls --run-tests [path]` discovers both alias tests and gvar tests and exits non-zero on failures.
+- Alias tests use `.alias-test` or `.aliastest` next to your alias file. Each test starts with an invocation, followed by `---` and the expected result; you can stack multiple tests in one file by repeating this pattern (optional metadata after a second `---` per test).
   ```
   !my-alias -b example args
   ---
   expected text or number
   ```
+- Gvar tests use `.gvar-test` or `.gvartest` next to a sibling `.gvar` file with the same stem. The test body runs after an implicit `using(...)` import of that module under a sanitized local binding name.
+  ```
+  return my_module.constant
+  ---
+  expected value
+  ```
+- A gvar named `foo-bar.gvar` is exposed to tests as `foo_bar`; a leading digit becomes `gvar_<stem>`.
+- Multi-case `.gvar-test` files are supported. Separate cases with a second `---`, then a blank line before the next test body. Metadata after the second `---` is optional.
 - For embed aliases, put a YAML/JSON dictionary after the separator to compare against the embed preview (partial dictionaries are allowed).
   ```
   !embedtest
@@ -57,7 +66,7 @@ Language Server Protocol (LSP) implementation targeting Avrae-style draconic ali
     name: Tester
   ```
   `name` is a label for reporting, `vars` are merged into cvars/uvars/svars/gvars, and `character` keys are deep-merged into the mock character.
-- Run them with `avrae-ls --run-tests [path]` (defaults to the current directory); non-zero exit codes indicate failures.
+- Gvar tests compare the direct execution result of the test body, not alias preview/embed output.
 
 ## Config variable substitution
 

action.yml

@@ -1,8 +1,8 @@
-name: "Avrae Alias Tests"
-description: "Run avrae-ls alias tests in CI."
+name: "Avrae Alias And Gvar Tests"
+description: "Run avrae-ls alias and gvar tests in CI."
 inputs:
   test-path:
-    description: "Path to search for alias test files."
+    description: "Path to search for alias and gvar test files."
     required: false
     default: "."
   config-path:
@@ -39,7 +39,7 @@ runs:
           fi
           cp "${{ inputs.config-path }}" ".avraels.json"
         fi
-    - name: Run alias tests
+    - name: Run alias and gvar tests
       shell: bash
       env:
         AVRAE_TOKEN: ${{ inputs.avrae-token }}

docs/alias-tests.md

@@ -1,11 +1,11 @@
-# Alias tests
+# Alias and gvar tests
 
-Alias tests let you run a mock alias and compare the result to what you expect. They are small text files that live next to your alias files and can contain many tests per file.
+Alias tests and gvar tests let you run mock Avrae code and compare the result to what you expect. They are small text files that live next to your alias or gvar files.
 
 ## Quick start
 
-1. Create an alias file (for example `greet.alias`).
-2. Create a test file next to it (for example `greet.alias-test`).
+1. Create an alias file such as `greet.alias`, or a gvar module such as `helpers.gvar`.
+2. Create a test file next to it such as `greet.alias-test` or `helpers.gvar-test`.
 3. Run tests:
 
 ```bash
@@ -14,16 +14,19 @@ avrae-ls --run-tests
 
 ## File layout and discovery
 
-Alias tests are discovered by filename. The runner scans for:
+Tests are discovered by filename. The runner scans for:
 
 - `*.alias-test`
 - `*.aliastest`
+- `*.gvar-test`
+- `*.gvartest`
 
 You can run tests in a folder or point to a single test file:
 
 ```bash
 avrae-ls --run-tests .
 avrae-ls --run-tests path/to/greet.alias-test
+avrae-ls --run-tests path/to/helpers.gvar-test
 ```
 
 Example layout:
@@ -33,6 +36,8 @@ my-aliases/
   .avraels.json
   greet.alias
   greet.alias-test
+  helpers.gvar
+  helpers.gvar-test
   combat/
     roll.alias
     roll.alias-test
@@ -47,6 +52,14 @@ The test file sits next to the alias file it targets. The test command decides w
 
 If you keep aliases and tests side by side, you rarely need to think about this.
 
+### How the gvar file is chosen
+
+The gvar test file targets a sibling `.gvar` file with the same stem:
+
+- `helpers.gvar-test` loads `helpers.gvar`
+- `foo-bar.gvar-test` loads `foo-bar.gvar`
+
+
 ## Test file format
 
 Each test has three sections:
@@ -170,17 +183,72 @@ If you just want to make sure the alias runs without error, leave the expected s
 name: "no-output-check"
 ```
 
+## Gvar test format
+
+Each gvar test file contains draconic code that runs after the sibling gvar module is implicitly imported with `using(...)`.
+
+```
+return helpers.constant
+---
+"Constant Gvar value"
+```
+
+- The sibling `.gvar` stem becomes the imported gvar id.
+- The local binding uses the sanitized form of that stem.
+  `foo-bar.gvar` becomes `foo_bar`
+  `123mod.gvar` becomes `gvar_123mod`
+- Gvar tests compare the direct execution result of the test body.
+
+### Multiple gvar tests per file
+
+Use the same repeated block layout, but because there is no `!command` sentinel, include a second `---` before the blank line that separates cases.
+
+```
+return helpers.constant
+---
+"one"
+---
+
+return helpers.other
+---
+"two"
+```
+
+- Metadata after the second `---` is optional.
+- Leave a blank line between cases.
+
+### Gvar metadata
+
+Gvar tests support the same metadata mapping as alias tests:
+
+- `name`
+- `vars`
+- `character`
+
+```
+return helpers.answer + get('bonus')
+---
+12
+---
+name: "adds-bonus"
+vars:
+  cvars:
+    bonus: 7
+```
+
 ## Common tips
 
 - Expected output cannot include a line that starts with `!` because that marks the next test. If you need to check a `!` line, use a single-line string like `"line1\n!line2"` or a regex like `re:^!`.
 - If you want a number treated as text, wrap it in quotes (YAML reads bare numbers as numbers).
 - The mock context comes from `.avraels.json` and any var files you configure there (including gvar `{ filePath: ... }` entries). Metadata `vars` and `character` values are merged on top of those defaults for the test only.
 - Each test runs independently, so one test does not affect another.
-- The expected section is compared against the alias result or embed preview, not against stdout. Stdout is shown in the test report to help debug.
+- Alias tests compare against the alias result or embed preview, not stdout.
+- Gvar tests compare against the direct test-body result, not stdout.
+- Stdout is still shown in the test report to help debug.
 
 ## GitHub Actions
 
-This repo ships a composite action that installs `avrae-ls` and runs alias tests.
+This repo ships a composite action that installs `avrae-ls` and runs alias and gvar tests.
 
 1. Create a minimal config file for CI (for example `.github/avrae/ci.avraels.json`):
 
@@ -196,7 +264,7 @@ This repo ships a composite action that installs `avrae-ls` and runs alias tests
 2. Add a workflow that uses the action:
 
 ```yaml
-name: Alias Tests
+name: Alias And Gvar Tests
 
 on:
   pull_request:
@@ -224,22 +292,26 @@ Use the file path:
 
 ```bash
 avrae-ls --run-tests path/to/greet.alias-test
+avrae-ls --run-tests path/to/helpers.gvar-test
 ```
 
 **Can I put many tests in one file?**
-Yes. Repeat the `command`, `---`, and `expected` blocks as many times as you want.
+Yes. Alias tests can repeat the `command`, `---`, and `expected` blocks. Gvar tests can repeat `body`, `---`, and `expected`, but multi-case gvar files should include the second `---` and a blank line between cases.
 
 **What if I do not care about the output, only that it runs?**
 Leave the expected section empty (see "Run-only tests"). That will pass as long as the alias runs without errors.
 
 **How does it find the alias file?**
 It looks in the same folder as the test file for the alias name in your command (for example `!greet` matches `greet`, `greet.alias`, or `greet.txt`). If your test file is named `test-greet.alias-test`, it will also try `greet`.
 
+**How does it find the gvar file?**
+It loads the sibling `.gvar` file with the same stem as the `.gvar-test` file.
+
 **Can I use JSON instead of YAML?**
 Yes. JSON is valid YAML, so JSON objects and lists work in the expected and metadata sections.
 
 **Why is a gvar missing or `using(...)` failing?**
-Make sure `.avraels.json` enables gvar fetch and sets a token, or provide the gvar in your var files (inline or with `{ filePath: ... }`) or test metadata under `vars.gvars`.
+Make sure `.avraels.json` enables gvar fetch and sets a token, or provide the dependency gvar in your var files (inline or with `{ filePath: ... }`) or test metadata under `vars.gvars`. The module under test itself comes from the sibling `.gvar` file.
 
 **How do I ignore gvar fetch failures in CLI runs?**
 Use `avrae-ls --run-tests --silent-gvar-fetch` to treat remote gvar fetch failures as `None` without warnings.

src/avrae_ls/__main__.py

@@ -20,12 +20,17 @@
     parse_alias_tests,
     run_alias_tests,
 )
+from avrae_ls.testing.gvar_tests import GVarTestError, GVarTestResult, parse_gvar_tests, run_gvar_tests
 from avrae_ls.config import AvraeLSConfig, CONFIG_FILENAME, load_config
 from avrae_ls.runtime.context import ContextBuilder
 from avrae_ls.analysis.diagnostics import DiagnosticProvider
 from avrae_ls.runtime.runtime import MockExecutor
 from avrae_ls.lsp.server import create_server, __version__
 
+ALIAS_TEST_PATTERNS = ("*.alias-test", "*.aliastest")
+GVAR_TEST_PATTERNS = ("*.gvar-test", "*.gvartest")
+RUN_TEST_PATTERNS = ALIAS_TEST_PATTERNS + GVAR_TEST_PATTERNS
+
 
 def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser(description="Avrae draconic alias language server")
@@ -40,7 +45,7 @@ def main(argv: list[str] | None = None) -> None:
         metavar="PATH",
         nargs="?",
         const=".",
-        help="Run alias tests in PATH (defaults to current directory)",
+        help="Run alias and gvar tests in PATH (defaults to current directory)",
     )
     parser.add_argument(
         "--silent-gvar-fetch",
@@ -148,7 +153,7 @@ def _run_alias_tests(
 
     workspace_root = _discover_workspace_root(target)
     log = logging.getLogger(__name__)
-    log.info("Running alias tests in %s (workspace root: %s)", target, workspace_root)
+    log.info("Running alias and gvar tests in %s (workspace root: %s)", target, workspace_root)
 
     config = _load_runtime_config(
         workspace_root,
@@ -161,23 +166,29 @@ def _run_alias_tests(
     builder = ContextBuilder(config)
     executor = MockExecutor(config.service)
 
-    test_files = discover_test_files(target)
-    cases = []
+    test_files = discover_test_files(target, patterns=RUN_TEST_PATTERNS)
+    alias_cases = []
+    gvar_cases = []
     parse_errors: list[str] = []
     for test_file in test_files:
         try:
-            cases.extend(parse_alias_tests(test_file))
-        except AliasTestError as exc:
+            if _is_gvar_test_file(test_file):
+                gvar_cases.extend(parse_gvar_tests(test_file))
+            else:
+                alias_cases.extend(parse_alias_tests(test_file))
+        except (AliasTestError, GVarTestError) as exc:
             parse_errors.append(str(exc))
 
     if parse_errors:
         for err in parse_errors:
             print(err, file=sys.stderr)
-    if not cases:
-        print(f"No alias tests found under {target}")
+    if not alias_cases and not gvar_cases:
+        print(f"No alias or gvar tests found under {target}")
         return 1 if parse_errors else 0
 
-    results = asyncio.run(run_alias_tests(cases, builder, executor))
+    alias_results = asyncio.run(run_alias_tests(alias_cases, builder, executor)) if alias_cases else []
+    gvar_results = asyncio.run(run_gvar_tests(gvar_cases, builder, executor)) if gvar_cases else []
+    results = [*alias_results, *gvar_results]
     _print_test_results(results, workspace_root)
 
     failures = [res for res in results if not res.passed]
@@ -204,14 +215,14 @@ def _load_runtime_config(
     return config
 
 
-def _print_test_results(results: Sequence[AliasTestResult], workspace_root: Path) -> None:
+def _print_test_results(results: Sequence[AliasTestResult | GVarTestResult], workspace_root: Path) -> None:
     total = len(results)
     passed = 0
     for res in results:
         rel = _relative_to_workspace(res.case.path, workspace_root)
         label = f"{rel} ({res.case.name})" if res.case.name else rel
         status = "PASS" if res.passed else "FAIL"
-        print(f"[{status}] {label} (alias: {res.case.alias_name})")
+        print(f"[{status}] {label} ({res.case.target_kind}: {res.case.target_name})")
         if res.passed:
             if res.stdout:
                 print(f"  Stdout: {res.stdout.strip()}")
@@ -323,6 +334,10 @@ def _discover_workspace_root(target: Path) -> Path:
     return current
 
 
+def _is_gvar_test_file(path: Path) -> bool:
+    return path.name.endswith(".gvar-test") or path.name.endswith(".gvartest")
+
+
 def _print_diagnostics(path: Path, diagnostics: Iterable[types.Diagnostic]) -> None:
     diags = list(diagnostics)
     if not diags:

src/avrae_ls/gvar_utils.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import re
+
+
+def sanitize_gvar_binding(label: str) -> str:
+    cleaned = re.sub(r"\W+", "_", str(label))
+    if cleaned and cleaned[0].isdigit():
+        cleaned = f"gvar_{cleaned}"
+    return cleaned or "gvar_import"

src/avrae_ls/lsp/code_actions.py

@@ -9,6 +9,7 @@
 
 from lsprotocol import types
 
+from avrae_ls.gvar_utils import sanitize_gvar_binding
 from avrae_ls.lsp.codes import MISSING_GVAR_CODE, UNDEFINED_NAME_CODE, UNSUPPORTED_IMPORT_CODE
 from avrae_ls.analysis.parser import DraconicBlock
 from avrae_ls.analysis.source_context import build_source_context
@@ -130,7 +131,7 @@ def _using_stub_action(
     diag: types.Diagnostic,
     gvar_id: str,
 ) -> types.CodeAction:
-    alias = _sanitize_symbol(gvar_id)
+    alias = sanitize_gvar_binding(gvar_id)
     insertion_line, indent = _block_insertion(blocks, diag.range.start.line, source)
     edit = _insert_line_edit(insertion_line, indent, f'using({alias}="{gvar_id}")\n')
     return types.CodeAction(
@@ -184,15 +185,6 @@ def _line_indent(source: str, line: int, default: int = 0) -> int:
         if match:
             return len(match.group(1))
     return default
-
-
-def _sanitize_symbol(label: str) -> str:
-    cleaned = re.sub(r"\W+", "_", str(label))
-    if cleaned and cleaned[0].isdigit():
-        cleaned = f"gvar_{cleaned}"
-    return cleaned or "gvar_import"
-
-
 def _kind_allowed(kind: str, only: Sequence[str]) -> bool:
     if not only:
         return True

src/avrae_ls/testing/__init__.py

@@ -1,5 +1,6 @@
-"""Alias test file parsing and execution helpers."""
+"""Alias and gvar test file parsing and execution helpers."""
 
 from . import alias_tests
+from . import gvar_tests
 
-__all__ = ["alias_tests"]
+__all__ = ["alias_tests", "gvar_tests"]