The Image Update panel helps you manage, modify, and work with previously existing images. It also assists in capturing new images, creating collections, and replacing previously existing images.
See the Image Diagnostics section on The Image Viewer page for information about image search settings and selecting diagnostic searches.
The Image Update panel lets you work with image diagnostics and fix image searches when an image is not found during a script run. Depending on the selected settings, this panel also appears when multiple instances of an image are found that were not anticipated by the script.
You can enable the Image Update panel functionality on the main menu by adjusting the options shown in the Run > Image Update menu.
When Image/Text is not found:
- Throw Exception (Update Off): The Image Update panel is not used, and so will not display when an image is not found.
- Show Panel (Manual Update): This option opens the Image Update panel when an OCR or text search fails during runtime so that you can interactively work with settings to find an appropriate match. This option lets you use the Image Update panel interactively, which gives the most complete control over text matches. This method is best for attended test runs.
- Auto Update: This setting engages the Image Update panel internally by trying additional search parameters to create a match and continue the script without user interaction.
The Auto Update option is a good choice for unattended script runs. Frequently, it can find a match and continues the script run when otherwise the search would throw an exception and fail. However, if your parameters are too broad, you could end up matching the wrong image, with unintended results.
When you use the Auto Update option, changes made during the script run are applied in memory only. You must apply updates to the image from the Results panel to retain changes.
Because of the behaviors listed above that are caused by using the Auto Update option, it is good to track how often your scripts are engaging this option. To see how often this is happening, do the following:
- Click the script in question in the Results pane in the Suite window. This action displays a Results pane that shows records of the tests you have run in the current suite.
- Click a row in the top of the Results pane.
- Review the results in the bottom of the Results pane, looking for the AutoUpdate string in the text and message columns. By searching for these AutoUpdate string occurrences, you can see how many times auto update has been engaged and how long it took to resolve each case. For example, in the following screenshot, the AutoUpdate are highlighted:
When multiple occurrences are found:
- Use First Location: Uses the first instance of the image found by Eggplant Functional.
- Show Panel: Displays the Update Image panel so that you can work with the images manually.
- Log Warning: Logs a warning in the script results. This does not affect the result of your script but will be recorded in the script results.
- Throw Exception: Throws an exception, which will cause the running script to fail. This will be recorded in the script results.
- Validate ImageFound(): Sets the ValidateImageFound global property to On. This means that when an imageFound() function returns false, Auto Update is triggered. This does not happen if Auto Update is already turned on.
- Validate Successful Image Searches: Whether or not to validate every image search, successful or not.
Using the Image Update Panel
The Image Update panel comprises three tabs, described in more detail below: The Start tab, the Diagnostics tab, and the Properties tab. Each tab allows you to make adjustments that make your Eggplant Functional scripts more successful.
All of the tabs in the Image Update panel include the Manual Update drop-down menu. The Manual Update drop-down menu includes the selections for the Image Update options explained in Enabling the Image Update Panel. As you make changes to the Image Update options, you must click Try Again to continue the script with the new preference.
The Start tab in the Image Update panel
The Image Update panel opens with the Start tab displayed. The Suggested Remedies section of the panel offers options to fix or replace the image that can't be found based on the following diagnostic searches performed by Eggplant Functional:
Standard Search: Searches for the image again using the original specifications. A result for this search means that the image has appeared since the first failure to find the image. Most likely this result means that the timing of the script at the step needs to be adjusted to allow more time for the image to appear.
Dynamic Tolerance: Searches for the image while increasing the RGB color tolerance value up by a particular increment (default = 5) until a match is found. A result for this diagnostic means that the RGB values of the image have shifted.
Alternate Types: Searches for the image while using the different SearchType filters, which are Smoothed for Text, Adaptive to Image,Pulsing to Element, and Smooth and Pulsing. If the image is text-based, a result indicating Smoothed for Text suggests that the system under test (SUT) is using anti-aliasing in its text. A result for Pulsing to Element or Smooth and Pulsing suggests that the background portion of the image either has a pulsing effect or perhaps another effect such as a variable gradient. For more on these search types, see Search Type.
Scaling Search: Searches for the image at a different scale than the original image.
Discrepancy Search: Performs the search while allowing a certain percentage or number of the pixels in the image to differ. The percentage of pixels (with a percent sign) or number of pixels (with no percent sign) by which the image and a match in the Viewer window can differ.Note: Discrepancy can be slow to use and can result in false positive matches. Preferable approaches include setting the Search Type to Smooth in the Image Update panel, cropping the image using the Image Editor, or creating an Image Collection that includes several acceptable versions of a basic image. You can also capture a new image if the current image can only be found using a discrepancy search.
OCR Search: Scans the original captured image for text, and then conducts a search for that text. For example, if the original image is of a button that says Search on it, this search will use OCR to look for the word Search on the screen.
Prior Location: References the results for the current script in which the current line of code was successfully run. Highlights the location on the screen where the image was found in that successful run of this test. The results that this search uses can be specified manually using the Mark As Prior Run button in the results portion of the suite for any script.Note: This search is not used when the Image Update panel is set using the Run > Image Update > Auto Update option.
Original Location: References the coordinate pair of the location at which the image was first captured.
- Crop Edges: Searches by progressively cropping in on the image, looking for smaller and smaller images. As long as the inside of the image does not match anything else on the screen, the edges are not important.
Selecting a Suggested Remedy shows a highlight rectangle on the SUT screen in the color for that diagnostic. The Remedy drop-down list changes depending on the option you choose. Available remedies are:
- Apply Fix: This option performs the selected fix to the current image.
- Replace Image: This option automatically recaptures the image without changing any of its properties. The search is then run again.
- Add Representation: This option adds a new representation of the image to the current suite. The new representation is added to the same collection as the original image, and Eggplant Functional suggests a name for the image in the New Representation field.
- Capture to Helper: This option captures a new version of the desired image and saves it in a helper suite. If you select this option, a drop-down menu appears, listing available suites to which the image can be captured
Select a Remedy action from the drop-down list, then click Do This. For the options listed above, Eggplant Functional will fix the image and try the search again.
Enter a name in the New Representation field. If you choose to add a new representation of this image to a collection, the name in this field is used. If you alter the naming convention used in this field, it will remember the convention for further image updates.
The Diagnostics tab lists the results of diagnostic searches so that you can see what settings can be adjusted or what search types can be used in order to find the image on the screen. The options listed correlate to the options in the Start tab, described above.
To use the Fix, Recapture, or Add Rep (which stands for Add Representation) buttons, select an appropriate diagnostic search that returned positive results. For instance, in the example below, the Original Location can be used to Fix the image:
The Diagnostics tab, with Scaling Search selected
In the following example, selecting Original Location enables the Recapture and Add Rep options:
The Diagnostics tab in the Image Update panel
Recapture will capture the image again using the location where the selected search type is finding the image. Add Rep will add a representation of the image to an image collection, or create a collection if one does not already exist.
The Properties tab, visible in the Image Update panel
The Properties tab gives you the ability to manually adjust different image settings without permanently altering the state of the captured image in your suite. You can change the Search Type, Tolerance, Discrepancy, Scale, and Rotate values in this panel, then press Enter to conduct a search of the current active connection to see what settings work best. The original settings will show to the right in red. To fix the image permanently, click Save Changes. To revert to the original settings, click Revert Changes.
Working with Images in the Viewer Window
The Viewer window during an Image Update panel Diagnostic Search
When an image is not found, or multiple instances of an image are found, the Image Update panel appears and conducts a variety of diagnostic searches. The results are highlighted in the remote screen window. Boxes of corresponding colors are shown in every location on the screen of the SUT where an image is found with one of the diagnostic searches.
Hovering over one of these colored squares turns the square white.
A Highlighted image match in the Viewer window
If clicked, the capture area snaps to that box, and you can use that selection to add a representation for an image collection, or fix the current image that you are working with in the Image Update panel.
A selected image match in the Viewer window
Clicking the arrow to the right of the capture area in this instance brings up the following drop-down menu:
The capture area drop-down menu in the Viewer window
Options are to:
- Add Representation and Try Again: Captures an image using the selected image-capture bounds and adds it to the current collection or creates a collection using the current image and the newly captured image. Then, it tries the search again with the new/updated image collection.
- Add Representation: Captures an image using the selected image-capture bounds and adds it to the current collection or creates a collection using the current image and the newly captured image.
- Recapture and Try Again: Captures an image using the selected image-capture bounds and replaces the current image with this new image. Then, it tries the search again with the newly captured image.
- Recapture: Captures an image using the selected image-capture bounds and replaces the current image with this new image.
- Capture Image: Captures an image using the selected image-capture bounds and brings up an image capture panel so you can name the image and adjust any other settings as desired before saving.
- Show Update Image Panel: This brings up the Update Image panel if it is not currently displayed.
- Hide Highlight Rectangles: This hides the highlighted rectangles displayed after a search.