Cyperful

The Capybara visual debugger

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

• 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)

🚨 Cyperful is in BETA and you will likely encounter issues/bugs! I have only confirmed it works on the default Rails 7.0 testing stack: Minitest and Capybara.

Please open a Github issue if you'd like to see support for other test frameworks (such as RSpec) or any other specific setups.

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

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

In your application_system_test_case.rb file, add the following:

CYPERFUL = !!ENV["CYPERFUL"]

require "cyperful" if CYPERFUL

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

  # ...
end

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

# 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