run_scene_test
Automates headless scene testing by executing driver and assertion actions to validate live game state with per-step pass/fail results.
Instructions
Automated end-to-end / UAT test of a scene. Boots the scene headless (real game loop, no rendering), runs a sequence of steps, and evaluates assertions against live game state. Returns per-assertion pass/fail.
Each step is an object with an "action". Driver actions: {action:"wait_frames",frames:N} | {action:"wait_seconds",seconds:S} | {action:"press_action",name:"jump",strength:1.0} | {action:"release_action",name:"jump"} | {action:"tap_action",name:"jump",frames:2} | {action:"key",key:"Space",pressed:true} | {action:"mouse_button",button:1,position:[x,y],pressed:true} | {action:"mouse_move",position:[x,y]} | {action:"set_property",node:"Path",property:"x",value:1} | {action:"call_method",node:"Path",method:"start",args:[]} | {action:"emit_signal",node:"Path",signal_name:"hit",args:[]} | {action:"watch_signal",node:"Path",signal_name:"hit"} | {action:"wait_for_signal",node:"Path",signal_name:"hit",timeout_seconds:2}. Assertion actions: {action:"assert_property",node:"Path",property:"position",op:">",value:{x:0}} (op: ==,!=,>,<,>=,<=; for vectors/colors only the provided components are checked) | {action:"assert_node_exists",node:"Path",exists:true} | {action:"assert_in_group",node:"Path",group:"mobs",expected:true} | {action:"assert_signal_emitted",node:"Path",signal_name:"hit",min_count:1} (requires a prior watch_signal) | {action:"assert_method_returns",node:"Path",method:"get_score",args:[],op:">=",value:10} | {action:"assert_node_count",group:"mobs",op:">",value:0}. Node paths are relative to the scene root ("" or "root" = root).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | Path to the Godot project directory | |
| scenePath | Yes | Path to the scene to test (relative to project) | |
| steps | Yes | Ordered list of step objects (see description) | |
| timeoutSeconds | No | Max wall-clock seconds for the whole scenario (default 10) |