integration

In 4.1 we introduced a new set of methods: PerformSynchronousClick, PerformSynchronousDoubleClick and PerformSynchronousRightClick. These methods are only available in our windows adapter currently, but will be extended to other technology stacks in the future. These new methods complement our existing PerformClick, PerformDoubleClick and PerformRightClick. So why do we need synchronous versions of these methods? And why are the existing methods not synchronous? What does synchronous mean in this context anyway?

To understand these functions, let’s take a step back and talk about the Windows message loop. All Windows programs (at least those with a user interface) feature some variation of the following:

MSG msg;
while( GetMessage( &msg, NULL, 0, 0 ) != 0)
{
   TranslateMessage(&msg); 
   DispatchMessage(&msg); 
}

This simple code snippet is the prototypical Windows message loop. Essentially, GetMessage asks Windows for a message and waits. When Windows has a message (such as a keyboard or mouse message), GetMessage returns. The caller then passes the message to TranslateMessage (which turns keyboard messages into char messages), and then DispatchMessage (which passes the message to the actual destination window).

However, not all messages are returned by GetMessage. Only posted messages (input messsages and messages posted using PostMessage) are returned by GetMessage. So what happens to sent messages (messages sent using SendMessage or one of its variants)? These messages are dispatched synchronously to the destination window by GetMessage before it returns. The sequence looks like this:

1. Enter GetMessage.
2. Dispatch all sent messages to the destination windows.
3. Get the next posted message and fill the msg structure.
4. Exit GetMessage.

In truth, it gets a little more complicated than this, particularly when you’re dealing with another application’s message loop. Applications can and do add all sorts of additional processing to the message loop to do special input filtering, show modal dialogs, etc. Moreover, simulating even the simplest click can involve over twenty messages, some sent, some posted, depending on the styles of the destination window.

Unfortunately, directly sending messages to the destination window will not yield the correct behavior because if the application does any special message processing in the message loop we will have bypassed it entirely. Moreover, we never know when one of the twenty messages we send will result in a long running application process that we don’t want to wait for. For these reasons, prior to 4.1, we did not provide any synchronous click functions at all. We filled the message queue and let’er rip.

For most scenarios, this works fine. OpenSpan always waits for new controls to be created using our implicit WaitForCreate methods so there are very few instances where we need to wait for the actual result of a click. However, one of those situations involves our prototypical demo application: calculator. Using the standard click methods, the following automation will return 0 or 4 rather than the desired 8. With the information above can you understand why?

That’s right, each step of the automation doesn’t wait for the previous step to complete. Thus, the automation gets the text before calculator has updated the text field with the final result. The new synchronous click methods do wait for all of the click messages to be processed. Thus, the automation below will return 8 every time.

But what if clicking a button creates a modal dialog? Will OpenSpan wait for the modal dialog to be dismissed by the user before continuing? What if there is no user? What if I want to dismiss the dialog in my automation? Oh noesss!

Simmer down. The short answer is that we do not wait for the modal dialog to be dismissed. Modal dialogs are nothing more than a nested GetMessage loop inside the outer GetMessage loop. Usually the sequence looks something like this:

1. GetMessage returns a mouse up message.
2. DispatchMessage passes the mouse up message to a window.
3. The window procedure creates the modal dialog and shows it.
4. The window procedure calls GetMessage and enters a new message loop to process messages posted to the modal dialog.
5. The user dismisses the modal dialog.
6. The windows procedure exits the message loop and returns.
7. DispatchMessage returns and the outer message loop resumes.

OpenSpan simply waits until step 4, when GetMessage is called again after the mouse up message and returns. Perceptive readers with knowledge of hooking may have guessed how we do this, but for everyone else, it’s sufficient to say that we ensure that each time an application calls GetMessage (or any of its variants such as PeekMessage) the next simulated message is always returned. Some other time, maybe I’ll talk about how we ensure that OpenSpan messages receive priority over other messages and are always processed in order. Until then, I’ll let everyone guess in the comments (everyone except OpenSpan employees, that would be cheating) and give the correct answer a free “Do It on the Desktop” t-shirt.

{ Comments on this entry are closed }