whale-town-front/.claude/skills/godot-cli-test-runner/SKILL.md

name, description

name	description
godot-cli-test-runner	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)

& "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)

godot --headless --path . --log-file .godot/test_websocket_close_code.log --script tests/unit/test_websocket_close_code.gd

With extra app args

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):

godot --headless --path . --scene res://scenes/MainScene.tscn --quit-after 120 --log-file .godot/smoke_main.log

2. Run one test script (isolated logic):

godot --headless --path . --script tests/unit/test_websocket_close_code.gd --log-file .godot/test_websocket_close_code.log

3. Run one scene:

godot --headless --path . --scene res://scenes/SomeScene.tscn --quit-after 90 --log-file .godot/smoke_scene.log

4. Parse script only (syntax check):

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:

& "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.