Repository files navigation

Gemini is a utility for regressiontesting the visual appearance of web pages.

Gemini allows you to:

• Work with different browsers:

  • Google Chrome (tested in latest version)
  • Mozilla Firefox (tested in latest version)
  • IE8+
  • Opera 12+

• Test separate sections of a web page

• Include thebox-shadow andoutline properties when calculating element position and size

• Ignore some special case differences between images (rendering artifacts, text caret,etc.)

• Gather CSS test coverage statistics

Gemini was created atYandex and is especiallyuseful to UI library developers.

npm install -g gemininpm install -g selenium-standaloneselenium-standalone install

Put the.gemini.js file in the root of your project:

module.exports={rootUrl:'http://yandex.ru',gridUrl:'http://127.0.0.1:4444/wd/hub',browsers:{chrome:{desiredCapabilities:{browserName:'chrome'}}}};

Write a test and put it in thegemini folder in the root of your project:

gemini.suite('yandex-search',(suite)=>{suite.setUrl('/').setCaptureElements('.home-logo').capture('plain');});

You have written a new test and should save a reference image for it:

gemini update

Startselenium-standalone in a separate tab before running the tests:

selenium-standalone start

Run gemini tests:

gemini test

Required software:

1. WebDriver server implementation. There are several options:

   • Selenium Server — for testing indifferent browsers. Launch with theselenium-standalone start command (if you will get error like "No Java runtime present, requesting install." you should installJava Development Kit (JDK) for your OS.).

   • ChromeDriver — fortesting in Google Chrome. Launch with thechromedriver --port=4444 --url-base=wd/hub command.

   • PhantomJS — launch with thephantomjs --webdriver=4444 command.

   • Cloud WebDriver services, such asSauceLabs orBrowserStack

2. Compiler with support for C++11 (GCC@4.6 or higher). This is apng-img requirement.Compiling on Windows machines requires thenode-gyp prerequisites.

To install the utility, use thenpminstall command:

npm install -g gemini

Global installation is used for launching commands.

Gemini is configured using a config file at the root of the project.Gemini can use one of the following files:

• .gemini.conf.js
• .gemini.conf.json
• .gemini.conf.yml
• .gemini.js
• .gemini.json
• .gemini.yml

Let's say we want to run our tests only in the locally installedPhantomJS.

In this case, the minimal configuration file will only need to have the root URLof your web app and the WebDriver capabilities ofPhantomJS:For example,

rootUrl:http://yandex.combrowsers:PhantomJS:desiredCapabilities:browserName:phantomjs

Also, you need to runPhantomJS manually inWebDriver mode:

phantomjs --webdriver=4444

If you are using a remote WebDriver server, you can specify its URL with thegridUrl option:

rootUrl:http://yandex.comgridUrl:http://selenium.example.com:4444/wd/hubbrowsers:chrome:desiredCapabilities:browserName:chromeversion:"45.0"firefox:desiredCapabilities:browserName:firefoxversion:"39.0"

You can also set up each browser to have its own node:

rootUrl:http://yandex.combrowsers:chrome:gridUrl:http://chrome-node.example.com:4444/wd/hubdesiredCapabilities:browserName:chromeversion:"45.0"firefox:gridUrl:http://firefox-node.example.com:4444/wd/hubdesiredCapabilities:browserName:firefoxversion:"39.0"

See the details of the config file structure and availableoptions.

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 a block'stest suites.

For example, let's write a test for a search block atyandex.com:

gemini.suite('yandex-search',function(suite){suite.setUrl('/').setCaptureElements('.search2__input').capture('plain').capture('with text',function(actions,find){actions.sendKeys(find('.search2__input .input__control'),'hello gemini');});});

We are creating a new test suiteyandex-search, assuming that we will capture the.search2__input element from the root URLhttp://yandex.com. We know that theblock has two states:

• plain — right after the page is loaded
• with text — with thehello gemini text inserted into.search2__input .input__control

States are executed one after another in the order in which they are defined, without the browserreloading in between.

See the details of test creation methods.

To complete the test creation procedure, you need to take reference shots usingthe following command:

gemini update [paths to test suites]

To launch a test (to compare the current state of a block with a reference shot), usethe command:

gemini test [paths to test suites]

See the details of interaction with CLI and availableoptions.

You can use theGemini graphical user interface instead of the command line. Itis located in thegemini-gui packageand must be installed additionally:

npm install -g gemini-gui

GUI advantages:

• Handy preview of reference shots

• Clear real-time demonstration of the differences between a reference shot andthe current state of a block

• Easy to update reference shots

Gemini can be extended with plugins. You can choose from theexistingplugins orwrite yourown. To use a plugin, install and enable it in your.gemini.yml:

system:plugins:some-awesome-plugin:plugin-option:value

To see the difference between the current state of a block and a reference picturemore clearly, use theHTML reporter - plugin for gemini. Thisplugin produces HTML report, which displays reference image, current image anddifferences between them, for each state in each browser. When all tests arecompleted, you will see a link to HTML report.

To use Gemini in your scripts or build tools, you can use the experimentalprogrammatic API.

To learn more about all events in Gemini, see theevents documentation.