API

Note

We try to document the basics here, but it is not meant as a replacement for the upstream documentation. If you need general help we recommend looking at the test engine wiki, and possibly at the documentation comments in these header files:

imgui_te_engine.h (for the engine API)
imgui_te_context.h (for the test context API)

There are two major parts of the test engine:

The Engine itself. This is the class that executes the tests and handles things like interacting with the GUI.
The TestContext API, which is what you'll use to control the GUI and write the tests.

Danger

For the sake of simplicitly certain parts of the API are not memory-safe. This means that some test engine types are wrapped as raw pointers that are owned by C++ rather than Julia, which means that using them after they have been free'd will cause segfaults. All memory-unsafe types are marked as such in their docstrings.

Because of all that, we recommend using such types only temporarily in the style recommended by the upstream examples. This style is good:

# The test object is never even assigned to a variable
@register_test(engine, "foo", "bar") do ctx
    ...
end

This style is less good:

all_tests = []
t = @register_test(engine, "foo", "bar")
t.TestFunc = ...

# Dangerous because it allows `t` to potentially be accessed after the
# engine has been destroyed.
push!(all_tests, t)

Note that in all the examples in the docstrings below we assume that we have already evaluated:

import CImGui as ig
using ImGuiTestEngine
import ImGuiTestEngine as te

API

Engine

ImGuiTestEngine.Engine — Type

mutable struct Engine

Represents a test engine context. This a wrapper around the upstream ImGuiTestEngine type. Don't create it yourself, use CreateContext().

ImGuiTestEngine.CreateContext — Function

CreateContext(
;
    exit_on_completion,
    show_test_window
) -> ImGuiTestEngine.Engine

Create a test engine context. The keyword arguments don't do anything in this library, they're used to support the test engine in CImGui.jl's renderloop.

Arguments

exit_on_completion=true: Exit the program after the tests have completed.
show_test_window=true: Call ShowTestEngineWindows() while running the tests.

Examples

engine = te.CreateContext()

ImGuiTestEngine.DestroyContext — Function

DestroyContext(engine::ImGuiTestEngine.Engine; throw)

Destroy a test engine context.

Arguments

throw=true: Whether to throw an exception if the engine has already been destroyed.

Examples

engine = te.CreateContext()
te.DestroyContext(engine)

ImGuiTestEngine.Start — Function

Start(
    engine::ImGuiTestEngine.Engine,
    ctx::Ptr{CImGui.lib.ImGuiContext}
)

Start a test engine context. If you're using CImGui.jl's renderloop you must not call this, it will be called automatically for you.

Examples

ctx = ig.CreateContext()
engine = te.CreateContext()
te.Start(engine, ctx)

ImGuiTestEngine.Stop — Function

Stop(engine::ImGuiTestEngine.Engine)

Stop a test engine context.

Examples

ctx = ig.CreateContext()
engine = te.CreateContext()
te.Start(engine, ctx)
te.Stop(engine)

ImGuiTestEngine.TestGroup — Type

primitive type TestGroup <: Enum{Int32} 32

Wrapper for the upstream ImGuiTestGroup enum. Possible values:

TestGroup_Perfs
TestGroup_Tests
TestGroup_Unknown

ImGuiTestEngine.TestRunFlags — Type

primitive type TestRunFlags <: Enum{Int32} 32

Wrapper for the upstream ImGuiTestRunFlags enum. Possible values:

TestRunFlags_None
TestRunFlags_GuiFuncDisable
TestRunFlags_GuiFuncOnly
TestRunFlags_NoSuccessMsg
TestRunFlags_EnableRawInputs
TestRunFlags_RunFromGui
TestRunFlags_RunFromCommandLine
TestRunFlags_NoError
TestRunFlags_ShareVars
TestRunFlags_ShareTestContext

ImGuiTestEngine.QueueTest — Function

QueueTest(
    engine::ImGuiTestEngine.Engine,
    test::ImGuiTestEngine.ImGuiTest
)
QueueTest(
    engine::ImGuiTestEngine.Engine,
    test::ImGuiTestEngine.ImGuiTest,
    run_flags
)

Queue a specific test for execution. If you're using the CImGui.jl renderloop it shouldn't be necessary to call this yourself.

Examples

engine = te.CreateContext()
t = @register_test(engine, "foo", "bar") do ctx
    @info "Hello world!"
end

te.QueueTest(engine, t)

ImGuiTestEngine.QueueTests — Function

QueueTests(engine::ImGuiTestEngine.Engine)
QueueTests(
    engine::ImGuiTestEngine.Engine,
    group::ImGuiTestEngine.TestGroup
)
QueueTests(
    engine::ImGuiTestEngine.Engine,
    group::ImGuiTestEngine.TestGroup,
    filter
)
QueueTests(
    engine::ImGuiTestEngine.Engine,
    group::ImGuiTestEngine.TestGroup,
    filter,
    run_flags
)

Queue all tests in a specific group. If you're using the CImGui.jl renderloop it shouldn't be necessary to call this yourself.

Examples

engine = te.CreateContext()
t = @register_test(engine, "foo", "bar") do ctx
    @info "Hello world!"
end

# Queue all tests
te.QueueTests(engine)

ImGuiTestEngine.ShowTestEngineWindows — Function

ShowTestEngineWindows(engine::ImGuiTestEngine.Engine)

The main test engine window, which lets you run the tests individually. It needs to be called within the render loop.

Examples

ctx = ig.CreateContext()
engine = te.CreateContext()
te.Start(engine, ctx)

# This is the important bit
ig.render(ctx) do
    te.ShowTestEngineWindows(engine)
end

te.Stop(engine)
te.DestroyContext(engine)

Base.isassigned — Method

isassigned(engine::ImGuiTestEngine.Engine) -> Bool

Check if the Engine has a valid pointer to a test engine context.

EngineIO

Some engine settings can be configured with EngineIO:

ImGuiTestEngine.EngineIO — Type

struct CxxRef{ImGuiTestEngine.lib.ImGuiTestEngineIO} <: CxxWrap.CxxWrapCore.CxxBaseRef{ImGuiTestEngine.lib.ImGuiTestEngineIO}

A wee typedef for ImGuiTestEngineIO. Get this from an Engine with GetIO().

Supported properties:

ConfigSavedSettings::Bool
ConfigRunSpeed::RunSpeed
ConfigStopOnError::Bool
ConfigKeepGuiFunc::Bool
ConfigVerboseLevel::TestVerboseLevel
ConfigVerboseLevelOnError::TestVerboseLevel
ConfigRestoreFocusAfterTests::Bool
ConfigCaptureEnabled::Bool
ConfigCaptureOnError::Bool
ConfigNoThrottle::Bool
ConfigMouseDrawCursor::Bool
IsRunningTests::Bool (readonly)

Danger

This a memory-unsafe type, only use it while the engine is alive.

ImGuiTestEngine.GetIO — Function

GetIO(
    engine::ImGuiTestEngine.Engine
) -> CxxWrap.CxxWrapCore.CxxRef{ImGuiTestEngine.lib.ImGuiTestEngineIO}

Get the EngineIO object for an engine.

Examples

engine = te.CreateContext()
engine_io = te.GetIO(engine)

ImGuiTestEngine.TestVerboseLevel — Type

primitive type TestVerboseLevel <: Enum{Int32} 32

Wrapper around the upstream ImGuiTestVerboseLevel. Possible values:

TestVerboseLevel_Silent
TestVerboseLevel_Error
TestVerboseLevel_Warning
TestVerboseLevel_Info
TestVerboseLevel_Debug
TestVerboseLevel_Trace

ImGuiTestEngine.RunSpeed — Type

primitive type RunSpeed <: Enum{Int32} 32

Wrapper around the upstream ImGuiTestRunSpeed. Possible values:

RunSpeed_Fast
RunSpeed_Normal
RunSpeed_Cinematic

Registering tests

Once the engine is set up you can register some tests for it to run:

ImGuiTestEngine.ImGuiTest — Type

mutable struct ImGuiTest

Wrapper around the upstream ImGuiTest. Don't create this yourself, use @register_test(). Once it's created you can assign functions to these properties:

GuiFunc::Function, for standalone GUI code that you want to run/test. This shouldn't be necessary if you're testing your own GUI.
TestFunc::Function, for tests that you want to execute.

The functions you assign must take in one argument to a TestContext.

Danger

This a memory-unsafe type, only use it while the engine is alive.

ImGuiTestEngine.@register_test — Macro

@register_test(engine, category::AbstractString, name::AbstractString)::ImGuiTest
@register_test(f::Function, engine,
               category::AbstractString, name::AbstractString)::ImGuiTest

Register a ImGuiTest. Note that it will not be executed until the test is queued, either programmatically with QueueTests() or by the user running it manually through ShowTestEngineWindows().

Examples

If you only need to set TestFunc you can use do-syntax:

engine = te.CreateContext()
@register_test(engine, "foo", "bar") do ctx
    @imtest ctx isa te.TestContext
end

To set GuiFunc as well you'll need to set the GuiFunc property:

engine = te.CreateContext()
t = @register_test(engine, "foo", "bar")
t.GuiFunc = ctx -> begin
    ig.Begin("Foo")
    ig.End()
end
t.TestFunc = ctx -> @info "Hello world!"

Test context

Inside GuiFunc and TestFunc you can use any methods of the test context API to control and test the GUI. It's not safe to use them outside of a GuiFunc/TestFunc.

Note that even though GuiFunc/TestFunc are passed a TestContext object, it's never necessary to pass it explicitly to any of the methods below because we do some magic to automatically get the right TestContext in the current scope. e.g. SetRef(ctx, "My window") is fine, but it'll do the same thing as SetRef("My window").

Note

Loads of test context methods are missing Julia wrappers, feel free to open an issue or contribute them yourself if you're missing one.

If you want to try calling the wrapped C++ functions directly, it'll probably boil down to something like:

te.lib.Thing(ctx, te.lib.ImGuiTestRef("my ref"))

For functions that take an ImVec2 argument, create one that can be passed to the C++ functions with the un-exported mkImVec2() helper function like so:

te.lib.Thing(ctx, te.mkImVec2(x, y))

ImGuiTestEngine.TestContext — Type

struct CxxPtr{ImGuiTestEngine.lib.ImGuiTestContext} <: CxxWrap.CxxWrapCore.CxxBaseRef{ImGuiTestEngine.lib.ImGuiTestContext}

This is a reference to a ImGuiTestContext. It cannot be created directly, instead the context will be passed to the GuiFunc and TestFunc functions of an ImGuiTest.

Danger

This a memory-unsafe type, only use it while the engine is alive.

ImGuiTestEngine.@imcheck — Macro

@imcheck expr

A port of the upstream IM_CHECK() macro. Like the upstream macro, this will return early from the calling function if expr evaluates to false. Prefer using it over @test because it will register test results with the test engine, which can be convenient if you're using the built-in test engine window (see ShowTestEngineWindows()).

@imcheck hooks into @testset's by default, so a failure will be recorded with your Julia Test tests as well as with the test engine. If this is not wanted it can be disabled by passing jltest=false.

Note

A limitation of the current implementation is that nicely parsing the expression, e.g. to display both arguments of an equality, is not supported.

Examples

engine = te.CreateContext()
@register_test(engine, "foo", "bar") do ctx
    # This record the result with `Test` as well as the test engine
    @imcheck false

    # This will only record the result with the test engine
    @imcheck false jltest=false
end

ImGuiTestEngine.@imcheck_noret — Macro

@imcheck_noret expr

Same as @imcheck, except that it will not return early from the calling function.

ImGuiTestEngine.SetRef — Function

SetRef(test_ref::Union{Int64, String})
SetRef(test_ref::Union{Int64, String}, ctx)

Set the current reference. For more information on references see the upstream documentation.

Examples

@register_test(engine, "foo", "bar") do ctx
    SetRef("My Window")
end

Note that test_ref is always treated as an absolute reference:

@register_test(engine, "foo", "bar") do ctx
    SetRef("My Window/quux") # This will set the reference to `//My Window/quux`

    # These two calls will not work
    SetRef("My Window") # Set the reference to `//My Window`
    SetRef("quux")      # Try to set the reference to `//quux`
end

SetRef(window::Ptr{CImGui.lib.ImGuiWindow})
SetRef(window::Ptr{CImGui.lib.ImGuiWindow}, ctx)

Same as SetRef(::TestRef), except it takes an explicit window to set a reference to.

Examples

@register_test(engine, "foo", "bar") do ctx
    window = GetWindowByRef("Window")
    SetRef(window)
end

ImGuiTestEngine.GetRef — Function

GetRef(

) -> NamedTuple{(:id, :path), <:Tuple{UInt32, Union{Nothing, String}}}
GetRef(
    ctx
) -> NamedTuple{(:id, :path), <:Tuple{UInt32, Union{Nothing, String}}}

Get the current reference, with id and path properties.

Examples

@register_test(engine, "foo", "bar") do ctx
    x = GetRef()
    @show x.id x.path
end

ImGuiTestEngine.MouseClick — Function

MouseClick()
MouseClick(button::CImGui.lib.ImGuiMouseButton_)
MouseClick(button::CImGui.lib.ImGuiMouseButton_, ctx)

Register a click of button.

Examples

@register_test(engine, "foo", "bar") do ctx
    MouseClick()                          # LMB
    MouseClick(ig.ImGuiMouseButton_Right) # RMB
end

ImGuiTestEngine.MouseMove — Function

MouseMove(test_ref::Union{Int64, String})
MouseMove(test_ref::Union{Int64, String}, ctx)

Move the mouse to test_ref.

Examples

@register_test(engine, "foo", "bar") do ctx
    MouseMove("My button")
end

ImGuiTestEngine.MouseMoveToPos — Function

MouseMoveToPos(x, y)
MouseMoveToPos(x, y, ctx)

Move the mouse to the given position in absolute coordinates (e.g. matching ig.GetMousePos() and ig.GetCursorScreenPos()).

Examples

@register_test(engine, "foo", "bar") do ctx
    MouseMoveToPos(100, 100)
    MouseMoveToPos((100, 100))
    MouseMoveToPos(ig.ImVec2(100, 100))
end

MouseMoveToPos(pos::CImGui.lib.ImVec2)
MouseMoveToPos(pos::CImGui.lib.ImVec2, ctx)

MouseMoveToPos(pos::Tuple{Real, Real})
MouseMoveToPos(pos::Tuple{Real, Real}, ctx)

ImGuiTestEngine.ItemOpen — Function

ItemOpen(test_ref::Union{Int64, String})
ItemOpen(test_ref::Union{Int64, String}, flags)
ItemOpen(test_ref::Union{Int64, String}, flags, ctx)

Ensure an item is opened.

Examples

@register_test(engine, "foo", "bar") do ctx
    ItemOpen("My menu")
end

ImGuiTestEngine.ItemClose — Function

ItemClose(test_ref::Union{Int64, String})
ItemClose(test_ref::Union{Int64, String}, flags)
ItemClose(test_ref::Union{Int64, String}, flags, ctx)

Ensure an item is closed.

Examples

@register_test(engine, "foo", "bar") do ctx
    ItemClose("My menu")
end

ImGuiTestEngine.OpenAndClose — Function

OpenAndClose(f, test_ref::Union{Int64, String})
OpenAndClose(f, test_ref::Union{Int64, String}, ctx)

A helper function that will ensure test_ref is open, execute f(), and close test_ref again. A typical use would be to open a section, run some tests, and then close the section again (handy for re-runnable tests).

Examples

@register_test(engine, "foo", "bar") do ctx
    OpenAndClose("My section") do
        # ...
    end
end

OpenAndClose(test_ref::Union{Int64, String})
OpenAndClose(test_ref::Union{Int64, String}, ctx)

Open and then close test_ref.

Examples

@register_test(engine, "foo", "bar") do ctx
    OpenAndClose("My section")
end

ImGuiTestEngine.ItemClick — Function

ItemClick(test_ref::Union{Int64, String})
ItemClick(
    test_ref::Union{Int64, String},
    button::CImGui.lib.ImGuiMouseButton_
)
ItemClick(
    test_ref::Union{Int64, String},
    button::CImGui.lib.ImGuiMouseButton_,
    ctx
)

Simulate a click on the reference.

Examples

@register_test(engine, "foo", "bar") do ctx
    ItemClick("My button")
end

ImGuiTestEngine.ItemDoubleClick — Function

ItemDoubleClick(test_ref::Union{Int64, String})
ItemDoubleClick(test_ref::Union{Int64, String}, ctx)

Simulate a double-click on the reference.

Examples

@register_test(engine, "foo", "bar") do ctx
    ItemDoubleClick("My selectable")
end

ImGuiTestEngine.ItemCheck — Function

ItemCheck(test_ref::Union{Int64, String})
ItemCheck(test_ref::Union{Int64, String}, ctx)

Check an item.

Examples

@register_test(engine, "foo", "bar") do ctx
    ItemCheck("My checkbox")
end

ImGuiTestEngine.MenuClick — Function

MenuClick(test_ref::Union{Int64, String})
MenuClick(test_ref::Union{Int64, String}, ctx)

Click on a menu item.

Examples

@register_test(engine, "foo", "bar") do ctx
    MenuClick("My menu")
end

ImGuiTestEngine.ComboClick — Function

ComboClick(test_ref::Union{Int64, String})
ComboClick(test_ref::Union{Int64, String}, ctx)

Click on a combo box item.

Examples

@register_test(engine, "foo", "bar") do ctx
    ComboClick("My combo/Item 1")
end

ImGuiTestEngine.ComboClickAll — Function

ComboClickAll(test_ref::Union{Int64, String})
ComboClickAll(test_ref::Union{Int64, String}, ctx)

Click on all items in a combo box.

Examples

@register_test(engine, "foo", "bar") do ctx
    ComboClickAll("My combo")
end

ImGuiTestEngine.GetWindowByRef — Function

GetWindowByRef(
    test_ref::Union{Int64, String}
) -> Union{Nothing, Ptr{CImGui.lib.ImGuiWindow}}
GetWindowByRef(
    test_ref::Union{Int64, String},
    ctx
) -> Union{Nothing, Ptr{CImGui.lib.ImGuiWindow}}

Retrieve a ImGuiWindow by reference. This will return nothing if the window was not found.

Examples

@register_test(engine, "foo", "bar") do ctx
    window_ptr = GetWindowByRef("My window")
    @show window_ptr
end

ImGuiTestEngine.Yield — Function

Yield()
Yield(count::Int64)
Yield(count::Int64, ctx)

Yield to the application renderloop for count number of frames (defaults to 1). This is useful if you need to wait for more frames to be drawn for some action to occur (e.g. waiting for a window to appear after checking a checkbox).