Playwright JavaScript overview
This SDK allows you to work with Applitools Eyes using Playwright JavaScript.
For information about installing and configuring this SDK, see Testing web apps in TypeScript using Playwright on the Applitools Tutorial site.
Installation
Install Eyes-Playwright as a local dev dependency in your tested project:
npm i -D @applitools/eyes-playwright
Getting started
To get started with this SDK, you need to set the following:
- Applitools API key
- Eyes server URL - Required only if the Eyes server is not deployed on the Eyes public server.
Entering the Applitools API key
To authenticate via the Applitools server and run tests, you need to set the environment variable APPLITOOLS_API_KEY
to the API key provided from Applitools Eyes. For details how to retrieve your API key, see the Applitools documentation.
Entering the API Key on Linux or a Mac
export APPLITOOLS_API_KEY=<API_key>
Entering the API Key on Windows
set APPLITOOLS_API_KEY=<API_key>
Eyes server URL
If the Eyes server is not deployed in https://eyes.applitools.com
, you need to set the Server URL in the environment variable APPLITOOLS_SERVER_URL
before running tests.
The server URL of your Applitools Eyes dashboard is in the format https://<MY_COMPANY>.applitools.com
Entering the server URL on Linux or a Mac
export APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>
Entering the server URL on Windows
set APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>
Recommended practice for using the SDK
A test in Applitools Eyes always starts with a eyes.open
call and ends with eyes.close
. The steps in the test are calls to eyes.check
between eyes.open
and eyes.close
calls.
A test is structured as following:
eyes.open
[step 1]
[step 2]
...
eyes.close
Common methods
Eyes constructor
Creates an instance of Eyes
, which then exposes methods to run and configure visual tests.
const eyes = new Eyes(runner)
runner
- A runner instance which manages tests across multipleEyes
instances. The runner can be an instance of either aClassicRunenr
or aVisualGridRunner
. For more information, see Runners.
open
Creates an Eyes test. This will start a session with the Applitools server.
eyes.open(page, appName, testName, viewportSize)
Visual tests and baselines
By using the open
, check
, and close
methods on Eyes
, you are creating visual tests in Applitools Eyes. A visual test is a sequence of screenshots, compared with a baseline. The baseline is also a sequence of screenshots. The specific baseline to compare against is found by using the values for:
- Browser
- Operating system
- App name
- Test name
- Viewport size
The baseline is created automatically when running a test with specific values for these 5 parameters for the first time. For example, if you run a test with Chrome on OS X and specify the app name, test name and viewport size via eyes.open(t, 'some app', 'some test', {width: 1200, height: 800})
, the first time the test runs with these parameters, a baseline will be created. Any subsequent execution with the same values will compare screenshots against this baseline. The test will actually be created after running eyes.close
, and the results of the test are returned as a TestResults
object.
For more information, see How Eyes compares checkpoints and baseline images in the Eyes Knowledge Center.
Batches
You can aggregate tests that are run in different processes, or in different Eyes instances, under the same batch. This is done by providing the same batch ID to these tests.
For instructions, see the Organize tests in batches section below.
For more information, see How to organize your tests with batches
check
Generates a screenshot of the current page and add it to the Applitools Test.
Syntax
eyes.check(checkSettings)
For a description of common actions with this class, see check Settings
closeAsync
Closes the Eyes test but does not wait for the Eyes server to return a result. This command enables your system to continue running tests while Eyes completes its comparisons in the background. You should call this command at the end of each test, symmetrically to eyes.open
.
After executing all Eyes tests, your code should call Runner.getAllTestResults
to retrieve all test results as a TestResultsSummary
.
const testResults = await eyes.closeAsync()
close
Closes the Eyes test and waits for the Eyes Server to return a single result. The close
command then returns a TestResults
object with detailed test result data. This method takes an optional boolean parameter, if false
it will not throw an exception if the test found differences (default is true
). You should call this command at the end of each test, symmetrically to eyes.open
.
This is a legacy API as it only returns a single result. We recommend using eyes.closeAsync
and eyes.getResult
instead of this API.
const testResults = await eyes.close()
//or
const testResults = await eyes.close(false)
Return value: TestResults
getResults
Returns TestResults
for the last test (open-
... -close
) by the Eyes instance.
If you call getResults
before eyes.closeAsync
the method aborts the test.
const results1 = await eyes.getResults() // throws error by default
const results2 = await eyes.getResults(true) // explicitly specifies that error should be thrown
const results3 = await eyes.getResults(false) // explicitly specifies that error should NOT be thrown
Runners
Used to manage multiple Eyes sessions. There are the following types of runners:
ClassicRunner
- Used when the screenshot is taken by the SDK itself.VisualGridRunner
- Used when the screenshot is taken by the Ultrafast Grid.
For details, see Runners