Welcome to the Ranorex Support Portal


Unexpected popup windows are a common reason for failed or disrupted test runs. Handling them properly without code is hard. The PopupWatcherLibrary contains a range of useful methods that automatically deal with popup windows.

To use them, simply ⇢ add the individual methods to the desired recording modules and configure them as described on this page.

On this page


Two prerequisites must be met for the methods to work:

  1. The popup window itself must be stored as a repository item.

  2. The popup window must contain a UI element that closes it. This UI element must also be stored as a repository item.

Note Icon


In our example, we use the OK button. We could also have used the Cancel button or the Close button in the top-right of the popup. The best button to choose depends on the popup window itself.

PopupWatcher methods

There are four different methods, each with a different purpose.


The main method. Waits for a popup window to appear and clicks a UI element to close the window.

You can use this method multiple times to have multiple watchers running at the same time or one after another, each watching for a different popup, for example. However, running popup watchers uses resources, so make sure to stop them when they are no longer needed. This is done with the two Stop* methods (see below).

Available arguments:

RepoItemInfo findElement / clickElement: The repository item representing the popup window itself and the repository item representing the button that should be clicked.


Here is an example for a finished method:


Stops an active popup watcher that has the same values for the arguments findElement and clickElement (see StartPopupWatcher).


Stops all active popup watchers.


Waits for a popup window to appear and pauses the test execution until it disappears. In principle the same as StartPopupWatcher, but only waits for the popup to disappear by itself and does not click anything to make it disappear.


With the prerequesites met and a popup watcher active, Ranorex Studio will automatically pause test execution when encountering a popup and handle it.

In our example, Ranorex Studio clicks the OK button. Afterwards, test execution resumes.

The report also shows that a popup watcher handled a popup.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved