[eggPlant Functional] Tips for scripting against tooltips

Scripting Tooltips and Other Transient GUI Elements

If you aren’t familiar with certain features of Eggplant, scripting against something as elusive as a tooltip might seem impossible. They appear briefly on the screen and only when the mouse is in a particular region of the screen, and then they disappear just as you try to capture them. But there are a couple of tips that can make the process more manageable.

Capturing Tooltips

Perhaps the greatest difficulty in this sort of scripting is the capture process; once you’ve made the tooltip appear, how do you get the capture area over it, or even get into capture mode without moving the mouse and having the tooltip disappear? The technique that will facilitate this is using the Command key to toggle between Live mode and Capture mode.

First, with the Remote Screen window in Live mode, get the tooltip on the screen by moving the mouse over the desired GUI item. Now, leaving the mouse where it is, press and release the Command key to put the Remote Screen window into Capture mode, then quickly press Shift-Command-K to close the connection. This will “freeze” the display in the Remote Screen window. It will also close the Remote Screen window, so press Command-0 (zero) to reopen it.

With the display of the Remote Screen window frozen, you can leisurely capture the tooltip (and anything else on the screen) just as you would normally capture any other image. Bear in mind that the tooltip can popup in different locations, depending on where the mouse enters the active region, so be careful to keep your capture area inside the borders of the tooltip to prevent background pixels throwing off your search.

When you’re finished capturing the image, you’ll need to reconnect to the SUT; you can do this quickly by pressing Command-K to bring up the Connection panel and then hitting Return to reconnect to the same SUT.

Note: You can’t generate commands when the connection is closed; you can only capture images. Then you can either enter commands into the script manually, or use the “Insert” option on the Script Editor toolbar.

Validating Tooltips

There is also a potential issue when playing back the script. By default, if Eggplant doesn’t find the image it is looking for when it scans the screen the first time, it will move the mouse to the lower right-hand corner of the screen. Since the display of a tooltip is dependent on the mouse hovering over the GUI item, having the mouse move to the corner of the screen isn’t going to be helpful. Fortunately, you can disable this behavior from within the script itself. The commands to control this behavior are:

setOption shouldRepositionMouse, NO // disables the behavior
setOption shouldRepositionMouse, YES // re-enables the behavior

You may want to create a handler for your tooltip searches that incorporates these setting changes, for example:

function toolTipFound toolTipImage

    // store the starting value for the shouldRepositionMouse option
    // to prevent turning on the option inadvertently
    put getOptions( "shouldRepositionMouse" ) into repoMouse

    // turn off the mouse repositioning
    setOption shouldRepositionMouse, NO

    // set the return value to the result of the image search
    put imageFound( toolTipImage ) into returnValue

    // now restore the starting value of shouldRepositionMouse
    setOptions repoMouse

    return returnValue
end toolTipFound

(This function in the form of a standalone script is available for download at the end of this post.)

You can then call this function, passing it the name of a tooltip image to look for, as follows:

moveTo "MyImage" // Something that should have a tooltip
if not toolTipFound("MyTooltip") then
    LogError "Tooltip has changed or was not displayed"
end if

I’m having an issue with transient error messages that are appearing as tooltips.

Up to here, I’m fine, but

then quickly press Shift-Command-K to close the connection.

This isn’t working for me.

I’m getting a ding when I press Shift-Command-K, but the connection remains open.

Consequently, the display doesn’t freeze, the connection remains open, and the tooltip/error message drifts away to that great bit-bucket in the sky.

Running on a macbook, OSX 10.4, connecting to a client running XP SP2.

Unfortunately, those instructions were written for an earlier version of Eggplant. When new features were introduced providing the ability to have multiple connections open at once, some of these details changed, so you’ll need to use a different technique to capture your tooltip image.

Here’s an approach that should work for you:

First, write a tiny script to capture a “snapshot” image of the screen when the tooltip is showing. For instance, you might create a script called CaptureTooltip.script, like this one:

moveto "myButton"
wait 2 seconds

This script moves the mouse over the object that has a tooltip (a button, in this example) and then waits 2 seconds, which should be long enough for the tooltip to appear, but not so long that it goes off into bit-bucket land again. If you don’t already have an image of the button, you can capture one first, or use coordinates instead (e.g. “moveTo (250,200)” ).

Run this script, then go to the Results tab in the Suite window and view the detailed results for that run (hint: just click on Show Results in the toolbar of the Script window to do this in one step). The third line of the detailed results should be the “capturescreen” command. Click the little circle with an arrow in it, to the right of the Image column on this line. This will open the screen image in the Preview application.

In Preview, drag a selection rectangle to capture just the desired portion of the tooltip (being careful not to include anything outside the tooltip itself). Preview lets you zoom in if you like, to make this easier. Then type Command-C (Copy), followed by Command-N (New From Clipboard) to open a new window containing only the selected image. Type Command-S (Save) and save that image into the Images folder within your suite. Now it’s available to use in your scripts just like any other captured image.

Many thanx. Worked perfectly.