Project

cyperful

0.1
The project is in a healthy, maintained state
Interactive test debugger for Capybara tests
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

Cyperful

The Capybara visual debugger

Gem Version

An addon for Ruby Capybara system tests that adds the great DX of tools like Cypress.io.

cyperful-demo.mp4

Features

  • View the list of steps in a test, with live updates as the test runs
  • Pause the test at each step and interact with the page
  • View API requests and console logs between steps
  • Auto-restart the test when the source code is modified
  • Records a video of the test so you can preview the finished test at that point in time (experimental)
  • View and run ANY test suite from the UI (coming soon)
  • Record browser interactions to save as ruby code (coming later)

Framework support

🚨 Cyperful is in BETA and you will likely encounter issues/bugs! We currently only support: Rails 7.1, Ruby 3.2.1, Minitest/RSpec, capybara, and selenium with Chrome.

Try it out, then please open a Github issue if you'd like to see support for any other specific frameworks/setups.

Installation

First, install the gem (with require=false):

group :test do
  gem "cyperful", require: false
end

Follow the instructions for your test framework:

RSpec

In your rails_helper.rb file, add the following:

CYPERFUL = !!ENV["CYPERFUL"]

require "cyperful/rspec" if CYPERFUL

RSpec.configure do |config|
  # make sure we setup the browser-driver BEFORE Cyperful's setup
  config.prepend_before(:example, type: :system) do
    # Cyperful only supports Selenium + Chrome
    driven_by :selenium, using: :chrome, screen_size: [1400, 1400]
  end

  # ...
end

Minitest

In your application_system_test_case.rb file, add the following:

CYPERFUL = !!ENV["CYPERFUL"]

require "cyperful/minitest" if CYPERFUL

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  include Cyperful::Minitest::SystemTestHelper if CYPERFUL

  # Cyperful only supports Selenium + Chrome
  driven_by :selenium, using: :chrome, screen_size: [1400, 1400]

  # ...
end

Usage

Run a test with CYPERFUL env var, e.g.:

CYPERFUL=1 rails test test/system/my_test.rb:123

🚨 IMPORTANT NOTE: Cyperful currently works best when you run a single test at a time i.e. your test file contains only 1 test OR you specify a single test with <filename>:<line_number>. A better DX for running multiple sequential tests is coming soon.

Config

Config options:

  • reload_test_files (default: true) - Reset the test when the test's source code is modified.
  • auto_run_on_reload (default: true) - Automatically start the test when the source code is modified. Only applies if reload_test_files is true.
  • history_recording (default: true) - Record a video of the test while it is running for debugging.

You can set these options on the Cyperful.config object after requiring the gem, e.g.:

Cyperful.config.history_recording = false

Development

# in a terminal, run the frontend dev server.
# this will watch for changes and rebuild the frontend
cd cyperful
pnpm run dev

# in another terminal, run any test.
# prepend `CYPERFUL_DEV=1` to tell cyperful to look at the
# dev server instead of the prebuilt frontend assets.
cd my_test_app
CYPERFUL_DEV=1 CYPERFUL=1 rails test test/system/my_test.rb