Screenshots Python Tutorial

The example below shows a basic skeleton of an Eyes visual test using the Images SDK. For a more detailed example and explanation please see Writing tests with the Eyes SDK.

import os
from applitools.images import Eyes
from applitools.images import Region
from applitools.images import Target
class HelloWorldBasic:
    # Initialize the eyes SDK and set your private API key.
    uri = "https://eyesapi.applitools.com"
    eyes = Eyes(uri)
    api_key = os.environ.get('MY_APPLITOOLS_API_KEY')                #note 2 
    eyes.api_key = api_key
    # 
    # Add optional global setup/defaults here                        #note 3
    # 
    # Start the test 
    viewport_size = {'width' :1024, 'height' :768}              
    eyes.open('Hello World App', 'Hello World Test',  viewport_size)  #note 4
    try:

        eyes.check_image('./image1.png',"checkpoint 1");              # note 5
        eyes.check("checkpoint 3",
            Target().region("./image1.jpg",Region(10,15,600,400))
                    .ignore(Region(left=10,top=10,width=33,height=43))
            )

        # End the test.
        throwtTestCompleteException = False
        test_results = eyes.close(throwtTestCompleteException)        # note 6
    finally:
        # If the test was aborted before eyes.close was called, ends the test as aborted.
        eyes.abort_if_not_closed()                                    # note 7

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Note:

Install the eyes package by running the following:

pip install eyes-images

The Notes in the comments refer to the points in the description below.

The main points to note are:

The first step is to instantiate an object of the Eyes class.

uri = "https://eyesapi.applitools.com"
eyes = Eyes(uri)

1
2

Using this object, you call various methods and properties to configure and run your visual tests. When the constructor is called without a parameter, the tests will access the Eyes server on the public cloud. To access a different server you can pass an appropriate URL to the Eyes constructor.

In order to do a visual test you have to provide your API Key.

api_key = os.environ.get('MY_APPLITOOLS_API_KEY')                #note 2 
eyes.api_key = api_key

1
2

In this example we show the value being obained from an environment variable.If the environment variable APPLITOOLS_API_KEY is defined then Eyes will automatically use that value as the API key, and you don't need to use the api_key property. To obtain your key see How to obtain your API key

Before you start your test there are various configuration you can do that affect the default way the way the image is processed. For example,

eyes.batch = "My Batch"    
eyes.match_level = MatchLevel.LAYOUT

1
2

In this snippet, the test is assigned a batch name. This defines the name that wil appear in the Test Manager batch panel of the Test results page. You can run several tests in the same batch, where a test is defined as one or more checks between a call to the method open and a call to the method close. For more information on this see How to organize your tests with batches.Also show in the example is a use of the match_level property to configure the test(s) so that the image matching is done less strictly (instead of the default Strict match level). For example if the text on the page is dynamic, you can use the layout match level and Eyes will check the general layout of the page but will not report mismatches due to text or image differences.

Now you start a test.

viewport_size = {'width' :1024, 'height' :768}              
eyes.open('Hello World App', 'Hello World Test',  viewport_size)  #note 4

1
2

You should pass the method open two strings, an application name and test name that together uniquely identifier this test. You can also optionallly pass the viewport size, which declares the size of the image. See open for more details. These three values determine the baseline that will be used to visually test the image. The baselines provides the reference images to which , your test checkpoints images will be compared. For more information on this see Using viewports in Eyes.

Next comes the heart of visual testing - passing the SDK an image or a file path to an image file to send to the Eyes server for processing:

eyes.check_image('./image1.png',"checkpoint 1");              # note 5
eyes.check("checkpoint 3",
    Target().region("./image1.jpg",Region(10,15,600,400))
            .ignore(Region(left=10,top=10,width=33,height=43))
    )

1
2
3
4
5

The first checkpoint in the example is to the check_image method which is the simplest way to execute a checkpoint on an entire image. You may call as many check points as you want.

When you're done calling all your test points, call the close method.

throwtTestCompleteException = False
test_results = eyes.close(throwtTestCompleteException)        # note 6

1
2

If you pass a false value to this method then it will return an object with the results of the test. If you don't pass a parameter or pass a true value then if the test passes then the method will return normally, if there are any mismatches, or new or missing steps, then an exception will be thrown.

Since an exception may be thrown during the test, the call to close may be skipped, so always wrap your test in an exception handler and call abort_if_not_closed to correctly terminate the test.

eyes = Eyes(uri)
viewport_size = {'width' :1024, 'height' :768}              
eyes.open('Hello World App', 'Hello World Test',  viewport_size)  #note 4
try:
    throwtTestCompleteException = False
    test_results = eyes.close(throwtTestCompleteException)        # note 6
finally:
    # If the test was aborted before eyes.close was called, ends the test as aborted.
    eyes.abort_if_not_closed()                                    # note 7

1
2
3
4
5
6
7
8
9

Analyze your test results

Congratulations! You've successfully run your first visual UI test with Applitools Eyes! A detailed report is ready for your inspection at the Applitools Eyes test manager. Watch this 5 minute video to get acquainted with the test manager and to learn the basics of baseline maintenance.

Learn more

Applitools Eyes is a powerful platform for automated visual UI testing that supports full page screenshots, page layout matching, cross-device and browser testing, test batching, baseline branching and merging, automated baseline maintenance, collaboration features, and much more. Applitools has over 40 SDKs supporting a broad range of testing environments.

Reference documentation

To learn more, check out the Applitools Eyes documentation and tutorials for other testing environments.

Request a demo

If you want to see a demo of all our other features, you do request a demo

# Screenshots Python Tutorial

# The main points to note are:

# Analyze your test results

# Learn more

# Reference documentation

# Request a demo