Scene Runner

Definition

The Scene Runner is a tool used for simulating interactions on a scene. With this tool, you can simulate input events such as keyboard or mouse input and/or simulate scene processing over a certain number of frames.

This tool is typically used for integration testing a scene.

For more advanced example, see Tutorial - Testing Scenes

How to Use It

The Scene Runner is managed by the GdUnit API and is automatically freed after use. One Scene Runner can only manage one scene. If you need to test multiple scenes, you must create a separate runner for each scene in your test suite.

GdScript
C#

To use the Scene Runner, load the scene to be tested with scene_runner(<scene>).
```
var runner := scene_runner("res://my_scene.tscn")
```
To use the Scene Runner, load the scene to be tested with ISceneRunner.Load(<scene>).
```
ISceneRunner runner = ISceneRunner.Load("res://my_scene.tscn");
```

Here is a short example:

GdScript
C#

func test_simulate_frames(timeout = 5000) -> void:
    # Create the scene runner for scene `test_scene.tscn`
    var runner := scene_runner("res://test_scene.tscn")

    # Get access to scene property '_box1'
    var box1: ColorRect = runner.get_property("_box1")
    # Verify it is initially set to white
    assert_object(box1.color).is_equal(Color.WHITE)
    
    # Start the color cycle by invoking the function 'start_color_cycle' and await 10 frames being processed
    runner.invoke("start_color_cycle")        
    await runner.simulate_frames(10)

    # After 10 frames, the color should have changed to black
    assert_object(box1.color).is_equal(Color.BLACK)

[TestCase]
public void simulate_frame() {
    // Create the scene runner for scene `test_scene.tscn`
    ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

    // Get access to scene property '_box1'
    ColorRect box1 = runner.GetProperty("_box1");
    // Verify it is initially set to white
    AssertObject(box1.color).IsEqual(Color.WHITE);
    
    // Start the color cycle by invoking the function 'start_color_cycle' and await 10 frames being processed
    runner.Invoke("start_color_cycle")        
    await runner.SimulateFrames(10);

    // After 10 frames, the color should have changed to black
    AssertObject(box1.color).IsEqual(Color.BLACK);
}

Function Overview

Processing and Rendering Your Scene

This section provides guidance on how to process and render your scene during tests using GdUnit4.

GdScript
C#

Function	Description
simulate_frames	Simulates scene processing for a certain number of frames (respecting time factor).
set_time_factor	Sets how fast or slow the scene simulation is processed (clock ticks versus the real).
move_window_to_foreground	Restores the scene window to a windowed mode and brings it to the foreground.

Function	Description
SimulateFrames	Simulates scene processing for a certain number of frames (respecting time factor).
SetTimeFactor	Sets how fast or slow the scene simulation is processed (clock ticks versus the real).
MoveWindowToForeground	Restores the scene window to a windowed mode and brings it to the foreground.

simulate_frames

The simulate_frames function allows you to simulate the processing and rendering of a specified number of frames in your scene. This is particularly useful for testing and debugging, as it provides a way to advance the scene’s state over time without user input or external triggers.

This function is useful when you need to validate behaviors that depend on frame updates, such as animations, physics, and scripted events.
Simulate frame progression in your scene to test animations, interactions, and time-based logic under controlled conditions.

GdScript
C#

It takes the following arguments:

# frames: the number of frames to process
# delta_ms: the time delta between each frame in milliseconds, by default no delay is set.
func simulate_frames(frames: int, delta_ms := -1) -> GdUnitSceneRunner:

Here is an example of how to use simulate_frames:

var runner := scene_runner("res://test_scene.tscn")

# Simulate scene processing over 60 frames at normal speed
await runner.simulate_frames(60)

# Simulate 60 frames with a delay of 100ms between each frame
await runner.simulate_frames(60, 100)

It takes the following arguments:

/// <summary>
/// Simulates scene processing for a certain number of frames by given delta peer frame by ignoring the current time factor
/// </summary>
/// <param name="frames">the number of frames to process</param>
/// <param name="deltaPeerFrame">the time delta between each frame in milliseconds, by default no delay is set.</param>
/// <returns>Task to wait</returns>
Task SimulateFrames(uint frames, uint deltaPeerFrame);

Here is an example of how to use SimulateFrames:

ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");

// Simulate scene processing over 60 frames at normal speed
await runner.SimulateFrames(60);

// Simulate scene processing over 60 frames with a delay of 100ms between each frame
await runner.SimulateFrames(60, 100);

set_time_factor

The set_time_factor function adjusts the speed at which the scene simulation is processed relative to real time.
This is useful for testing in different gameplay speeds, debugging time-dependent interactions.

GdScript
C#

It takes the following arguments:

## Sets the time factor for the scene simulation.
## [member time_factor] : A float representing the simulation speed.
## - Default is 1.0, meaning the simulation runs at normal speed.
## - A value of 2.0 means the simulation runs twice as fast as real time.
## - A value of 0.5 means the simulation runs at half the regular speed.
func set_time_factor(time_factor: float = 1.0) -> GdUnitSceneRunner:

Here is an example of how to use set_time_factor:

var runner := scene_runner("res://test_scene.tscn")

# Set the simulation speed to five times faster as the normal speed.
runner.set_time_factor(5)

# Simulated 60 frames ~5 times faster now  
await runner.simulate_frames(60)

It takes the following arguments:

/// <summary>
/// Sets how fast or slow the scene simulation is processed (clock ticks versus the real).
/// </summary>
/// <param name="timeFactor"></param>
/// <returns>SceneRunner</returns>
ISceneRunner SetTimeFactor(double timeFactor = 1.0);

Here is an example of how to use SetTimeFactor:

ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");
// Set the simulation speed to five times faster as the normal speed.
runner.SetTimeFactor(5);
// Simulated 60 frames ~5 times faster now  
await runner.SimulateFrames(60);

move_window_to_foreground

The move_window_to_foreground function restores the scene window to a windowed mode and brings it to the foreground.
This ensures that the scene is visible and active during testing, making it easier to observe and interact with, as the window are minimized or moved to the background after each test.

This function is essential for scenarios where the scene needs to be actively monitored or interacted with during automated tests. Without it, the scene may not be visible or accessible, which can hinder the debugging process.

GdScript
C#

## Restores the scene window to a windowed mode and brings it to the foreground.
## This ensures that the scene is visible and active during testing, making it easier to observe and interact with.
func move_window_to_foreground() -> GdUnitSceneRunner:

Here is an example of how to use move_window_to_foreground:

var runner := scene_runner("res://test_scene.tscn")

# Shows the running scene and moves the window to the foreground
runner.move_window_to_foreground()

/// <summary>
/// Shows the running scene and moves the window to the foreground. 
/// </summary>
void MoveWindowToForeground();

Here is an example of how to use MoveWindowToForeground:

ISceneRunner runner = ISceneRunner.Load("res://test_scene.tscn");
// Shows the running scene and moves the window to the foreground
runner.MoveWindowToForeground();

Scene Runner

Definition

How to Use It

Function Overview

Processing and Rendering Your Scene

simulate_frames

set_time_factor

move_window_to_foreground

document version v4.4.0