visualregression

visual regression

Simple package to enable comparing reference images to screenshots from full web pages and specific elements. This package cannot be run by itself, it's intended to be used within your own Go program.

go get github.com/marcelblijleven/visualregression

Getting started

References

The visualregression package uses reference to figure out which screenshots to take. It does so via a json file, typically named references.json.

Example:

[
  {
    "name": "product tile",
    "selector": ".c-product-tile",
    "path": "https://example.com/tile",
    "actions": [
      {
        "type": "click",
        "selector": "#accept-cookies"
      }
    ]
  },
  {
    "name": "cookie popup",
    "selector": "#cookie-popup",
    "path": "https://example.com"
  },
  {
    "name": "full page",
    "path": "https//example.com",
    "actions": [],
    "cookies": [
      {
        "name": "dnt",
        "value": "1",
        "expires": 16412334,
        "domain": "www.example.com",
        "path": "/",
        "httpOnly": false,
        "secure": false
      }
    ]
  },
  {
    "name": "multiple viewports",
    "selector": "#cookie-popup",
    "path": "https://example.com",
    "viewports": [
      {
        "width": 1920, "height": 1080, "scale": "2.0"
      },
      {
        "width": 360, "height": 640, "scale": "1"
      }
    ]
  }
]

Creating reference images

To create base images, you can use the following example

package main

import (
	vr "github.com/marcelblijleven/visualregression"
)

func main() {
	headless := true
	override := true
	config := vr.NewConfig("references.json", headless, override)

	if err := vr.CreateReferenceImages(config); err != nil {
		panic(err)
	}
}

Note: It is not recommended to compare headless screenshots to non headless screenshots, as this might lead to false errors.

Running tests

package main

import (
	vr "github.com/marcelblijleven/visualregression"
)

func main() {
	// ..... //
	vr.Threshold = 5
	vr.RunTests(config)
}

Output

Reports

If an image has a difference above threshold, a comparison image will be created at reports/. You can customise this location by modifying the vr.ReportsDir variable.

Results

By default, the visualregression package will output any results to os.Stdout and os.Stderr. If you want other loggers, you can do so by assiging a *log.Logger to the config

package main

import (
	"bytes"
	vr "github.com/marcelblijleven/visualregression"
	"log"
)

func main() {
	var buf bytes.Buffer
	customLogger := log.New(&buf, "EXAMPLE\t", log.Ltime)
	customErrorLogger := log.New(&buf, "PANIC\t", log.Ltime)
	
	config := vr.NewConfig("references.json", true, true).
		WithInfoLog(customLogger).
		WithPassedLog(customLogger).
		WithFailedLog(customLogger).
		WithErrorLog(customErrorLogger)

	vr.RunTests(config)
}

Notes

This package required changes introduces in (https://github.com/chromedp/chromedp/pull/863)[this pull request]. Until this pull request is merged, you can use the following workaround:

Clone branch with changes to your computer

git clone --single-branch --branch screenshot git@github.com:ZekeLu/chromedp.git

Use a replace directive in your go.mod to temporarily replace chromedp/chromedp with ZekeLu's fix

replace github.com/chromedp/chromedp => /Users/your-user/path-to-your-go-workspace/src/github.com/ZekeLu/chromedp