Getting started
A guide for getting started using ez_visual_regression
, designed to help make it easier to get up and running quickly!
Please note all examples use webdriver manager and Chrome. Neither of these are strictly required, any valid non-headless (standard) browser with bindings will work (firefox, safari etc.)
Installation
From source
- Clone this repo: (put github/source code link here)
- Run
pip install .
orsudo pip3 install .
in the root directory
From PyPi
- Run
pip install ez-visual-regression
Using ez_visual_regression from the API
The most basic example is comparing a full page screenshot of a URL (you can also use a file path to an HTML file). If it's the first time you've run the utility it will generate some images in the folder you specify, see the home page for an explanation of these images. Once you've done the initial run and generated a baseline image, you can then just run the same code whenever you want to do visual regression testing.
Full page visual regresion testing
Here's the basic code:
# Setup driver
from ez_visual_regression.api import instantiate_driver
driver_name = "chrome"
driver = instantiate_driver(driver_name)
from ez_visual_regression.api import assert_image_similarity_to_baseline
# Configuration variables
URL = "https://canadiancoding.ca"
folder = "results"
# Creates baseline if one isn't available
assert_image_similarity_to_baseline(driver, URL, folder=folder)
You can also shorten this using built in system to instantiate a driver:
from ez_visual_regression.api import assert_image_similarity_to_baseline, get_installed_driver, instantiate_driver
# Configuration variables
URL = "https://canadiancoding.ca"
folder = "results"
driver_name = "chrome"
driver = instantiate_driver(driver_name)
# Creates baseline if one isn't available
assert_image_similarity_to_baseline(driver, URL, folder=folder)
We ended up with some decent results, but even compared to our baseline image there was a difference because of the page animations:
baseline
current
thresh
diff
At this point we could tweak the thresholds (see advanced features for details), or we could ignore the animated element (see how to do this here).
Element visual regresion testing
To test an individual element you just need to specify a locator
parameter (needs to be a Query/CSS selector):
# Setup driver
from ez_visual_regression.api import instantiate_driver
driver_name = "chrome"
driver = instantiate_driver(driver_name)
from ez_visual_regression.api import assert_image_similarity_to_baseline
# Configuration variables
URL = "https://canadiancoding.ca"
folder = "results"
locator = "nav"
# Creates baseline if one isn't available
assert_image_similarity_to_baseline(driver, URL, folder=folder, locator=locator)
Multiple element visual regression testing
To test multiple elements you just need to specify a locator
parameter (needs to be a Query/CSS selector), and the multielements
parameter:
# Setup driver
from ez_visual_regression.api import instantiate_driver
driver_name = "chrome"
driver = instantiate_driver(driver_name)
from ez_visual_regression.api import assert_image_similarity_to_baseline
# Configuration variables
URL = "https://canadiancoding.ca"
folder = "results"
locator = ".nav-item p"
# Creates baseline if one isn't available
assert_image_similarity_to_baseline(driver, URL, folder=folder, locator=locator, multielements=True)
Using ez_visual_regression from the CLI
There's several ways to use ez_visual_regression from the cli. The two main ones are with a normal command, or a config. Normal commands are good for one-off systems, or systems with 1 test, configs are better for multiple tests.
Normal commands
There are 2 options for normal commands:
ezvr screenshot <url> [-l locator] [-i ignored_elements] [-f folder] [-m]
ezvr test <url> [-l locator] [-i ignored_elements] [-f folder] [-w warning_threshold] [-e error_threshold] [-m]
screenshot will let you take a normal screenshot, only the URL is needed, everything else is optional. Test will do the normal tests you are expecting where there will be a baseline image generated then tested against.
Config
You can also setup a config file and then access it using the command:
ezvr [<config_file>] [-h] [-v]
For details about how to use the config file checkout this page