screentest

Documentation

Overview

Package screentest implements script-based visual diff testing for webpages.

Scripts

A script is a template file containing a sequence of testcases, separated by blank lines. Lines beginning with # characters are ignored as comments. A testcase is a sequence of lines describing actions to take on a page, along with the dimensions of the screenshots to be compared. For example, here is a trivial script:

compare https://go.dev {{.ComparisonURL}}
pathname /about
capture fullscreen

This script has a single testcase. The first line sets the origin servers to compare. The second line sets the page to visit at each origin. The last line captures fullpage screenshots of the pages and generates a diff image if they do not match.

Keywords

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

windowsize 540x1080

Use compare ORIGIN ORIGIN to set the origins to compare.

compare https://go.dev http://localhost:6060

Use header KEY:VALUE to add headers to requests

header Authorization: Bearer token

Add the ::cache suffix to cache the images from an origin for subsequent test runs.

compare https://go.dev::cache http://localhost:6060

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

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

Use output DIRECTORY to set the output directory for diffs and cached images.

output testdata/snapshots

USE output BUCKETNAME for screentest to upload test output to a Cloud Storage bucket. The bucket must already exist prior to running the tests.

output gs://bucket-name

Values set with the keywords above apply to all testcases that follow. Values set with the keywords below reset each time the test keyword is used.

Use test NAME to create a name for the testcase.

test about page

Use pathname PATH to set the page to visit at each origin. If no test name is set, PATH will be used as the name for the test.

pathname /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 capture [SIZE] [ARG] to create a testcase with the properties defined above.

capture fullscreen 540x1080

When taking an element screenshot provide a selector.

capture element header

Evaluate JavaScript snippets to hide elements or prepare the page in some other way.

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

Chain capture commands to create multiple testcases for a single page.

windowsize 1536x960
compare https://go.dev::cache http://localhost:6060
output testdata/snapshots

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

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

Index

• func CheckHandler(glob string, opts CheckOptions) error
• func TestHandler(t *testing.T, glob string, opts TestOpts)
• type CheckOptions
• type TestOpts

Functions

func CheckHandler

func CheckHandler(glob string, opts CheckOptions) error

CheckHandler runs the test scripts matched by glob. If any errors are encountered, CheckHandler returns an error listing the problems.

func TestHandler

func TestHandler(t *testing.T, glob string, opts TestOpts)

TestHandler runs the test script files matched by glob.

Types

type CheckOptions

type CheckOptions struct {
	// Update is true if cached screenshots should be updated.
	Update bool

	// MaxConcurrency is the maximum number of testcases to run in parallel.
	MaxConcurrency int

	// Vars are accessible as values in the test script templates.
	Vars map[string]string

	// DebuggerURL is the URL to a chrome websocket debugger. If left empty
	// screentest tries to find the Chrome executable on the system and starts
	// a new instance.
	DebuggerURL string

	// If set, only tests for which Filter returns true are included.
	// Filter is called on the test name.
	Filter func(string) bool
}

type TestOpts

type TestOpts struct {
	// Update is true if cached screenshots should be updated.
	Update bool

	// Parallel runs t.Parallel for each testcase.
	Parallel bool

	// Vars are accessible as values in the test script templates.
	Vars map[string]string
}