Cyperful

The Capybara visual debugger

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 inBETAand you will likely encounter issues/bugs! We currently only support: Rails 7.1, Ruby 3.2.1,Minitest/RSpec,capybara,andseleniumwith 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 yourrails_helper.rbfile, add the following:

CYPERFUL=!!ENV["CYPERFUL"]

require"cyperful/rspec"ifCYPERFUL

RSpec.configuredo|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 yourapplication_system_test_case.rbfile, add the following:

CYPERFUL=!!ENV["CYPERFUL"]

require"cyperful/minitest"ifCYPERFUL

classApplicationSystemTestCase<ActionDispatch::SystemTestCase
includeCyperful::Minitest::SystemTestHelperifCYPERFUL

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

#...
end

Usage

Run a test withCYPERFULenv var, e.g.:

CYPERFUL=1 railstesttest/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 ifreload_test_filesistrue.
• history_recording(default:true) - Record a video of the test while it is running for debugging.

You can set these options on theCyperful.configobject 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
cdcyperful
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.
cdmy_test_app
CYPERFUL_DEV=1 CYPERFUL=1 railstesttest/system/my_test.rb