Gemini UI Screenshot Testing

Common errors

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

  cause 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

  cause 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.

  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.
  fix Execute `gemini update` to create initial reference images based on the current UI state. Ensure that the `screenshotsDir` in your config is writable.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js environment to a version >= 8.0.0. It is recommended to use an actively maintained Node.js LTS version.
• breaking 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.
  Fix: Replace all instances of `gemini gather` with `gemini update` to save or refresh reference images.
• breaking 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.
  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`.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• npm install gemini npm
• yarn add gemini yarn
• pnpm add gemini pnpm

Imports

• gemini
  wrong:

  import gemini from 'gemini';

  correct:

  const gemini = require('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
  wrong:

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

  correct:

  module.exports = { /* ... */ }; // 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.

Quickstart

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