HTMLImageFunctions

Last Updated:

Actions for working with HTMLImage objects


[How To Read This Reference]
Click
WR
Deprecated For:ClickArea
ClickArea
RJ
Attempts to perform a Click on a mapped region of an Image (on a webpage).
CompareStoredData
WR
Deprecated For:GenericObjectFunctions.CompareStoredData
CompareStoredProperties
WR
Deprecated For:GenericObjectFunctions.CompareStoredProperties
SaveHTMLImage
RC RJ
Attempts to Save an HTMLImage on a webpage.
VerifyHTMLImage
RC RJ
Attempts to verify an HTMLImage on a webpage to a benchmark file.

HTMLImageFunctions::Click (deprecated for: ClickArea)
WR

Command deprecated in favor of ClickArea.

Attempts to perform a standard Click on an HTMLImage on a webpage. This functionality is already provided by GenericObject CLICK.

We can optionally click on a particular area of a client-side or server-side image rather than a generic click (Coords=1,1). This part of the functionality should be implemented in ClickArea instead.

The image area lookup is done with the component name AND an additional app map reference provided in Field #5.

Typical Data Table records:

(1) t BrowserWin AnImage Click
(2) t BrowserWin AnImage Click AMappedRegion

#1 above should merely click in the top-left corner of the image.

#2 above will contain a AnImage entry in the MainWindow section with normal recognition information for it. AnImage will also have it's own section in the Application Map in which there will be entries defining specific indexed or named regions for the image.

Examples:

                [BrowserWin]
                BrowserWin=WindowTag=WEBBrowser
                AnImage=Type=HTMLFrame;HTMLID=top;Type=HTMLImage;Index=1
                ...
                [AnImage]
                AMappdedRegion=Coords=10,10
                ANamedRegion=AreaName=TechSupport
                AnIndexedRegion=AreaIndex=2
                AnotherRegion=AreaID=Contact


Fields: [ ]=Optional with Default Value
  1. [ AppMapSubkey = ]
    Name of the AppMap subkey to lookup and use for the click.

    (OPTIONAL) Name of the AppMap subkey to lookup and use for the click. The AppMap can contain the item in any of the following formats:

                    [AnImage]
                AMappdedRegion=Coords=10,10
                ANamedRegion=AreaName=TechSupport
                AnIndexedRegion=AreaIndex=2
                AnotherRegion=AreaID=Contact

    Any valid content used with the HTMLImage Click command can be part of this AppMap entry.

    Both Fields #3 and #5 are used to locate the item in the App Map. This routine does not specify an App Map so only the current Map is used and it is expected to be valid.



Examples:
  • T, WebBrowser, SiteMapImage, CLICK, Center
    A single-click is performed on the SiteMapImage based on the reference Center in the Application Map

    Field 5 : TQ String. A reference identified in the Application Map identifying where to click.

                    [AnImage]
                Center=Coords=10,10
                ANamedRegion=AreaName=TechSupport
                AnIndexedRegion=AreaIndex=2
                AnotherRegion=AreaID=Contact


[How To Read This Reference]

HTMLImageFunctions::ClickArea
RJ

Attempts to perform a Click on a mapped region of an Image (on a webpage).

RobotJ: The initial implementation actually does this in reverse. It expects that the specified object resolves to the HTML.AREA object defined in the HTML.MAP instead of simply specifying the Image and then an area. The RobotJ implementation then attempts to locate the Doc and Image that use the defined area and click on it.
No Field #5 parameter is used or needed in this implementation.

Future implementations should also\instead support the HTML.IMAGE object as the target and the area to click as a Field #5 parameter. The parameter would optionally define an App Map reference or could be used as a literal value. App Map references might appear as below: 

                Examples:

                [BrowserWin]
                AnImage=Type=HTMLFrame;HTMLID=top;Type=HTMLImage;Index=1
                ...                 
                [AnImage]
                ANamedRegion=AreaName=TechSupport
                AnIndexedRegion=AreaIndex=2
                AnotherRegion=AreaID=Contact


Fields: [ ]=Optional with Default Value
  1. [ AppMapSubkey = ]
    (FUTURE) Name of the AppMap subkey to lookup and use for the image area click.

    (FUTURE) Not used by RobotJ at this time.

    The AppMap could contain the item in any of the following formats: 

                    [AnImage]
                AMappdedRegion=Coords=10,10
                ANamedRegion=AreaName=TechSupport
                AnIndexedRegion=AreaIndex=2
                AnotherRegion=AreaID=Contact

    Both Fields #3 and #5 would be used to locate the item in the App Map. This routine does not specify an App Map so only the current Map would be used and it is expected to be valid.



Examples:
  • T, WebBrowser, ADefinedArea, ClickArea
    A single-click is performed on the the first Image using the defined HTML.AREA.


[How To Read This Reference]

HTMLImageFunctions::CompareStoredData (deprecated for: GenericObjectFunctions.CompareStoredData)
WR

Performs a HTMLImageVP CompareData on an HTMLImage object.

Performs a HTMLImageVP CompareData on an HTMLImage object.

THE BENCHMARK VP MUST ALREADY EXIST AND BE AN ASSET OF THE CURRENTLY RUNNING SCRIPT.

Modified VP parameter information can be added to the standard VP=VPName by including the VPName reference in the application map in a section defined for the HTMLImage. If this is done, the value retrieved from the application map will be appended to VP=VPName. The required semicolon for this append will be provided by this routine.

Example 1: Perform a standard HTMLImage CompareData. To perform a basic CompareData the name "StoredVP" will not exist in the app map:

The Step File call:

BrowserWindow AnHTMLImage CompareStoredData StoredVP

This will produce a CompareData VP with "VP=StoredVP;Wait=2,10".

The StoredVP baseline MUST already exist as an asset of the currently running script.

Example 2: Perform a HTMLImage CompareData providing addition parameter information (such as ExpectedResult=FAIL). To do this the HTMLImage object must have its own section in the app map and an item with the same name as the StoredVP. The value of that item will be appended to the standard VP argument with a semicolon.

Part of App Map:

                [BrowserWindow]
                BrowserWindow=WindowTag=WEBBrowser
                AnHTMLImage=<snipped for brevity>;\;Type=HTMLImage;Index=1
                ...
                [AnHTMLImage]
                StoredVP=ExpectedResult=FAIL;Wait=3,30

The Step File call:

BrowserWindow AnHTMLImage CompareStoredData StoredVP

This will produce a CompareData VP with all the parameters appended like this: "VP=StoredVP;ExpectedResult=FAIL;Wait=3,30". NOTE:When stored parameters are found in the app map then the default Wait= parameter used in the standard compare is no longer provided. If you still need a Wait= parameter, then it must be included in the stored parameters.

The StoredVP baseline MUST already exist as an asset of the currently running script.



Fields: [ ]=Optional with Default Value
  1. VPAsset
    Name of the pre-existing VP asset stored in the currently running script.

    Name of the pre-existing VP asset stored in the currently running script. If the name also exists in the app map under the component then the additional stored parameters are appended to the VP call.

Examples:
  • T, WebBrowser, SiteMapImage, COMPARESTOREDDATA, "AStoredVP"
    This action compares stored data on the SiteMapImage object against "AStoredVP".

    Field 5 : TQ String. The name of a stored CompareData VP which must exist as an asset of the currently running script. You can also specify additional VP parameters by including a reference in the application map.

    [URLLink]

    AStoredVP=ExpectedResult=FAIL;Wait=3,30



[How To Read This Reference]

HTMLImageFunctions::CompareStoredProperties (deprecated for: GenericObjectFunctions.CompareStoredProperties)
WR

Performs a HTMLImageVP CompareProperties on an HTMLImage object.

Performs a HTMLImageVP CompareProperties on an HTMLImage object.

THE BENCHMARK VP MUST ALREADY EXIST AND BE AN ASSET OF THE CURRENTLY RUNNING SCRIPT.

Modified VP parameter information can be added to the standard VP=VPName by including the VPName reference in the application map in a section defined for the HTMLImage. If this is done, the value retrieved from the application map will be appended to VP=VPName. The required semicolon for this append will be provided by this routine.

Example 1: Perform a standard HTMLImage CompareProperties. To perform a basic CompareProperties the name "StoredVP" will not exist in the app map:

The Step File call:

BrowserWindow AnHTMLImage CompareStoredProperties StoredVP

This will produce a CompareProperties VP with "VP=StoredVP;Wait=2,10".

The StoredVP baseline MUST already exist as an asset of the currently running script.

Example 2: Perform a HTMLImage CompareProperties providing addition parameter information (such as ExpectedResult=FAIL). To do this the HTMLImage object must have its own section in the app map and an item with the same name as the StoredVP. The value of that item will be appended to the standard VP argument with a semicolon.

Part of App Map:

 
                [BrowserWindow]
                BrowserWindow=WindowTag=WEBBrowser
                AnHTMLImage=<snipped for brevity>;\;Type=HTMLImage;Index=1
                ...
                [AnHTMLImage]
                StoredVP=ExpectedResult=FAIL;Wait=3,30

The Step File call:

BrowserWindow AnHTMLImage CompareStoredProperties StoredVP

This will produce a CompareProperties VP with all the parameters appended like this: "VP=StoredVP;ExpectedResult=FAIL;Wait=3,30". NOTE:When stored parameters are found in the app map then the default Wait= parameter used in the standard compare is no longer provided. If you still need a Wait= parameter, then it must be included in the stored parameters.

The StoredVP baseline MUST already exist as an asset of the currently running script.



Fields: [ ]=Optional with Default Value
  1. VPAsset
    Name of the pre-existing VP asset stored in the currently running script.

    Name of the pre-existing VP asset stored in the currently running script. If the name also exists in the app map under the component then the additional stored parameters are appended to the VP call.

Examples:
  • T, WebBrowser, SiteMapImage, COMPARESTOREDPROPERTIES, "AStoredVP"
    This action performs a CompareProperties on the WebImage object against "AStoredVP".

    Field 5 : TQ String. The name of a stored CompareProperties VP which must exist as an asset of the currently running script. You can also specify additional VP parameters by including a reference in the application map. [SiteImageMap] AStoredVP=ExpectedResult=FAIL;Wait=3,30

[How To Read This Reference]

HTMLImageFunctions::SaveHTMLImage
RC RJ

Attempts to Save an HTMLImage on a webpage.

Attempts to perform a right click - save image/picture as command on the specified image.

You can also optionally specify an x,y offset into the image for the right click to occur.



Fields: [ ]=Optional with Default Value
  1. FileName
    Name of the image file.

    (Required) Name of the file to use for the image save-as command. This can be a full or relative path or a simple filename. A relative path will be stored relative to the Project's root directory. If a simple filename is provided it will be stored in the Project's Datapool\Test directory.



  2. [ Coords = 3,3 ]
    The explicit coordinates ("x,y"), or an App Map reference to pre-defined coordinates.

    We first check to see if the field contains a reference to an App Map item. If that cannot be found, we will assume the field contains explicit coordinates.

    We expect the coordinates in the format "x,y":

                    [MyImage]
                TopRight=50,10
                Center=25,25
                BottomRight=Coords=50,40

    The results from the lookup are appended to the "Coords=" string used by the Click command in Robot (if necessary).

    Both Fields #3(component name) and #6(coords reference name) are used to locate the item in the App Map. This routine does not specify an App Map so only the current Map is used and it is expected to be valid.

    If this parameter is not provided, we will use default coordinates of 3,3 for the right click.



Examples:
  • T, WebBrowser, myImage, SaveHTMLImage, ^filename=myImage.jpg
    Attempts to Save myImage on the webpage.

    Attempts to perform a right click at the default image coordinates, use the 'save as' menuitem on myImage. The image is stored as "myImage.jpg" in the project's Datapool\Test directory.



  • T WebBrowser myImage SaveHTMLImage ^filename=c:\images\myImage.jpg ^xy="25,25"
    Attempts to Save myImage on the webpage.

    Attempts to perform a right click at provided image coordinates, use the 'save as' menuitem on myImage. The image is stored as "myImage.jpg" in the c:\images directory.



  • T WebBrowser myImage SaveHTMLImage ^filename=images\myImage.jpg ^xy="Coords=25,25"
    Attempts to Save myImage on the webpage.

    Attempts to perform a right click at the provided image coordinates, use the 'save as' menuitem on myImage. The image is stored as "myImage.jpg" in the <project>\images directory.



  • T WebBrowser myImage SaveHTMLImage ^filename=images\myImage.jpg ^xy="TopRight"
    Attempts to Save myImage on the webpage.

    Attempts to perform a right click at "TopRight" coordinates defined in the app map, Uses the 'save as' menuitem on the myImage popup menu. The image is stored as "myImage.jpg" in the <project>\images directory.



[How To Read This Reference]

HTMLImageFunctions::VerifyHTMLImage
RC RJ

Attempts to verify an HTMLImage on a webpage to a benchmark file.

Attempts to perform a right click - save image/picture as command on the specified image and then run a binary file compare of the file to a benchmark file.

You can also optionally specify an x,y offset into the image for the right click to occur.

The command may produce a WARNING if a diff tool for which we have no means to verify the results is configured for use. Consequently, if these warnings are expected, the user can use the "TW" test record type to avoid issuing these warnings.



Fields: [ ]=Optional with Default Value
  1. BenchmarkFile
    Name of the Benchmark image file.

    (REQUIRED) Name of the file to use for the image save-as command and the benchmark file. This can also be a full or relative path suitable for FindSQAFile. If no full path or relative path is given then the benchmark file is expected to be found in the project's Datapool\Bench directory.

    The captured image will be stored in the project's Datapool\Test project's Datapool/Test directory. Any comparison difference will be stored in the project's Datapool\Dif directory.



  2. [ Coords = 3,3 ]
    The explicit coordinates ("x,y") or an App Map reference to pre-defined coordinates.

    We first check to see if the field contains a reference to an App Map item. If that cannot be found, we will assume the field contains explicit coordinates.

    We expect the coordinates in the format "x,y":

                    [MyImage]
                TopLeft=10,10
                Center=Coords=25,25

    The results from the lookup are appended to the "Coords=" string used by the Click command in Robot (if necessary).

    Both Fields #3(component name) and #6(coords reference name) are used to locate the item in the App Map. This routine does not specify an App Map so only the current Map is used and it is expected to be valid.

    If this parameter is not provided, we will use default coordinates of 3,3 for the right click.



Examples:
  • T, WebBrowser, myImage, VerifHTMLImage, ^bench=myImage.jpg
    Attempts to verify myImage on the webpage to the benchmark file myImage.jpg.

    Attempts to perform a right click at the default image coordinates, use the 'save as' menuitem on myImage, and then run a binary file compare of the file to a benchmark file myImage.jpg.



  • T, WebBrowser, myImage, VerifHTMLImage, ^bench=myImage.jpg, ^rightclick="Coords=15,15"
    Attempts to verify myImage on the webpage to the benchmark file myImage.jpg.

    Attempts to perform a right click at the provided image coordinates, use the 'save as' menuitem on myImage, then run a binary file compare of the file to a benchmark file myImage.jpg.



  • T, WebBrowser, myImage, VerifHTMLImage, ^bench=myImage.jpg, ^rightclick=TopLeft
    Attempts to verify myImage on the webpage to the benchmark file myImage.jpg.

    Attempts to perform a right click at the image coordinates found in the provided App Map key "TopLeft" under [MyImage]. It will then use the 'save as' menuitem on myImage, then run a binary file compare of the file to a benchmark file myImage.jpg.



[How To Read This Reference]