The Capybara visual debugger
An addon for Ruby Capybara system tests that adds the great DX of tools like Cypress.io.
cyperful-demo.mp4
- 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 inBETAand you will likely encounter issues/bugs! We currently only support: Rails 7.1, Ruby 3.2.1,Minitest
/RSpec
,capybara
,andselenium
with Chrome.
Try it out, then please open a Github issue if you'd like to see support for any other specific frameworks/setups.
First, install the gem (with require=false):
group:test do
gem "cyperful", require: false
end
Follow the instructions for your test framework:
In yourrails_helper.rb
file, 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
In yourapplication_system_test_case.rb
file, 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
Run a test withCYPERFUL
env 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 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_files
istrue
.history_recording
(default:true
) - Record a video of the test while it is running for debugging.
You can set these options on theCyperful.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
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