Using the ScreenPart Function Handler

Setting the searchRectangle global property or image search property in the Eggplant Functional test automation tool based on the dimensions of the screen of your system under test (SUT) can improve the performance and accuracy of optical character recognition (OCR), validating that UI or text elements appear in the desired portion of the SUT screen, or increasing the execution speed of repetitive image or OCR searches for elements that consistently appear in the same area of the screen.

Defining the SearchRectangle

Below is an example of a reusable custom function handler that you can use to set the searchRectangle to a portion of the full screen. This code leverages a number of helpful SenseTalk concepts, including the times mathematical operator and property lists.

Example:

function ScreenPart Portion
  // Set up an easy-to-maintain property list that stores the necessary multipliers for the specified screen portion parameter value
  set screenPortions to {
    TopHalf: ((0,0),(1,.5)),
    BottomHalf: ((0,.5),(1,1)),
    LeftHalf: ((0,0),(.5,1)),
    RightHalf: ((.5,0),(1,1)),
    HorizontalMiddle: ((0,.25),(1,.75)),
    VerticalMiddle:((.25,0),(.75,1)),
    TopLeftQuadrant:((0,0),(.5,.5)),
    TopRightQuadrant:((.5,0),(1,.5)),
    BottomLeftQuadrant:((0,.5),(.5,1)),
    BottomRightQuadrant:((.5,.5),(1,1)),
    Center:((.25,.25),(.75,.75)),
  }
  set multiplier to screenPortions.(Portion) // Retrieves the value for the key in the property list. The name of the key is passed as a parameter into the function.
  // Error handling is needed in the event that an unrecognized parameter is passed to the function
  if multiplier is empty then
    throw "Parameter error", Portion && "is not a recognized screen portion."
  end if
  return (the remoteScreenSize,the remotescreenSize) * multiplier
End ScreenPart

The screenPart() function returns a set of two coordinate pairs, representing a valid rectangle, which can then be used by the searchRectangle global property or image search property to set the desired search area on the screen.

Example:

Set the searchRectangle to ScreenPart("LeftHalf") // Passes the parameter value "LeftHalf" into the ScreenPart() function
// All of the following image and OCR searches will honor the new searchRectangle
Click text:"State"
TypeText "Michigan"
Click text:"Zip Code"
TypeText "49418"
Click text:"Street Address"
TypeText "123 Main St."
Click "Submit"
Set the searchRectangle to empty // Returns the search area to the full screen

Example:

Click (image:"WelcomeMessage",searchRectangle:ScreenPart("TopHalf"),waitFor:10)

Calling ScreenPart () from Helper Scripts

More commonly, the screenPart() function is declared within a separate script than the calling script, which requires different syntax to call the function.

Example:

Click (image:"WelcomeMessage",searchRectangle:Rectangle.ScreenPart("BottomHalf")) // Uses dot (.) syntax to call the ScreenPart function, which is declared within a script named Rectangle

Example:

set the searchrectangle to Rectangle's screenPart ("BottomRightQuadrant") // Uses apostrophe-s ('s) syntax to call the ScreenPart function, which is declared within a script named Rectangle