# Dear ImGui Test Engine, driving a GUI the way a user would

> The Dear ImGui Test Engine is an automation system for Dear ImGui applications that works from the end user's point of view, injecting mouse, keyboard and gamepad input and then finding its way to the item it needs. It ships as a C++ library, a test suite app and a minimal integration demo, and the library folder carries a licence that is not open source.

**ocornut/imgui_test_engine** — Dear ImGui Automation Engine & Test Suite

- Repository: https://github.com/ocornut/imgui_test_engine
- Stars: 638 · Forks: 85
- Language: C++
- License: not declared
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ocornut-imgui-test-engine

## Dear ImGui is wired deep, so the UI is a handle on everything

The premise of the Dear ImGui Test Engine is a consequence of how Dear ImGui itself works. The project documentation argues that because Dear ImGui tends to be wired into many low-level subsystems within your codebase, you can use that to automate actions interacting with them, and that this may be a very efficient solution to automate and test many things, engine systems included.

That is the key insight and it is worth restating. Dear ImGui renders an immediate mode GUI where widgets are drawn by the application each frame. There is no retained widget tree with stable handles, and no accessibility API to query. The consequence for testing is that conventional UI automation does not work, because automation frameworks look for named elements in a widget hierarchy and Dear ImGui has none.

The test engine's answer is to give up on element lookup and operate the way a person does. The documentation states that the test engine interacts mostly from the point of view of an end-user by injecting mouse, keyboard and gamepad inputs into Dear ImGui's IO. It tries to find its way toward accomplishing an action. Opening an item may mean CTRL+Tabbing into a given window, moving things out of the way, scrolling to locate the item, querying its open status, and so on.

The same page makes the strongest claim about scope: your app can be controlled from Dear ImGui, you can now automate your app, therefore you can test anything exposed in your app or engine, and not only the UI.

The audience is a team building a game editor, a tool, or an engine whose interface is Dear ImGui, and who need regression tests or a demo capture pipeline rather than a UI inspector.

## The API is a list of verbs against a path

The quick overview in the project documentation shows what automation code looks like, and it is short enough to read as a whole.

```cpp
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)
};
```

The mechanics are a test registry, a lambda that receives a context, and a set of commands that take a path. `SetRef` establishes a base path so subsequent commands do not have to spell out the full location, which is the equivalent of a working directory for the UI. `ItemClick`, `ItemCheck` and `ItemInputValue` are the verbs. `MenuCheck` shows a menu path, and the leading double slash in that example means an absolute path from the Dear ImGui Demo root rather than a path relative to the current reference.

The `IM_CHECK_EQ` line is the part that makes this a test framework rather than a robot. The click and the input are the action, but the assertion against `app->SliderValue` is where the correctness check happens, on the application side, where the real value lives. The engine drives the UI, and your own code verifies the result.

Named References are a documented wiki section of their own, and the documentation calls out all the nice uses of `ImGuiTestRef`. That is a sign the path system is more than a convenience: it is the addressing scheme for the whole interface.

## Headless, windowed, fast, or at human speed

The engine's execution modes are what make it usable in a build pipeline rather than only on a developer's machine.

It can run in your windowed application, and it can also run headless, for example running GUI tests from a console or on a CI server without rendering. The documentation also notes the demonstration of the Dear ImGui Test Suite running in Fast Mode with full rendering enabled, which is the combination used to capture video.

Then there is the speed switch. It can run at simulated human speed, for watching or exporting videos, or in fast mode, for example teleporting the mouse. That distinction is more than a convenience. At human speed the input timings are realistic enough to catch bugs that depend on animation or deferred updates, and the video looks like a person using the tool. In fast mode the engine skips the waiting, which is what you want in a CI run, but a timing-dependent bug that a human would hit may not reproduce.

Output is part of the feature set. It can export screenshots and videos and gifs, and the documentation says they can be leveraged for some forms of testing, but also to generate assets for documentation, or to notify teams of certain changes. It adds the point that assets that often need to be updated are best generated from a script instead of manually recreated, cropped or exported. For a game editor whose screenshots appear across a website and a wiki, that is a real saving.

One more capability rounds it out. It includes a performance tool and viewer, which the documentation says was used to record and compare performances between builds and branches. That is optional and requires ImPlot.

## Four directories, three of them optional for you

The repository layout is small and tells you what you actually depend on.

`imgui_test_engine/` is the dear imgui test engine and automation system, the library. `imgui_test_suite/` is the dear imgui test suite, which is an app. `app_minimal/` is a minimal demo app showcasing how to integrate the test engine. `shared/` holds shared C++ helpers for apps.

That is four folders, and the third one is the important one for a first-time user. A minimal demo app that shows how to integrate the engine is the difference between reading a wiki page about integration and copying a working example. The documentation links the wiki section on Setting Up, and the demo app is the other half of it.

The suite app is a separate thing from the library. It is the Dear ImGui test suite proper, and it is also the tool that exercises Dear ImGui itself, since the project uses it to self-test Dear ImGui, to reduce regression and to facilitate contributions. That self-use is the reason the tool exists in public form, and it is also the reason the code is a reasonable reference implementation rather than a toy.

The status section in the documentation adds a caveat that matters for planning. It is currently a C++ API, but down the line the project expects the commands to be better standardized, stored in data files, and callable from other languages. So today, a test written against the engine is a C++ test. If your test suite lives in Python, or your team wants data-driven test files, that is a future direction rather than a current capability.

The other status note is about the project's own history. It has been in use and development since 2018 and only made public at the end of 2022, and the documentation says they will provide best effort to make it suitable for user needs, that you will run into problems and shortcomings, and that they are happy to hear about them. That is an unusually candid statement from a project whose author is well known for the same tone.

## The library is not MIT, and the licence split matters

This is the detail to read before you plan to use the tool, because the licences are not the same.

The `imgui_test_engine/` folder, which is the library itself, is under the Dear ImGui Test Engine License. The documentation summarizes it: free for individuals, educational, open-source and small businesses uses, paid for larger businesses, and license sales to larger businesses are used to fund and sustain the development of Dear ImGui. The full text is in the LICENSE.txt inside that folder.

The `imgui_test_suite/` folder and all other folders are under the MIT License, including the demo app and the shared helpers. So the test suite application, the example and the shared code are permissively licensed, and the component you would embed in your own product is the one that is not.

The practical consequence: a company that wants to use the automation library inside a commercial tool has to check whether it qualifies as a small business, and if it does not, it needs a paid licence. A hobbyist, a student, an open-source project or a small team is covered by the free tier. This is not a source-available trap; it is a deliberate funding model that pays for Dear ImGui's development, and the summary in the documentation is unambiguous about it.

The repository itself carries no license field in its metadata, so the two LICENSE.txt files inside the subfolders are the operative documents. Anyone who assumes the whole repository is MIT because the test suite folder is will be wrong about the part that matters most.

For an engineer evaluating this, the licence question comes before the technical one.

## Screenshots, videos and the limits of a UI-level check

The project is explicit that this is an end-user-level tool, and that boundary defines both what it can and cannot tell you.

Because the engine works through injected input, it verifies what the interface does, not what the engine underneath computes. A test that clicks a button and checks the resulting widget value is a good test of the wiring between the interface and the state. It is not a test of the algorithm that produced the value. The example makes the pattern explicit: the assertion is written by the developer, in the developer's own code, against the developer's own state variable. The framework provides the interaction and the reporting; it does not know what correct means for your application.

The path-based addressing has a matching limitation. Since items are located by walking the interface the way a user would, a test can be fragile against layout changes. A menu entry that moves to a different section of the interface is a different path, and the test will not find it. The engine reports that clearly, as a failure to locate the item, but the fix is a test edit.

The performance tool has the same character. Comparing performances between builds and branches is a comparative measurement made with the same harness, so it tells you about a change relative to a baseline. It is a development aid rather than a benchmark, and the documentation does not present it as anything more.

Where the engine genuinely has no competition in this space is the combination of headless operation and video export for a Dear ImGui application. A tool built for a browser or a native widget toolkit does not apply here, because Dear ImGui exposes neither an accessibility tree nor a stable element handle. The engine's answer, input injection, is the only approach that works without changing the application.

## Conclusion

The Dear ImGui Test Engine suits a team whose tools or game editor are built on Dear ImGui and who want smoke tests, regression checks and recorded videos without hand-writing input plumbing, and it suits them best if they can live with a C++-only API. It does not suit a project that needs a permissive licence for the automation library itself, because the engine folder is under the Dear ImGui Test Engine License, which is free for individuals, educational, open-source and small business use and paid for larger businesses. Verify first that the licence tier covers your organisation, that the test suite application runs in your build environment, and that your application exposes enough of its state for the engine to check results rather than only click pixels.

## FAQ

### What is the Dear ImGui Test Engine?

It is an automation system for Dear ImGui and for applications, games and engines built with Dear ImGui. It injects mouse, keyboard and gamepad input into Dear ImGui's IO and works from the point of view of an end user, trying to find its way to the item it needs.

### How do I integrate the Dear ImGui Test Engine into my application?

The repository ships an app_minimal directory described as a minimal demo app showcasing how to integrate the test engine, and the wiki has a Setting Up section. The engine itself is the imgui_test_engine folder, which you add to your project as a library.

### Can the Dear ImGui Test Engine run without a display?

Yes. The documentation states it can run in your windowed application and can also run headless, for example running GUI tests from a console or on a CI server without rendering.

### What licence applies to the Dear ImGui Test Engine library?

The imgui_test_engine folder is under the Dear ImGui Test Engine License, which the documentation summarizes as free for individuals, educational, open-source and small businesses uses, and paid for larger businesses. The imgui_test_suite folder and all other folders are under the MIT License.

### Does the Dear ImGui Test Engine support languages other than C++?

Not yet. The status section says it is currently a C++ API, and that down the line the commands are expected to be better standardized, stored in data files and called from other languages.

## Sources

- [Issues](https://github.com/ocornut/imgui_test_engine/issues)
- [ocornut/imgui_test_engine on GitHub](https://github.com/ocornut/imgui_test_engine)
- [README](https://github.com/ocornut/imgui_test_engine/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ocornut-imgui-test-engine