screentest

command
v0.0.0-...-9827523 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 10, 2025 License: BSD-3-Clause Imports: 28 Imported by: 0

Documentation

Overview

Screentest compares images of rendered web pages. It compares images obtained from two sources, one to test and one for the expected result. The comparisons are driven by a script file in a format described below.

Usage

screentest [flags] testURL wantURL file ...

The first two arguments are the URLs being tested and the URL of the desired result, respectively. The remaining arguments are script file paths.

The URLs can be actual URLs for http:, https:, file: or gs: schemes, or they can be slash-separated file paths (even on Windows).

The flags are:

-c
  Number of test cases to run concurrently.
-d
  URL of a Chrome websocket debugger. If omitted, screentest uses the
  Chrome executable on the command path. It will look first for the
  headless-shell binary, which is preferred.
-headers
  HTTP(S) headers to send with each request, as a comma-separated list of name:value.
-retrypixels N
  If the difference is no more than N pixels, take another screenshot. Repeat up to 3
  times. N should be small. This is a last-resort method for handling small, inexplicable
  output variations.
-run REGEXP
  Run only tests matching regexp.
-o
  URL or slash-separated path where output files for failing tests are written.
  If omitted, files are written to a subdirectory of the user's cache directory.
  At the start of each run, existing files are removed.
  Each test file is given its own directory, so test names in two files can be identical,
  but the directory name is the basename of the test file with the extension removed, so
  files with identical basenames will overwrite each other.
-u
  Instead of comparing screenshots, use the test screenshots to update the
  want screenshots. This only makes sense if wantURL is a storage location
  like a file path or GCS bucket.
-v
  Variables provided to script templates as comma-separated KEY:VALUE pairs.

Headless Chrome

Screentest needs a headless Chrome process to render web pages. Although it can use a full Chrome browser, we have found the headless-shell build of Chrome to be more reliable. Install headless-shell on your local machine with this command:

npx @puppeteer/browsers install chrome-headless-shell@VERSION

Put the binary on your path and screentest will find it. Omit the -d flag in this case.

You can also run headless-shell in docker. We use this command:

docker run --detach --rm --network host --shm-size 8G --name headless-shell chromedp/headless-shell:VERSION

Then pass "-d ws://localhost:9222" to screentest.

Scripts

A script file contains one or more test cases described as a sequence of lines. The file is first processed as Go template using the text/template package, with a map of the variables given by the -v flag provided as `.`.

The script format is line-oriented. Lines beginning with # characters are ignored as comments. Each non-blank, non-comment line is a directive, listed below.

Each test case begins with the 'test' directive and ends with a blank line. A test case describes actions to take on a page, along with the dimensions of the screenshots to be compared. For example, here is a trivial script:

test about
path /about
capture fullscreen

This script has a single test case. The first line names the test. The second line sets the page to visit at each origin. The last line captures full-page screenshots of the pages and generates a diff image if they do not match.

Directives

Use windowsize WIDTHxHEIGHT to set the default window size for all test cases that follow.

windowsize 540x1080

Use block URL ... to set URL patterns to block. Wildcards ('*') are allowed.

block https://codecov.io/* https://travis-ci.com/*

The directives above apply to all test cases that follow. The ones below must appear inside a test case and apply only to that case.

Use test NAME to create a name for the test case.

test about page

Use path PATH to set the page to visit at each origin.

path /about

Use status CODE to set an expected HTTP status code. The default is 200.

status 404

Use click SELECTOR to add a click an element on the page.

click button.submit

Use wait SELECTOR to wait for an element to appear.

wait [role="treeitem"][aria-expanded="true"]

Use eval JS to evaluate JavaScript snippets to hide elements or prepare the page in some other way.

eval 'document.querySelector(".selector").remove();'
eval 'window.scrollTo({top: 0});'

Use sleep DURATION to pause the browser for the duration. This is a last resort for deflaking; prefer to wait for an element.

sleep 50ms

Use capture [SIZE] [ARG] to create a test case with the properties defined in the test case. If present, the first argument to capture must be one of 'fullscreen', 'viewport' or 'element'. The optional second argument provides a viewport size. The defaults are 'viewport' with dimensions specified by the windowsize directive.

capture fullscreen 540x1080

When taking an element screenshot provide a selector.

capture element header

Each capture directive creates a new test case for a single page.

windowsize 1536x960

test homepage
path /
capture viewport
capture viewport 540x1080
capture viewport 400x1000

test about page
path /about
capture viewport
capture viewport 540x1080
capture viewport 400x1000

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL