Gemini is the utility for regression testing of web pages appearance.
Its key features are:
- Compatibility with different browsers;
- Ability to test separate sections of a web page;
- Position and size of an element are calculated including its
box-shadow
andoutline
properties; - Some special case differences between images (rendering artifacts, text caret, etc.) are ignored;
- CSS test coverage statistics.
Gemini is created at Yandex and will be especially useful to UI libraries developers.
Current document is a quick step-by-step guide that describes installation, configuration and usage of Gemini.
Required software:
- Selenium Server - for testing in different browsers.
- PhantomJS - headless version of a WebKit browser.
To install the utility use npm command install
:
npm install -g gemini
Global installation is used for commands launch.
To write the tests you will also need local installation of Gemini
. Run the following command in project directory:
npm install gemini
Gemini is configured using .gemini.yml
file at the root of the project.
In case only local PhantomJS
copy is being used for testing, the configuration is as simple as declaring the website rootUrl
option.
For example,
rootUrl: http://yandex.com
Also, you need to run PhantomJS
manually in a WebDriver
mode:
phantomjs --webdriver=4444
In order to run tests in different browsers use Selenium
. You may choose remote Selenium Grid
, a cloud service (such as SauceLabs or BrowserStack), or run a local server:
java -jar selenium-server-standalone.jar
Additionally, declare Selenium Server
address and a list of browsers used for testing in configuration file:
rootUrl: http://yandex.com
gridUrl: http://localhost:4444/wd/hub
browsers:
chrome:
browserName: chrome
version: "37.0"
firefox:
browserName: firefox
version: "31.0"
In browsers
section, keys are unique browser ids (chosen by user) and values are DesiredCapabilites of a corresponding browser.
See the details of a config file structure.
Each of the blocks that are being tested may be in one of the determined states. States are tested with the help of chains of step-by-step actions declared in test suites of a block.
For example, let's write a test for a search block at yandex.com:
var gemini = require('gemini');
gemini.suite('yandex-search', function(suite) {
suite.setUrl('/')
.setCaptureElements('.main-table')
.capture('plain')
.capture('with text', function(actions, find) {
actions.sendKeys(find('.input__control'), 'hello gemini');
});
});
We create a new test suite yandex-search
and assume that we will capture the .main-table
element from a root URL http://yandex.com
. We know that the block has two states:
plain
โ right after the page is loaded;with text
- withhello gemini
text inserted into.input__control
.
States are executed one after another in order of definition without browser reload in between.
See the details of tests creation methods.
To complete the test creation procedure you need to take reference shots using the following command:
gemini gather [paths to test suites]
For test launch (to compare current state of a block with a reference shot) use the command:
gemini test [paths to test suites]
To see the difference between current state of a block and a reference picture more clearly, use HTML reporter:
gemini test --reporter html [paths to test suites]
You can use both console and HTML reporters at the same time:
gemini test --reporter html --reporter flat [paths to test suites]
See the details of interaction with CLI and available options.
Instead of a command line you can use graphical user interface of Gemini
. It is located in
gemini-gui package and must be installed additionally:
npm install -g gemini-gui
GUI advantages:
- Handy reference shots preview;
- Clear real-time demonstration of differences between a reference shot and current state of a block;
- Easy update of reference shots.
To use Gemini in your scripts or build tools plugins you can use experimental programmatic API.