assertView

Overview

Use the assertView command to take a screenshot for a specific test state and compare it with a reference.

info

The assertView command uses waitForExist (with waitTimeout and waitInterval) to wait for the element to exist before taking a screenshot.

It also automatically waits for static (fonts, images, etc.) to load using the waitForStaticToLoad command.

Usage

await browser.assertView(state, options);
await browser.assertView(state, selector, options);

Command Parameters

Name	Type	Description
state	`string`	Required parameter. The name of the test state. It must be unique within a single test.
selector	`string \| string[]`	Optional parameter. Can be skipped. The DOM element selector to capture. If skipped, current viewport is captured.
options	`AssertViewOpts`	Optional settings for the assertView command.

state

Required parameter. Specifies the name of the test state. The name must be unique within a single test.

selector

Optional parameter. Specifies the selector of the DOM element to capture:

If not specified, assertView will take a screenshot of the current viewport
If an array of selectors is passed, assertView will take a screenshot of an area covering all passed selectors
If any of the selectors matches multiple elements, assertView will take a screenshot of the first one

options

Specifies the settings for the assertView command:

Option	Type	Description
ignoreElements	`string \| string[]`	Elements (specified as selectors) that will be ignored when comparing screenshots. Ignoring is implemented by painting the listed elements black. If multiple elements match any of the selectors, all matches will be ignored.
tolerance	`number`	Sensitivity to color differences, `3.0` by default. Read more.
antialiasingTolerance	`number`	Sensitivity to antialiasing, `4` by default. Read more.
allowViewportOverflow	`boolean`	By default, Testplane will print a warning if element could not be captured in full, this option disables the warning. Use this option in combination with `captureElementFromTop` to disable any scrolling that might happen before capture.
captureElementFromTop	`boolean`	By default, Testplane may scroll the element into view before capturing a screenshot, if it's not visible initially. If this option is disabled and element is not visible initially, Testplane will throw an error.
compositeImage	`boolean`	By default, Testplane will take capture the element in full by taking multiple screenshots of the element and scrolling, and then stitch them together. When disabled, only the part of the element that is visible on the first screenshot will be captured.
screenshotDelay	`number`	Delay in milliseconds before taking a screenshot. This can be useful to wait for a scrollbar to disappear before capturing a screenshot.
disableAnimation	`boolean`	Disable animations and transitions when taking a screenshot. Default is `true` starting from version `8.0.0`.
ignoreDiffPixelCount	number \| `${number}%`	Percentage of pixels to ignore in the diff. Useful for ignoring very small diffs. Default is `0`. Available starting from version `8.2.0`.
waitForStaticToLoadTimeout	`number`	Default is `5000`. Timeout for `waitForStaticToLoad` command, which is automatically called before taking screenshot. If value is set to `0`, waiting is disabled. Available starting from version `8.32.0`.
disableHover	`"always" \| "never" \| "when-scrolling-needed"`	By default, Testplane will disable hover effects if scrolling is needed to capture element in full. Available starting from version `9.0.0`.
cropMargins	`{ top?: number, right?: number, bottom?: number, left?: number }`	Determines the margins to crop the screenshot by. Useful to crop scrollbars on android emulators. Available starting from version `9.0.0`.
selectorToScroll	`string`	Deprecated. Starting from Testplane 9, the scrollable element is determined automatically. Manual override affects what element Testplane will scroll when capturing a screenshot.

Usage Examples

Visual check of certain element

it("should assert view", async ({ browser }) => {
    await browser.url("some/url");
    await browser.assertView("plain", ".button");

    await browser.click(".button");
    await browser.assertView("clicked", ".button");
});

Visual check of current viewport

it("should assert viewport without selector", async ({ browser }) => {
    await browser.url("some/url");
    await browser.execute(() => window.scrollTo(0, 1000));
    await browser.assertView("plain");

    await browser.$(".button").click();
    await browser.assertView("clicked", { ignoreDiffPixelCount: 5 });
});

Visual check with additional options

it("should assert view with given options", async ({ browser }) => {
    await browser.url("some/url");
    await browser.assertView("plain", ".form", {
        ignoreElements: [".link"],
        tolerance: 5,
        antialiasingTolerance: 4,
        allowViewportOverflow: true,
        captureElementFromTop: true,
        compositeImage: true,
        screenshotDelay: 10,
        selectorToScroll: ".modal",
    });
});

History

Version	Changes
v9.0.0	Major update to the screenshot engine, see full article for more details. Added `disableHover` and `cropMargins` options. `selectorToScroll` is deprecated because the scrollable element is now detected automatically. `tolerance` is now `3.0` by default instead of `2.3`.
v8.32.0	Added `waitForStaticToLoadTimeout` option.
v8.2.0	Added `ignoreDiffPixelCount` option.
v8.0.0	`disableAnimation` defaults to `true`.

Overview​

Usage​

Command Parameters​

state​

selector​

options​

Usage Examples​

History​

Related Commands​