Image File and Suite Information
The functions in this section return various properties associated with image files and Eggplant Functional suites.
ImageInfo Function
Behavior: Returns an image property list for a single image, or a list of image property lists for multiple image references. Depending on the data that is available, the list can contain the following properties:
- CaptureDate: The date of the image capture, including time, in the format (yyyy-mm-dd hh:mm:ss +0000); the final four digits represent the GMT offset.
- CaptureHost: The name of the SUT on which the image was captured.
- CaptureLocation: Coordinates that indicate the position of the top-left corner of the image when it was captured in the Viewer window.
- CaptureScreenSize: The dimensions of the SUT screen on which the image was captured, given in pixels as (
width,height). - Description: The image description in the Suite Editor Info panel.
- HotSpot: The coordinates of the image's hot spot, given as (x, y).
- ImageLocation: The on-screen coordinates of the hot spot of the image. See the ImageLocation() function.
- ImageName: The name of the image file.
- ImagePath: The full pathname of the image file.
- ImageRectangle: The rectangle coordinates of the image found using the ImageRectangle() function.
- ImageSize: The image’s size in pixels, given as (
width,height). - ImageTolerance: The tolerance setting used when capturing the image on the SUT.
- Pulsing: Whether the image was captured with the pulsing setting (true/false).
- Scale: The scale used to capture the image.
- SearchType: The Search Type selected when saving the image.
Parameters: One or more Image References. Returns: An image property list, or list of image property lists. For example:
((CaptureDate:"2016-10-19 15:20:52 -0600", CaptureHost:"Windows", CaptureLocation:(527,707), CaptureScreenSize:(1024,768), Description:"", HotSpot:(11,19), ImageLocation:"", ImageName:"Value", ImagePath:"C:/Users/Carrie/Documents/Demo.suite/Images/ValueField.png", ImageRectangle:"", ImageSize:(23,39), Pulsing:"False", Scale:"1", SearchType:"Tolerant"))
Example:
put ImageInfo("BrowserIcon") into ListVariable //Stores the return of the imageInfo function in a variable.
Example:
put the number of items of imageInfo("CheckBox") into NumberinReturn //Stores the number of items in the return of ImageInfo.
if NumberinReturn is greater than 1 then log "There are" && NumberinReturn && "images in the collection." //Checks whether the number of items in the return is greater than 1, which means the image is actually an image collection.
Example:
copy file imageInfo("CompanyLogo")'s imagePath to folder "C:\Users\Carrie\Desktop\ResultsFolder" //Copies an image from inside the current suite to a new location on the eggPlant machine.
Example:
put the suiteinfo's imagesfolder into myimagefolder //Stores the path to the image folder in the current suite.
put the files of myimagefolder as a list into myimages //Stores the names of all files in the image folder (including imageinfo files) as a list.
repeat with each item of myimages by reference //Iterates on the list by reference instead of in memory.
if it contains "imageinfo" then delete it //Deletes the file name from the list if it's an imageinfo file.
end repeat
repeat with each item of myimages //Iterates on the remaining list of file names after the imageinfo file names have been removed.
put imageinfo(it)'s CaptureDate into mycapturedate //Stores the CaptureDate property value in a variable.
If mycapturedate is not empty and mycapturedate is earlier than 1 year ago then //Determines whether the CaptureDate occurred more than a year ago from today.
do merge of <<Logwarning "Image [[it]] was captured over a year ago.">>//Uses the merge function to construct a string and log a message.
end if
end repeat
ImageHotSpot Function
Behavior: Returns the coordinates (x,y) of the image’s hot spot, relative to the top-left corner of the image.
If you need to work with the hot spot location of a found image on the SUT, use the ImageLocation() function.
Parameters: A single image, excluding Image Collections.
Returns: Coordinates. For example:(-65,90)
Example:
set PointAdjustment to ImageHotSpot("Logo") - imageSize("Logo")//Finds the difference between the lower right corner of the image and the hot spot of the image.
Example:
log imagehotspot("CompanyLogo")
ImageSize Function
Behavior: This function returns the size in pixels—given as (width, height)—of the given image. If the image is not found, an exception is raised.
Parameters: A single image, excluding Image Collections.
Returns: Size in pixels (width, height). For example: (48,19)
Example:
put ImageSize("image") into ImageSizeVariable //Stores the return of the imageSize function in a variable.
Example:
If the ImageSize of "ConfirmationNumberField" is not(30,40) then Log "The image has changed size since original capture." //Checks whether the image size is as expected.
Example:
params CollectionName //Parameterizes the script to receive the name of an image collection.
put item 1 of ImageInfo(CollectionName) into myImage //Stores the first item of the return of ImageInfo, which is the ImageInfo for a single image in a collection.
put the folder of myImage's ImagePath into CollectionFolder //Uses the folder function to find the folder path of the image, based on the file path of the image. This is the folder path of the image collection.
put the files of CollectionFolder into ImagesList //Stores the names of the files in the image collection.
repeat with each Image of ImagesList //Iterates on each file name, including imageinfo files.
if myFile contains ".png" then //Checks whether the file name belongs to an image file.
put CollectionName & slash & myFile into ImageRelativePath //Constructs a path relative to the suite using the image file name.
put ImageRelativePath's ImageSize into ImageSize //Stores the return of the imageSize function in a variable.
insert item 1 of ImageSize times item 2 of ImageSize after ListofAreas //Creates a list of the areas of each image in the collection.
end if
end repeat
Log "The median area of the images in the collection "&CollectionName&" is "& the median of ListOfAreas&"." //Calculates the median area of the images in the collection using the median function and logs a message about it .
ImageColorAtLocation Function
Behavior: Returns the color value, displayed in the format specified by the colorFormat global property, of a single pixel in the given image. The coordinates of the pixel are relative to the top-left corner of the image.
If you need to determine the color of a pixel on the SUT, use the ColoratLocation() function.
Parameters: One image name and one coordinate location.
Returns: A color value. For example: (255,255,255). For more information, see Color Values in SenseTalk.
Example:
set the colorFormat to "HSB" //Sets colors to display according to hue, saturation, and brightness values from 0 to 1
put ImageColorAtLocation("myIcon",[23,1]) //Returns the color at location [23,1] of the given image. i.e. HSB, 0.592, 0.977, 0.682
Example:
function FindChartreusePercentage myImage //Declares a function named FindChartreusePercentage with parameter value myImage.
if "Chartreuse" is not among the keys of the NamedColors then set the NamedColors.Chartreuse to color(127,255,0) //Adds chartreuses to the global property list of named colors, if it is not already a named color.
put the width of imageSize(myImage) into XDirection //Stores the x coordinate of the imageSize in a variable.
put the height of imageSize(myImage) into YDirection
set TotalPixels to XDirection x YDirection //Calculates the total number of pixels in the image.
set ColorPixels to 0 //Resets the tally of chartreuse-colored pixels to zero.
repeat YDirection times //Iterates down the height of the image.
put the repeatIndex - 1 into YCoord //Tracks the Y coordinate of the current pixel.
repeat XDirection times //Iterates across the width of the image.
put the repeatIndex - 1 into XCoord //Tracks the X coordinate of the current pixel.
put imagecoloratlocation(myImage, (XCoord,YCoord)) into ReturnedColor //Stores the RGB value of the current pixel.
if ReturnedColor is color("Chartreuse") then add 1 to ColorPixels //If the pixel is chartreuse, tallies the pixel.
end repeat
end repeat
return round((ColorPixels/TotalPixels) * 100, 1) //Returns the percentage of chartreuse pixels, rounded to the first decimal place.
end function
OpenSuites Function
Behavior: Returns a list of all of the suites that are available to the current script. The list includes the script’s own suite, suites opened by the OpenSuite (deprecated) command, and the EggplantCommon suite.
Parameters: None Returns: A list of all of the suites that are available to the current script. For example:
(C:/Users/Carrie/Documents/eggPlantSuites/Demo.suite,C:/Program Files (x86)/eggPlant/Eggplant.app/Resources/EggplantCommon.suite)
Example:
put OpenSuites() into SuitesInUse
ResourcePath Function
Behavior: If no parameter value is provided, returns the full path of the suite resource folder of the calling suite. If a parameter value is provided, returns the full path of the suite resource folder with the parameter value appended to the end.
Parameters: None, or the name of a suite resource.
Returns: The path of the calling suite's resources folder, or the path of the calling suite's resources folder, with the parameter value appended. For example:
No parameter value:
C:/Users/Carrie/Documents/eggPlantSuites/Demo.suite/Resources
Resource name parameter value:
C:/Users/Carrie/Documents/eggPlantSuites/Demo.suite/Resources/testlist.txt
Because this function always returns the full path of the calling suite, it is not useful for referencing the file paths of suite resources stored inside other suites, such as helper suites.
Example:
log ResourcePath() //Logs the suite resource folder path for the calling suite
Example:
set ProtectedApps to file ResourcePath("ProtectedApps.txt") //Stores the content of the resource file "ProtectedApps.txt" in a variable called ProtectedApps
Example:
repeat with each line of file ResourcePath("TestData.csv") //Iterates based on each line in the file named "TestData.csv" located in the calling suite's resources folder
CalculatorTest the first item of it, the second item of it //Passes the first and second items of the list that is on the current line of the file as parameters into script CalculatorTest
end repeat
Example:
BeginTestCase "ResultsLoaded" //Creates a custom test case called "ResultsLoaded"
WaitFor 20, "Results"
EndTestCase "ResultsLoaded"
set myResult to the result //Stores the result property list from test case "ResultsLoaded" in a variable called myResult
put myResult.testcase & comma & myResult.duration & comma & myResult.starttime &CRLF after file ResourcePath ("myTimings.csv") //Appends the concatenated string to the end of the calling suite's resource file myTimings.csv
Example:
set UserFilesList to the files of the resourcePath //Stores a list of all the files objects in the resources of the calling suite. This is distinct from simply storing a list of all the file names or paths
repeat with each userSet of UserFilesList //Iterates for each file called userSet in UserFilesList
RunWithNewResults "LoginTest", userSet //Calls a script named "LoginEst" and passes the current file object to the script
end repeat
SuiteInfo Function
Behavior: Returns the following information about a suite:
- Name: The name of the suite.
- Path: The full path of the suite.
- ScriptsFolder: The path of the Scripts folder.
- ImagesFolder: The path of the Images folder.
- ResultsFolder: The path of the Results folder.
- Version: The Eggplant Functional version number of the suite (usually the version of Eggplant Functional that created the suite).
- Description: The description of the suite as entered on the Settings tab of the suite.
If you call SuiteInfo from a script within a suite that has a helper suite, Eggplant Functional returns the paths of both the main or calling suite and the helper suite. If you call SuiteInfo from a script within the helper suite, Eggplant Functional returns the path of the main or calling suite only. It does not return the helper suite path.
Parameters: None, the full path of a suite, or the name of a suite located in the default suite directory.
Returns: A property list of the suite info. For example:
(description:"", helperSuites:((filePath:"C:/Users/Carrie/Documents/eggPlantSuites/NopCommerce.suite")), imagesFolder:"C:/Users/Carrie/Documents/eggPlantSuites/DemoSuite.suite/Images", name:"DemoSuite.suite", path:"C:/Users/Carrie/Documents/eggPlantSuites/DemoSuite.suite", resultsFolder:"C:/Users/Carrie/Documents/eggPlantSuites/DemoSuite.suite/Results", scriptsFolder:"C:/Users/Carrie/Documents/eggPlantSuites/DemoSuite.suite/Scripts", version:"1608291744")
Example:
set mySuiteInfo to SuiteInfo() //Stores the SuiteInfo() for the calling suite in a variable called mySuiteInfo
Example:
log SuiteInfo("C:\Users\Pamela\mySuite") //Logs the SuiteInfo for the suite at the specified path
Example:
CaptureScreen {name:SuiteInfo().ImagesFolder&slash&"CurrentLogo",rectangle:["WelcomeImage","Border"]} //Captures a screenshot named "CurrentLogo" and saves it into the calling suite's images folder so it can be easily used in later image searches
Example:
set ScriptFileList to the files of SuiteInfo().ScriptsFolder //Stores a list of all files objects in the ScriptsFolder into a variable called ScriptFileList
Example:
set the InitialSuites to the folder of SuiteInfo().Path&"windows.suite" //Sets the InitialSuites to a particular suite, based on the folder path the calling suite currently is located in. This is useful when the location of the suite on the eggPlant controller is inconsistent but the relative path between suites is the same
Example:
Code that uses the WaitForAll command to perform an image search for all images inside a folder:
on FindAllInFolder folderToSearch, waitTime //Creates a custom command named FindAllInFolder that takes two parameters, folderToSearch and waitTime
put SuiteInfo().imagesFolder&"/"&folderToSearch&"/" into imgFolder //Stores the folder path for the image folder of interest in a variable
put each item of files(imgfolder) where each does not end with "info" into imgsToFind //Creates a list for all of the image files in the folder and store it in a variable
put folderToSearch & each item of imgsToFind into imgsToFind //Combines the list of file names with the folder name to create a new list
WaitForAll waitTime, imgsToFind //Uses the WaitForAll command to validate that all images in the folder are present on the SUT
end FindAllInFolder