WaitBitmap Method


AnyWin class.


Waits for a screen image to match a saved bitmap within a timeout interval, and returns the time it took for the bitmap to appear.


nSeconds = window.WaitBitmap (sBitmapFile, nTimeout [, Rect] [, sMaskFile])
Variable Description
nSeconds The seconds it took for the bitmap to appear. NUMBER.
sBitmapFile The name of the file to compare against the current state of the screen. The filename can include a relative or absolute path. If you use the default bitmap location when you capture a bitmap (you did not specify a file location, only the name), the bitmap is saved in the working directory for the Agent on the machine that runs the Agent. In this case, you do not need to specify the file path, just the filename when you verify the bitmap. If you use a relative path or absolute path when you capture the bitmap, you must specify the full path for the bitmap to verify it. STRING.
nTimeout The length of time in seconds (or fractions of seconds) for WaitBitmap to wait before raising an exception. NUMBER.
Rect Optional: The area to capture, relative to the window. If Rect is omitted, Silk Test Classic captures the entire window. RECT.
sMaskFile Optional: The name of the file containing the bitmap mask to apply to the comparison. STRING.


WaitBitmap compares the current window or screen region against the stored sBitmapFile during the time-out interval nTimeout. Calling WaitBitmap is equivalent to calling VerifyBitmap repeatedly until it succeeds or until nTimeout expires.

You specify a record of the RECT data type.

WaitBitmap returns the number of seconds that it took for the bitmap to appear and remain stable, as determined by the interval from the time the method was called to the time the first snapshot of a group of identical snapshots was taken. Snapshots are taken at the interval specified by the OPT_BITMAP_MATCH_INTERVAL option. The number of snapshots required to consider the bitmap stable is specified with the OPT_BITMAP_MATCH_COUNT option.

If the bitmap does not become stable within the timeout period, Silk Test Classic raises the exception E_BITMAP_NOT_STABLE.

If sBitmapFile and the current state of the window or screen region do not compare equal by the end of the time-out interval, WaitBitmap saves the two bitmaps in sBitmapFile.rmp and raises the exception E_BITMAPS_DIFFERENT. You can use the Silk Test Bitmap Tool to view the differences between them.

The number WaitBitmap returns, which tells you how long it took the image to stabilize, is a useful performance measurement. You can also use WaitBitmap instead of VerifyBitmap in instances where you need to synchronize the speed of a 4Test script with the speed of an application, for example, by waiting for the application to redraw a screen.

WaitBitmap interprets the coordinates (0,0) as the top-left corner of the window’s frame. To capture a bitmap of a window’s client area only, specify window.ClientArea as the window to capture.

If the screen image and the saved bitmap file use different color tables, Silk Test Classic prints the warning E_BITMAPS_DIFF_COLORTABLE. If the bitmaps are not exactly the same but their differences are below the allowable tolerance level (set with the OPT_BITMAP_PIXEL_TOLERANCE option), Silk Test Classic prints the warning E_BITMAPS_ALMOST_MATCH.

The Open Agent and Classic Agent capture bitmaps in different color depths. By default, the Open Agent captures bitmaps using the current desktop settings for color depth. The Classic Agent captures bitmaps as 24-bit images. If you create a mask file for the captured bitmap using the Bitmap Tool that comes with Silk Test, the mask file is saved as a 24-bit bitmap. If the bitmap mask file does not have the same color depth as the bitmap that you capture, an error occurs. To ensure that VerifyBitmap functions do not fail due to different color-depth settings between the captured image and the mask image, ensure that the bitmaps have the same color depth.

To view, capture, and compare bitmaps, and to create monochrome mask files, use the Silk Test Bitmap Tool.


WaitBitmap can only monitor the screen if an application relinquishes control in a specific situation. Therefore, WaitBitmap is not useful for performance testing on Microsoft Windows in all situations. If WaitBitmap always seems to return zero, then it cannot run until the task you want to time has completed.


Elements.WaitBitmap ("sbitfile.bmp", 20)