DOCSEARCHbyAlgolia
Submit Docs

Dear ImGui Test Engine

repository·main·Indexed 20 days ago

https://github.com/ocornut/imgui_test_engine

An automation and testing system for Dear ImGui-based applications. It simulates mouse, keyboard, and gamepad inputs to perform functional and smoke testing, automated asset generation, and performance monitoring in both windowed and headless modes.

Tokens
905
Snippets
1
Records
3
Agent score
20%

What's inside imgui_test_engine

  1. Overview of Dear ImGui Test Engine

    main

    Dear ImGui Test Engine is an automation system designed to test and automate Dear ImGui applications, games, and engines. It works by injecting mouse, keyboard, and gamepad inputs into Dear ImGui's IO, simulating an end-user's interaction. This allows you to test not just the UI, but any part of your application or engine exposed through the ImGui integration.

    Key capabilities include:

    • Functional & Smoke Testing: Automate UI interactions to verify application state.
    • Headless Execution: Run GUI tests on CI servers without a rendering window.
    • Execution Modes: Run at simulated human speed (for video export) or in Fast Mode (using mouse teleportation for speed).
    • Asset Generation: Export screenshots, videos, and GIFs for documentation or visual regression testing.
    • Live Demos: Use scripts to run through application features as a live tutorial.
    • Performance Monitoring: Includes tools to record and compare performance between builds (requires ImPlot).

  2. Project Structure and Integration

    main

    The repository is organized into several components depending on your needs:

    • imgui_test_engine/: The core automation library. Integrate this into your C++ project to enable testing.
    • imgui_test_suite/: A standalone application used for testing the engine itself.
    • app_minimal/: A minimal demo application that demonstrates how to integrate the test engine into your own codebase.
    • shared/: Contains shared C++ helpers used by the applications.

  3. Register and write an automation test

    main

    You can define tests using the IM_REGISTER_TEST macro. A test typically consists of a lambda function that receives an ImGuiTestContext*. Within this context, you can perform high-level actions like clicking items, setting values, or navigating menus. Using SetRef allows you to establish a base path for item lookups, making subsequent commands more concise.

    Common ImGuiTestContext operations:

    • SetRef(path): Sets a base path for relative item lookups.
    • ItemClick(name): Clicks an item by name.
    • ItemCheck(name): Ensures a checkbox/toggle is checked.
    • ItemInputValue(name, value): Sets a specific value for a widget (e.g., a slider).
    • MenuCheck(path): Navigates and interacts with menu paths (e.g., //Menu/Submenu/Item).
    ImGuiTest* test = IM_REGISTER_TEST(e, "demo_test", "test1");
test->TestFunc = [](ImGuiTestContext* ctx)
{
    ctx->SetRef("My Window");           // Set a base path so we don't have to specify full path afterwards
    ctx->ItemClick("My Button");        // Click "My Button" inside "My Window"
    ctx->ItemCheck("Node/Checkbox");    // Open "Node", find "Checkbox", ensure it is checked if not checked already.
    ctx->ItemInputValue("Slider", 123); // Find "Slider" and set the value to 123
    IM_CHECK_EQ(app->SliderValue, 123); // Check value on app side
    
    ctx->MenuCheck("//Dear ImGui Demo/Tools/About Dear ImGui"); // Show Dear ImGui About Window (assume Demo window is open)
};