Skip to main content

Cucumber + Capybara

Add visual regression testing to your existing Cucumber + Capybara suite. TestivAI generates a reusable step definition — Then the "name" page looks correct — that plugs directly into your existing feature files.

Prerequisites​

  • Ruby 2.7+
  • Chrome browser
  • selenium-webdriver, capybara, and cucumber in your Gemfile
# Gemfile
gem 'selenium-webdriver'
gem 'capybara'
gem 'cucumber'
gem 'cucumber-capybara'

Then run:

bundle install

1. Install the CLI​

npm install -g @testivai/witness-cdp
note

The CLI is a Node.js tool. Node.js 18+ is required even for Ruby projects.

2. Run the Setup Wizard​

npx testivai init

Select when prompted:

? Select your language:        › Ruby
? Select your test framework:  › Cucumber + Capybara
? Where are your test files?   › features

The wizard generates three files:

FilePurpose
testivai_witness.rbTestivaiWitness module with witness method
features/step_definitions/testivai_steps.rbStep definition for the "name" page looks correct
features/visual_example.featureWorking example feature file

3. Authenticate​

npx testivai auth <your-api-key>

Get your API key from the TestivAI Dashboard.

4. Chrome Setup​

Configure Capybara to use Chrome with --remote-debugging-port=9222 in your features/support/env.rb:

require 'capybara/cucumber'
require 'selenium-webdriver'

Capybara.register_driver :chrome_cdp do |app|
  options = Selenium::WebDriver::Chrome::Options.new
  options.add_argument('--remote-debugging-port=9222')
  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

Capybara.default_driver    = :chrome_cdp
Capybara.javascript_driver = :chrome_cdp

5. Add Capture Steps​

The generated step definition registers the Then the "name" page looks correct step. Use it in any feature file:

Feature: Visual Regression

  Scenario: Homepage visual test
    Given I visit the homepage
    Then the "homepage" page looks correct

  Scenario: Login page visual test
    Given I visit the login page
    Then the "login-page" page looks correct

The generated step definition (features/step_definitions/testivai_steps.rb):

# TestivAI Step Definitions
require_relative '../../testivai_witness'
World(TestivaiWitness)

Then('the {string} page looks correct') do |name|
  witness name
end

The generated helper module (testivai_witness.rb):

# TestivAI Visual Regression Helper
module TestivaiWitness
  def witness(name)
    page.driver.browser.execute_script("return window.testivaiWitness('#{name}')")
  end
end

6. Full Working Example​

Feature file (features/visual_example.feature):

Feature: Visual Regression
  Scenario: Homepage visual test
    Given I visit the homepage
    Then the "homepage" page looks correct

Step definitions (features/step_definitions/testivai_steps.rb):

require_relative '../../testivai_witness'
World(TestivaiWitness)

Given('I visit the homepage') do
  visit '/'
end

Then('the {string} page looks correct') do |name|
  witness name
end

7. Run​

testivai run "bundle exec cucumber"

Or run a specific feature file:

testivai run "bundle exec cucumber features/visual_example.feature"

Or run by tag:

testivai run "bundle exec cucumber --tags @visual"

Tagging visual scenarios​

Tag your visual scenarios for selective runs:

Feature: Visual Regression

  @visual
  Scenario: Homepage visual test
    Given I visit the homepage
    Then the "homepage" page looks correct

CI/CD​

Add headless Chrome for CI:

options.add_argument('--remote-debugging-port=9222')
options.add_argument('--headless')
options.add_argument('--no-sandbox')
options.add_argument('--disable-dev-shm-usage')

GitHub Actions example:

- name: Set up Ruby
  uses: ruby/setup-ruby@v1
  with:
    bundler-cache: true

- name: Run visual tests
  run: testivai run "bundle exec cucumber"
  env:
    TESTIVAI_API_KEY: ${{ secrets.TESTIVAI_API_KEY }}

How it works​

The witness method calls page.driver.browser.execute_script() to invoke window.testivaiWitness(name) — the global function injected by the CDP SDK. The SDK captures a full 5-layer snapshot and uploads it for analysis.

→ See how the CDP sidecar model works