The bok-choy framework uses Needle to provide the ability to capture portions of a rendered page in the browser and assert that the image captured matches that of a baseline. Needle is an optional dependency of bok-choy, which you can install via either of the following commands:
pip install bok-choy[visual_diff]
pip install needle
The general methodology for creating a test with a screenshot assertion consists of the following steps.
assertScreenshot()
takes two arguments: a CSS selector for the element to
capture, and a filename for the image.
The following example uses the same my_test.py test case shown in the previous section, with an assertion added to check that the site logo for the edx.org home page has not changed.
img.site-logo
is the css locator for the element
that we want to capture and compare.edx_logo_header
is the filename that will be used
for both the baseline and the actual results. The .png extension is appended
automatically.Note
For test reliability and synchronization purposes, a bok-choy best practice is to employ Promises to ensure that the page has been fully rendered before you take the screenshot. At the very least, you should first assert that the element you want to capture is present and visible on the screen.
my_test.py, with the screenshot assertion.
from bok_choy.web_app_test import WebAppTest
from page import EdxHomePage
class TestEdxHomePage(WebAppTest):
def test_page_existence(self):
homepage = EdxHomePage(self.browser).visit()
css_locator = 'img.site-logo'
self.assertTrue(homepage.q(css=css_locator).first.visible)
self.assertScreenshot(css_locator, 'edx_logo_header')
To create an initial screenshot of the logo, run the test case in “baseline
saving” mode by specifying the nose parameter --with-save-baseline
.
$ nosetests my_test.py --with-save-baseline
If using pytest, you can instead set the environment variable
NEEDLE_SAVE_BASELINE
.
$ NEEDLE_SAVE_BASELINE=true py.test my_test.py
The folder in which the baseline and actual (output) screenshots are saved is determined using the following environment variables.
In our example, we would execute the test once with the save baseline parameter to create screenshots/baseline/edx_logo_header.png. We would then open it up and check that it looks okay.
Now if we run our tests, it will take the same screenshot and check it against the saved baseline screenshot on disk.
$ nosetests my_test.py
If a regression causes them to become significantly different, then the test will fail.
See the Needle documentation for more information on the following advanced features.