open method

Class: EyesPlatform: SeleniumLanguage: JavaScript
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 (in case of a normal completion) or (in case of an aborted exception) method. Only after this, you can call again on the same Eyes object.

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.