Understanding timeouts in WebdriverIO

Timeouts are one of the vital parts of UI end-to-end testing. When testing user interfaces, we often need to deal with various forms of randomness (or apparent randomness) in how elements appear and interact.

WebdriverIO handles this by having commands that run in a loop, trying to locate elements or make assertions until they either succeed or eventually fail. You can think of timeouts as upper limits - if the desired action happens within the timeout period, the script continues.

Timeouts vs. Hard Waits

So how are timeouts different from hard waits? Hard waits or pauses stop the test execution altogether. When using a hard wait, we essentially disconnect from the application under test, hoping that during this pause the application reaches the desired state. This approach is flaky by design because it's detached from what the application is actually doing.

Timeouts, on the other hand, are a great way to stay connected to the application under test. Because they enable us to constantly check the state of the application, they are typically faster - we move on to the next command as soon as the condition is met.

Types of Timeouts in WebdriverIO

Let's look at timeouts in a real-life scenario. I have a small game application with three closed doors that open to reveal different characters - some are enemies and some we should protect.

Whenever we run this game, the time it takes for a character to appear is random, which poses a challenge for our test.

Here's a basic test that handles this randomness:

This test passes even with random timing because the waitForDisplayed command keeps retrying until it finds the element. But how long does it wait?

The answer is in the WebdriverIO config:

The waitforTimeout setting dictates how long we want to wait for all waitFor commands (like waitForDisplayed, waitForClickable, waitForEnabled, etc.). If we were to change this timeout to 1 second, our test would likely fail since elements often take longer to appear.

We can also set timeouts for individual commands:

Test Suite Timeouts

Another important timeout determines the length of the whole test. In our example, the test takes about 12 seconds to finish. For longer tests, we might want to set an upper limit using Mocha's timeout option.

The default Mocha timeout is 30 seconds, but we can adjust this in the config:

Best Practices

Timeouts are a great way to set upper limits for actions in our tests, but you need to be careful not to set them too high. Remember that the timeout is also the time it takes for your test to fail. If you have multiple tests in your suite that are going to fail, high timeouts will significantly increase the overall execution time.