Patterns of automated game testing: Explicit Waits

If you’re familiar with testing tools for the web like Selenium and Appium, you’ve heard about implicit and explicit waits. What are they, and how do these concepts apply to automated game testing?

Implicit waits

Many testing tools can help you write simpler code by implicitly waiting things for you. For example if you’re looking for a specific element inside a web page, Selenium will wait until the element is here, or throw an exception after a certain time. The amount of time it waits before throwing the exception is the implicit wait. This can be changed at runtime, and having a high value for it is considered an anti-pattern.

Explicit waits

Now if long implicit waits are considered an anti-pattern, the corresponding good practice it is to use explicit waits. While implicit waits are handled by the testing tool, and thus are not visible in your testing code, explicit waits are waits you write yourself.

They’re better than implicit waits because they describe the clear intent of what you’re waiting for. This also helps to provide more context in case a timeout is reached. The error message can provide the exact context of what was waited for, and wasn’t fulfilled. Finally it allows you to have a timeout on a case to case basis instead of a single value applied to every implicit wait.

Waits in automated game testing

When testing video games, there are no implicit waits. The web platform is built on standards, but video games are not. Game engines are very different from each other, and even video games built with the same game engine can be very different. So the testing tools can’t provide reliable ways of implicitly waiting for things.

Instead you have to write explicit waits all the time. It’s actually a good practice and should be done systematically.

Explicit waits in practice

In automated game testing, an explicit wait usually means polling the game state until a certain condition is met. For example: waiting until a specific character is rendered on screen, a UI menu becomes active, or a loading animation is gone. Because every game is fundamentally built differently, you need to define those conditions yourself.

A simple pattern looks like this:

1. Define a predicate (a function returning true or false) checking if a condition is met.
2. Poll that predicate at a regular interval (every frame for example).
3. Stop polling when it returns true, or throw an exception if a timeout is reached.

We briefly mentioned predicates in the previous post, so you can use the ones you already defined in your screen objects. This gives you full control over how long to wait and what failure message to display. For example an error message can look like this:

Expected menu to be active after clicking button x.
Condition failed to be fulfilled within 5 seconds.”

By writing explicit waits this way, you create more deterministic, readable, and maintainable tests. Each wait clearly states what it’s waiting for and why, making debugging much easier when something goes wrong.

A note on hardcoded waits

Writing explicit waits can be cumbersome and often people will take the lazy road and use an hardcoded wait instead. For example in C# it could look like this:

Thread.Sleep(3000); // wait for 3 seconds

It’s a very bad practice because:

• It doesn’t clearly tell us what we are waiting for
• The right duration might change over time. To be on the safe side the duration will be longer than necessary, but then it wastes precious time when running automated tests
• When the duration is not correct anymore, the behaviour can be unpredictable. It can often be too short, causing the expected elements to not be present yet.
  In some cases, it can be too long, and the right elements necessary for the rest of the tests might be gone already

As a rule you should always avoid hardcoded waits, unless there are very very good reasons to do so.

Example

In the previous post about Screen Objects, we covered synchronization methods. Explicit waits are a form of synchronization and you might have noticed a WaitUntilActive method in our C# example. A better version of such method could be the following:

public IEnumerator WaitUntilActive()
{
    yield return ExplicitWait(
        () => IsActive(),
        timeout: TimeSpan.FromSeconds(5),
        "Expected MainScreen scene to be active but wasn't within 5 seconds"
    );
}

Notice how we provide a timeout, and an error message. The ExplicitWait class is up to you to write as an exercise. You can get inspired by another post titled Unity Test Framework: waiting the right way.

Depending on your game engine, this will look drastically different of course.

Conclusion

Unlike web testing, where implicit waits can hide timing issues, automated game testing forces you to be explicit. That’s a good thing. Writing your own waits may seem like a lot of work, but it gives you finer control, clearer intent, and more reliable results than using hardcoded waits.

Explicit waits are a pattern that turns your tests into readable, trustworthy descriptions of how your game is expected to behave, so use them as often as possible.