open method
Call this method to start a test, before calling any of the check methods.
Syntax
promise = eyes.open(driver, appName, testName, viewportSize)
Parameters
- appName
- Type:string
The application name. This may be any string.
You can set the application name globally using the,
setappname
If you do, then set this parameter to a value of
nullTBD
to indicate that the global default should be used.
- testName
- Type:string
- The name of the test.
This name must be unique within the scope of the application name.
It may be any string.
- viewportSize
- Type:{width: number, height: number}
The size of the viewport
The size of the viewport passed as an object.
The size of the viewport passed as an object {'width':, 'height':}
Defines the viewport size of the browser that will be set before the start of the test. If this parameter is not provided then the viewport size will be based on the current browser window size. See
Using viewports in Eyes for more details.
- driver
- Type:WebDriver
- The web driver.
Return value
- Type: Promise<WebDriver>
-
The returned web driver is a clone of the driver passed as a parameter.
It is recomended that you use the web driver object returned by this method in all further calls to the web driver.
This allows Eyes to record these interactions and play them back in the Eyes Test Manager.
Remarks
After making a call to this method, you must eventually call
You can define the various test parameters in a number of ways:
- Pass this method the application name, test name and (optionally) the viewport parameters
- Pass this method a configuration object setup with values for the above three parameters and other configuration properties.
- Pass only a driver, the above parameters are taken from the default configuration. The default configuration is setup using the various properties.
When running multiple tests on a common Eyes variable, you should only use one of these methods.
Example
The example below shows a basic skeleton of an Eyes visual test using Selenium. For a more detailed example and explanation please see Writing tests with the Eyes SDK.
The main points to note are:
- The first step is to instantiate an object of the
class.
Using this object, you call various methods and properties to configure and run your visual tests.
When the constructor is called without a parameter, then the checkpoints are taken from screenshots on a browser running on your test computer. To use the Visual Grid to render the checkpoint screenshots see Setting up and configuring the Visual Grid.
- In order to do a visual test you have to provide your API Key.
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
. To obtain your key see How to obtain your API key
- You access the web page you are testing, and provide mouse and keyboard events using the platform driver. In this example we create a chrome driver.
- Before you start your test there are various configuration you can do that affect the default way images are captured or the way the image is processed. For example,
In this snippet, the
is set to ensure that the entire webpage is captured even if it is larger than the viewport. As another example, the
is configured here 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.
If a particular checkpoint needs a different configuration then you can use the Fluent API to change some of the configuration options.
- Now you start a test. The first parameter you pass is the webdriver you created previously in step 3. You also pass two strings, an application name and test name that together uniquely identifier this test, and optionally, the viewport size, which defines the viewport of the widow in which the application run. These three values, along with the browser and operating system type determine the baseline that will be used for matching. 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. The method returns a web driver which is a clone of the web driver you passed as a parameter. In most cases you should use this returned web driver instance for further calls to the web driver.
- Now you use the web driver to navigate the browser to the test URL.
- Next comes the heart of visual testing - telling eyes to capture a screenshot image and to send it to the Eyes server for processing. The checkwindow method used here is the simplest way to execute a checkpoint, when what you want is to test the entire window.
In cases where parts of the window need to be ignored, need a different match level, or need some other special processing, use the check method and the Fluent API methods. See The Eyes SDK check Fluent API for more details and examples.
You may call as many check points as you want, typically you will call the web driver to surf to different pages, click buttons or menus, enter text and so on to fully exercise your UI and call checkwindow
or check
or check_region
or one of the other check calls.
in each state.
- When you're done calling all your test points, call the close method. If you pass a false value to this method then it will return 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 abortifnotclosed to correctly terminate the test.
- Finally you should quit your web driver.