gemini

library0.30.2jsnpmunverified

Gemini is a utility for regression testing the visual appearance of web pages, primarily interacting via a command-line interface and configuration files. It captures screenshots across various browsers to detect visual deviations from reference images, making it particularly useful for UI library developers. The package helps identify subtle rendering artifacts, text caret differences, and provides CSS test coverage statistics. The current stable version is 7.5.2, released in July 2019. The project appears to have a sporadic release cadence, with major version updates becoming infrequent, and the last code activity observed in March 2021. Its differentiators include granular control over capture elements and built-in image comparison tolerance for minor, expected visual variations.

testing

npm install gemini

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GEMINI

gemini

testingjavascriptv0.30.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gemini

✓ const gemini = require('gemini');

✗ import gemini from 'gemini';

Primarily a CLI-driven tool that uses a global 'gemini' object within test suite files (.gemini.js). Direct programmatic import is less common but possible for advanced scenarios. Given the Node.js 8 requirement, CommonJS `require` is the expected pattern.

suite

✓ gemini.suite('my-suite', (suite) => { /* ... */ });

Test suites are defined using `gemini.suite`, where `suite` is typically passed as a callback argument. No explicit import is usually needed within test files if they are configured correctly to be run by the Gemini CLI.

config

✓ module.exports = { /* ... */ }; // in .gemini.js

✗ export default { /* ... */ }; // in .gemini.js

Configuration is handled via a CommonJS module export (e.g., `.gemini.js`) or YAML/JSON files (`.gemini.yml`, `.gemini.json`). ESM exports are not supported for configuration files.

Demonstrates setting up Gemini with a configuration file, defining a test suite, capturing a specific UI element, and the basic CLI commands to run it.

/* .gemini.js (config file in project root) */ module.exports = { rootUrl: 'http://localhost:3000/', // Your application's base URL gridUrl: 'http://127.0.0.1:4444/wd/hub', // WebDriver URL (e.g., Selenium Standalone, ChromeDriver) browsers: { chrome: { desiredCapabilities: { browserName: 'chrome' } }, firefox: { desiredCapabilities: { browserName: 'firefox' } } }, // Define where test files are located sets: { desktop: { files: 'gemini/**/*.gemini.js', browsers: ['chrome', 'firefox'] } }, // Directory to save screenshots and diffs screenshotsDir: 'gemini/screens' }; /* gemini/my-component.gemini.js (test file) */ gemini.suite('MyComponent', (suite) => { suite.setUrl('/my-component') // Navigate to a specific path relative to rootUrl .setCaptureElements('.my-component-selector') // Define element(s) to capture .capture('initial-state', { // Capture a state for comparison tolerance: 2.5 // Allow some pixel difference }); }); // To run: // 1. Install gemini and selenium-standalone globally: npm install -g gemini selenium-standalone // 2. Install browser drivers: selenium-standalone install // 3. Start Selenium Server: selenium-standalone start // 4. Update reference images (first run): gemini update // 5. Run tests: gemini test

gemini --version

Debug

Known issues

breakingStarting with v7.0.0, Gemini requires Node.js version 8.0.0 or higher. Older Node.js versions are not supported and will lead to execution failures.

fix

Upgrade your Node.js environment to a version >= 8.0.0. It is recommended to use an actively maintained Node.js LTS version.

affects: >=7.0.0

breakingThe `gemini gather` command was deprecated in favor of `gemini update` in v4.0.0. Using `gather` will not work as expected and may result in errors.

fix

Replace all instances of `gemini gather` with `gemini update` to save or refresh reference images.

affects: >=4.0.0

breakingThe test execution events (`TEST_RESULT`, `UPDATE_RESULT`, `RETRY`, `ERROR`) changed their payload in v6.0.0. They now emit an object containing `path` and `size` for images, instead of just the image path string.

fix

Plugins or custom reporters interacting with these events must update their logic to access `event.image.path` and `event.image.size` instead of directly using `event.image`.

affects: >=6.0.0

gotchaGemini heavily relies on a running WebDriver server (e.g., Selenium Server, ChromeDriver). Failure to start this server before running tests will result in connection errors and tests not executing.

fix

Ensure your WebDriver server is running and accessible at the `gridUrl` specified in your `.gemini.js` configuration (default: `http://localhost:4444/wd/hub`) before executing `gemini test` or `gemini update`.

affects: *

gotchaThe project appears largely unmaintained since 2021. While functional for older tech stacks, it may lack updates for modern browser versions, WebDriver protocols, or complex frontend frameworks, potentially leading to instability or compatibility issues.

fix

Evaluate against current project needs. Consider alternatives for newer web technologies or if active maintenance is critical. If used, thoroughly test compatibility with target browsers and frameworks.

affects: *

Errors

Common errors & fixes

WebDriverError: Unable to connect to WebDriver service at http://localhost:4444/wd/hub

The Selenium WebDriver server (or ChromeDriver, etc.) is not running or is not accessible at the configured URL.

fix

Start your WebDriver server using `selenium-standalone start` or `chromedriver` before running Gemini tests. Verify the `gridUrl` in your `.gemini.js` is correct.

Error: Looks-same: Comparison failed because of different image sizes

The reference image and the captured image have different dimensions, often due to layout shifts, responsive changes, or unexpected browser behavior.

fix

Manually inspect the images to understand the cause. If the change is intended, run `gemini update` to generate new reference images. If unintended, fix the layout issue in your application.

Reference image does not exist. Run 'gemini update' to create it.

Gemini could not find a reference image for a specific test state, typically on the first run of a new test or after a reference image was deleted.

fix

Execute `gemini update` to create initial reference images based on the current UI state. Ensure that the `screenshotsDir` in your config is writable.

Upgrade

Version history

0.30.2latest on npm

Audit

Dependencies

selenium-webdriverrequiredRequired for interacting with browsers; Gemini relies on WebDriver server implementations (e.g., Selenium Server, ChromeDriver) to automate browser actions and capture screenshots.

selenium-standaloneoptionalCommonly used helper to install and start a local Selenium WebDriver server, often needed to run tests locally.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gemini-testing/gemini ↗

packagehttps://www.npmjs.com/package/gemini ↗

homepagehttps://gemini-testing.github.io ↗