gemini

library7.5.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

github ↗package ↗homepage ↗

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.

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.

const gemini = require('gemini');

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.

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

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.

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

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 footguns

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.

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.

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

9 hits · last 30 days

gptbot

ahrefsbot

script

Resources

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

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

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