[Expand]General Information/viewarticle/63445/
 [Expand]Using Help System/viewarticle/55799/
 [Expand]Getting Started Tutorial/viewarticle/56246/
 [Expand]Using TestComplete/viewarticle/57875/
 [Expand]Testing Types/viewarticle/62721/
 [Expand]Applications Testing/viewarticle/62606/
 [Expand]Working With Application Objects and Controls/viewarticle/55815/
 [Expand]Samples and Tutorials/viewarticle/56239/
  [Expand]Test Objects/viewarticle/57881/
  [Expand]Scripting Objects/viewarticle/57882/
  [Collapse]Project and Project Item Objects/viewarticle/57880/
   [Expand]Project Suite Objects/viewarticle/59766/
   [Collapse]Project Item Objects/viewarticle/59767/
     ActiveX Objects/viewarticle/56464/
    [Expand]Android Gesture Collection/viewarticle/59748/
    [Expand]Image Repository/viewarticle/59749/
    [Expand]Keyword Testing/viewarticle/59771/
    [Expand]Low-Level Procedures Collection/viewarticle/59772/
    [Expand]Manual Tests/viewarticle/59773/
    [Expand]Name Mapping/viewarticle/59774/
    [Expand]Network Suite/viewarticle/59775/
       Regions Object/viewarticle/55165/
      [Collapse]Regions Object Methods/viewarticle/58341/
        Add Method/viewarticle/55423/
        AddPicture Method/viewarticle/55222/
        Compare Method/viewarticle/55076/
        Contains Method/viewarticle/58268/
        ContainsFile Method/viewarticle/58261/
        Count Method/viewarticle/58264/
        CreateRegionInfo Method/viewarticle/55741/
        FileNameByIndex Method/viewarticle/58265/
        FileNameByName Method/viewarticle/58267/
        FileNamesList Method/viewarticle/58263/
        Find Method/viewarticle/55091/
        FindRegion Method/viewarticle/55077/
        GetPicture Method/viewarticle/57162/
        Items Method/viewarticle/58343/
        LastError Method/viewarticle/58255/
        NameByFileName Method/viewarticle/58260/
        NameByIndex Method/viewarticle/58262/
        NamesList Method/viewarticle/58266/
        Remove Method/viewarticle/57141/
       Regions Object Properties/viewarticle/58340/
    [Expand]Tested Applications/viewarticle/59779/
    [Expand]Unit Testing/viewarticle/59780/
    [Expand]User Forms/viewarticle/59781/
    [Expand]Web Services/viewarticle/59782/
   [Expand]Project Objects/viewarticle/59768/
   [Expand]Test Log Objects/viewarticle/59769/
   [Expand]COM Automation Objects/viewarticle/59770/
  [Expand]TestComplete Events/viewarticle/56945/
  [Expand]Language Reference/viewarticle/57879/
  [Expand]User Form Components/viewarticle/56689/
 [Expand]Other Tools That Help You Test Better/viewarticle/63442/
 [Expand]TestComplete 10 Licensing Guide/viewarticle/63451/
Updated: 4/23/2014 Applies To: TestComplete 10 Rating: No votes Click to rate: PoorNot badAverageGoodExcellent
Programming Reference Select language for code samples Select language for code samples

FindRegion Method


The Regions.FindRegion method searches pixel-by-pixel for one image, specified by the PictureToSearchFor parameter, within another, represented by the PictureToSearchIn parameter, and returns the rectangular area that corresponds to the found image. If either bitmap is not found, FindRegion generates an error string, which you can retrieve from the LastError property of the Regions object (and post to the test log).

This method uses the TestComplete’s image comparison engine. To learn more about it, read the How Image Comparison Works topic.



PictureToSearchFor [in] Required Variant
PictureToSearchIn [in] Required Variant
Left [in] Optional Integer Default value: 0
Top [in] Optional Integer Default value: 0
Transparent [in] Optional Boolean Default value: False
Mouse [in] Optional Boolean Default value: False
PixelTolerance [in] Optional Integer Default value: 0
Result A Rect object  

Applies To

The method is applied to the following object:


The method has the following parameters:


Specifies the sought-for image. PictureToSearchFor can be one of the following values:

  • The name of the image in the Regions collection of the Stores project item (if the image is added to this collection).
  • A Picture object.
  • A window or onscreen object.
  • Fully-qualified path to the image file. The following file types are supported:
    • BMP
    • JPEG
    • PNG
    • TIFF
    • GIF
    • ICO


Specifies the image, within which TestComplete searches for another image. To set the parameter, you can use the same values, which you used to specify the PictureToSearchFor parameter: the image’s name in the Regions collection, the Picture or window object, or the fully-qualified file name.


The horizontal coordinate of the PictureToSearchIn image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the PictureToSearchFor picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the left side of the given image.


The vertical coordinate of the PictureToSearchIn image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the PictureToSearchFor picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the top side of the given image.


False by default. If it is True, then the top left pixel of PictureToSearchFor will be treated as the “transparent” (background) color in PictureToSearchIn, which is meaningless for comparison. For instance, if that pixel is gray, then any gray pixel in PictureToSearchFor will match any color pixel in PictureToSearchIn.


The Mouse parameter specifies whether the mouse pointer image is included into the image where the method operates. By default, the Mouse parameter is False. If it is True and the PictureToSearchIn parameter specifies an object (for example, a window or onscreen object) with the mouse pointer over it, then the mouse pointer is included in this image. The FindRegion method will only return True if the other image includes the mouse pointer in the same position.


Lets you ignore slight differences between the bitmaps during the search. If the number of different pixels is less than or equal to PixelTolerance, then TestComplete considers the images to be identical. 0 is the default value; it means that no differences between the bitmaps except for those set by the Transparent parameter are ignored.

Note: Using the PixelTolerance parameter with non-zero values may slow down the search process.

Result Value

If the search is successful, FindRegion returns the Rect object whose properties are set to the values fitting the sought-for image found within the PictureToSearchIn image. This is the first image found, searching left-right and top-down. If the search fails, FindRegion returns an empty value (Nothing in VBScript, null in JScript, C++Script and C#Script and nil in DelphiScript).


If the method fails to locate an image, while the sought-for image is part of another image, see the Why Image Comparison Fails and Factors Affecting Image Comparison help topics to determine the cause of the failure.

The Regions.FindRegion method is similar to the Regions.Find method. The only difference between them is the order of the PictureToSearchIn and PictureToSearchFor parameters.


The following code searches for an image within another image that is stored in the Regions collection.

Show Example

See also
About Regions Editor | About Region Checkpoints | How Image Comparison Works | Compare Method | Find Method | Find Method | Picture Object

© 2014 SmartBear Software. All rights reserved.
Email Send feedback on this document