{"id":10932,"library":"gemini","title":"Gemini UI Screenshot Testing","description":"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.","status":"abandoned","version":"7.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/gemini-testing/gemini","tags":["javascript","test","testing","screenshot","selenium","layout"],"install":[{"cmd":"npm install gemini","lang":"bash","label":"npm"},{"cmd":"yarn add gemini","lang":"bash","label":"yarn"},{"cmd":"pnpm add gemini","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with browsers; Gemini relies on WebDriver server implementations (e.g., Selenium Server, ChromeDriver) to automate browser actions and capture screenshots.","package":"selenium-webdriver","optional":false},{"reason":"Commonly used helper to install and start a local Selenium WebDriver server, often needed to run tests locally.","package":"selenium-standalone","optional":true}],"imports":[{"note":"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.","wrong":"import gemini from 'gemini';","symbol":"gemini","correct":"const gemini = require('gemini');"},{"note":"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.","symbol":"suite","correct":"gemini.suite('my-suite', (suite) => { /* ... */ });"},{"note":"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.","wrong":"export default { /* ... */ }; // in .gemini.js","symbol":"config","correct":"module.exports = { /* ... */ }; // in .gemini.js"}],"quickstart":{"code":"/* .gemini.js (config file in project root) */\nmodule.exports = {\n  rootUrl: 'http://localhost:3000/', // Your application's base URL\n  gridUrl: 'http://127.0.0.1:4444/wd/hub', // WebDriver URL (e.g., Selenium Standalone, ChromeDriver)\n  browsers: {\n    chrome: {\n      desiredCapabilities: { browserName: 'chrome' }\n    },\n    firefox: {\n      desiredCapabilities: { browserName: 'firefox' }\n    }\n  },\n  // Define where test files are located\n  sets: {\n    desktop: {\n      files: 'gemini/**/*.gemini.js',\n      browsers: ['chrome', 'firefox']\n    }\n  },\n  // Directory to save screenshots and diffs\n  screenshotsDir: 'gemini/screens'\n};\n\n/* gemini/my-component.gemini.js (test file) */\ngemini.suite('MyComponent', (suite) => {\n  suite.setUrl('/my-component') // Navigate to a specific path relative to rootUrl\n    .setCaptureElements('.my-component-selector') // Define element(s) to capture\n    .capture('initial-state', { // Capture a state for comparison\n      tolerance: 2.5 // Allow some pixel difference\n    });\n});\n\n// To run:\n// 1. Install gemini and selenium-standalone globally: npm install -g gemini selenium-standalone\n// 2. Install browser drivers: selenium-standalone install\n// 3. Start Selenium Server: selenium-standalone start\n// 4. Update reference images (first run): gemini update\n// 5. Run tests: gemini test","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to a version >= 8.0.0. It is recommended to use an actively maintained Node.js LTS version.","message":"Starting 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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Replace all instances of `gemini gather` with `gemini update` to save or refresh reference images.","message":"The `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.","severity":"breaking","affected_versions":">=4.0.0"},{"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`.","message":"The 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.","severity":"breaking","affected_versions":">=6.0.0"},{"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`.","message":"Gemini 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Start your WebDriver server using `selenium-standalone start` or `chromedriver` before running Gemini tests. Verify the `gridUrl` in your `.gemini.js` is correct.","cause":"The Selenium WebDriver server (or ChromeDriver, etc.) is not running or is not accessible at the configured URL.","error":"WebDriverError: Unable to connect to WebDriver service at http://localhost:4444/wd/hub"},{"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.","cause":"The reference image and the captured image have different dimensions, often due to layout shifts, responsive changes, or unexpected browser behavior.","error":"Error: Looks-same: Comparison failed because of different image sizes"},{"fix":"Execute `gemini update` to create initial reference images based on the current UI state. Ensure that the `screenshotsDir` in your config is writable.","cause":"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.","error":"Reference image does not exist. Run 'gemini update' to create it."}],"ecosystem":"npm"}