---
name: godot-cli-test-runner
description: Run Godot CLI commands for this project with emphasis on headless test execution, script runs, scene runs, and export/debug operations. Use when the user asks to run Godot tests or commands (for example “Godot 跑测试”, “执行 Godot 命令”, “检查 Godot 参数”), troubleshoot CLI failures, or request reusable terminal/CI command templates.
---

# Godot CLI Test Runner

## Overview
Use deterministic Godot CLI workflows for Windows terminal and CI-style execution. Prefer `--headless`, explicit `--path`, and `--log-file` for reproducible diagnostics.

## Quick Decision
1. Parse-only check script syntax: `--headless --path . --script <file> --check-only`.
2. If test logic depends on autoload singletons (for example `SceneManager`, `LocationManager`, `EventSystem`), do not use direct `--script` as primary validation; use scene/project context first.
3. For isolated script tests without autoload dependencies, run `--headless --path . --script <file>`.
4. Export build by using `--export-release` / `--export-debug` with an existing preset.
5. Diagnose CLI behavior by adding `--verbose` and always writing `--log-file`.

## Workflow

### 1. Resolve executable and project path
1. Prefer `godot` from PATH.
2. If not available, use explicit exe path (for this machine typically `D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64_console.exe` or `D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe`).
3. Run from repository root and always pass `--path .` unless intentionally targeting another project.

### 2. Preflight checks
1. Confirm engine version: `godot --version`.
2. Confirm options when needed: `godot --help`.
3. Confirm project exists: ensure `project.godot` is present under `--path`.
4. Read `project.godot` `[autoload]` and check whether the target test script references those singleton names.
5. Prepare a log output path (for example `.godot/test_xxx.log`) and pass `--log-file`.

### 3. Execute task type
1. Autoload-dependent validation (preferred when script references global singleton names):
`godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log`
2. Scene-specific validation:
`godot --headless --path . --scene res://scenes/Maps/square.tscn --quit-after 90 --log-file .godot/smoke_square.log`
3. Script test (only for isolated logic or known SceneTree tests):
`godot --headless --path . --script tests/unit/test_xxx.gd --log-file .godot/test_xxx.log`
4. Script syntax only:
`godot --headless --path . --script tests/unit/test_xxx.gd --check-only --log-file .godot/check_xxx.log`
5. Export:
`godot --headless --path . --export-release "Web" web_assets/index.html --log-file .godot/export_web_release.log`

### 4. Capture and report results
1. Report exit code, key stdout/stderr lines, and failed command.
2. For failures, include one retry variant (for example add `--verbose`, switch explicit exe path, or switch from `--script` to `--scene` context).
3. Keep output concise and actionable.
4. If `--script` fails with missing singleton identifiers, mark it as context mismatch first, not business regression.

## Command Templates

### Windows (explicit exe)
```powershell
& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64_console.exe" --headless --path . --log-file .godot\test_websocket_close_code.log --script tests/unit/test_websocket_close_code.gd
```

### Generic (PATH)
```powershell
godot --headless --path . --log-file .godot/test_websocket_close_code.log --script tests/unit/test_websocket_close_code.gd
```

### With extra app args
```powershell
godot --headless --path . --log-file .godot/test_runner.log --script tests/unit/test_runner.gd -- --case websocket --timeout 30
```

## Minimal Runnable Examples
Run from repository root (`--path .`).

1. Run one scene-level smoke test (autoload-safe):
```powershell
godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log
```

2. Run one test script (isolated logic):
```powershell
godot --headless --path . --script tests/unit/test_websocket_close_code.gd --log-file .godot/test_websocket_close_code.log
```

3. Run one scene:
```powershell
godot --headless --path . --scene res://scenes/SomeScene.tscn --quit-after 90 --log-file .godot/smoke_scene.log
```

4. Parse script only (syntax check):
```powershell
godot --headless --path . --script tests/unit/test_websocket_close_code.gd --check-only --log-file .godot/check_websocket.log
```

If `godot` is not in PATH, replace `godot` with explicit exe call:
```powershell
& "D:\technology\biancheng\Godot\Godot_v4.5.1-stable_win64.exe" <same arguments>
```

## Option Summary Reference
Use `references/godot-cli-commands.md` for categorized option summary and quick recipes based on `godot --help` output.

## Guardrails
1. Prefer non-interactive commands.
2. Prefer `--headless` for tests and scripts.
3. For this environment, include `--log-file` for reproducible logs and to avoid console build logging issues.
4. Avoid assuming GUT addon exists; check `addons/gut/gut_cmdline.gd` before using GUT command.
5. Use `--check-only` when user requests parse/syntax validation only.
6. For long-running runs, include `--quit-after` when appropriate.
7. Do not classify missing autoload singleton errors in `--script` mode as product regressions until scene/project-context validation is also run.