106 lines
5.3 KiB
Markdown
106 lines
5.3 KiB
Markdown
---
|
|
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.
|