Creating images

Iris searches for images on the screen. These images are captured by test case authors and developers beforehand. During a test run, core APIs such as exists, wait, and wait_vanish use these images to confirm their on-screen presence, or lack thereof.

There are two main considerations to be taken for these images: image capture and pattern creation.

---

Capturing images

When writing any code in Iris that searches for an image, you will need to capture it using a tool capable of taking screenshots. All supported platforms - Mac, Windows, and Linux - provide native tools for this.

You can also use other programs, such as Sikuli. Each tool has its own benefits, usually around ease-of-use. It can be tricky to capture certain images that require application focus, or appear at sporadic intervals. The end goal is to produce a PNG that is properly cropped to the area you wish to detect, for each platform that your code will run on.

---

Special note for high-resolution displays

If you use a platform that has a high-resolution display - specifically, the Mac Retina screen - you will have to take an extra step after using the screenshot tools. These images are captured at twice the resolution as normal images. For this reason, these images will require a file name indicating this property, which is equal to the name of the image plus a suffix of @2x.png.

For example, if you wish to call an image home_button.png on most platforms, but have a high-resolution image on Mac Retina, it will be named [email protected] just for this platform. It is OK to have a mix of normal and high-resolution images, as long as they are properly named. Iris does the conversion automatically.

Note:
Images captured via Sikuli on the Mac Retina configuration are normal resolution and do not require special naming.

---

Images are named in lower case, and spaces are substituted with underscores. Aside from the character @ in the use case above, no other non-alphanumeric characters are allowed.

When you have created your images, they must be placed in the project, in the correct directories relative to your code. Some use cases will allow one image to work on all platforms and locales, while others will require multiple images for each platform and/or locale.

---

Creating Patterns

Placing the image file

Once you have produced finished screen captures - correctly-named PNGs - place them in the proper location relative to the calling code. Full instructions on how to determine this location are below. A misplaced image will cause a runtime error, and the code will fail.

Within each directory of the project exists a subdirectory named images, and within that, subdirectories named after supported platforms: osx, linux, win, and win7. There is also a directory named common.

Note:
The platform win denotes Windows 10.

For example, you might need to place an image named logo.png, and your code lives in /tests/some_package/window_test.py. By consulting the four use cases below, choose the location(s) for your image file(s).

1. Use case: Image that can be used on all platforms and locales.

Location:

/tests/some_package/images/common/logo.png

2. Use case: Image that is platform-specific, but supports all locales.

Location:

/tests/some_package/images/linux/logo.png
/tests/some_package/images/osx/logo.png
/tests/some_package/images/win/logo.png
/tests/some_package/images/win7/logo.png

3. Use case: Cross-platform image that only supports the locale ro.

Location:

/tests/some_package/images/common/ro/logo.png

4. Use case: Platform- and locale-specific image.

Location:

/tests/some_package/images/linux/ro/logo.png
/tests/some_package/images/osx/ro/logo.png
/tests/some_package/images/win/ro/logo.png
/tests/some_package/images/win7/ro/logo.png

---

Using the image in code

All images in Iris are referenced by instantiation of a Pattern object. Pass the file name of the image to the Pattern constructor to create this object.

Note:
If your image name includes the sequence @2x, just use the name minus this sequence, e.g.:

# Creating Pattern for '[email protected]'.
iris_image = Pattern('my_image.png')
if exists(iris_image):
    call_another_function()
else:
    different_steps()

---

Special considerations for platform-specific images

If an image does not exist on all platforms, then the Pattern creation must be done inside logic that detects the current platform. Otherwise, the image will not be found, and the code will raise an exception.

if Settings.is_linux():
    # This pattern only exists for Linux
    my_icon = Pattern('window_icon.png')
    icon_exists = exists(my_icon)
else:
    # Logic for other platforms goes here.

---

Order of image importance

Iris gives you the flexibility of determining if an image needs to be platform- or locale-specific, or if it can be used everywhere (common). To do this, image lookup is performed at runtime in order of specificity. Iris will use the first image that it finds that matches a supported path.

1. Inside current platform > locale
2. Inside common > locale
3. Inside current platform
4. Inside common