Build Status Gem Version

This project is sponsored by the software consulting firm ShakaCode, creator of the React on Rails Gem. We focus on React front-ends, often with Ruby on Rails or Gatsby. The best way to see what we do is to see the details of our recent work. Feel free to engage in discussions around this gem at our forum category for Cypress.

Gem for using in Rails and ruby rack applications with the goal of controlling State as mentioned in Cypress Best Practices

It allows to run code in the application context when executing cypress tests. Do things like:

  • use database_cleaner before each test
  • seed the database with default data for each test
  • use factory_bot to setup data
  • create scenario files used for specific tests

Has examples of setting up state with:

  • factory_bot
  • rails test fixtures
  • scenarios
  • custom commands

Video of getting started with this gem

Getting started

Add this to your Gemfile:

group :test, :development do
  gem 'cypress-on-rails', '~> 1.0'

Generate the boilerplate code using:

bin/rails g cypress_on_rails:install

# if you have/want a different cypress folder (default is spec/cypress)
bin/rails g cypress_on_rails:install --cypress_folder=test/cypress

# if you want to install cypress with npm
bin/rails g cypress_on_rails:install --install_cypress_with=npm

# to update the generated files run
bin/rails g cypress_on_rails:update

The generator modifies/adds the following files/directory in your application:

  • config/environments/test.rb
  • config/initializers/cypress_on_rails used to configure CypressDev
  • spec/cypress/integrations/ contains your cypress tests
  • spec/cypress/support/on-rails.js contains CypressDev support code
  • spec/cypress/app_commands/scenarios/ contains your CypressDev scenario definitions
  • spec/cypress/cypress_helper.rb contains helper code for CypressDev app commands

if you are not using database_cleaner look at spec/cypress/app_commands/clean.rb. if you are not using factory_bot look at spec/cypress/app_commands/factory_bot.rb.

Now you can create scenarios and commands that are plain ruby files that get loaded through middleware, the ruby sky is your limit.


WARNING!!: cypress-on-rails can execute arbitrary ruby code Please use with extra caution if starting your local server on or running the gem on a hosted server


Start the rails server in test mode and start cypress

# start rails
RAILS_ENV=test bin/rake db:create db:schema:load
bin/rails server -e test -p 5017

# in separate window start cypress
yarn cypress open --project ./spec

Example of using factory bot

You can run your factory_bot directly as well

# spec/cypress/app_commands/factory_bot.rb
require 'cypress_on_rails/smart_factory_wrapper'

  always_reload: !Rails.configuration.cache_classes,
  factory: FactoryBot,
  files: Dir['./spec/factories/**/*.rb']
// spec/cypress/integrations/simple_spec.js
describe('My First Test', function() {
  it('visit root', function() {
    // This calls to the backend to prepare the application state
      ['create_list', 'post', 10],
      ['create', 'post', {title: 'Hello World'} ]

    // Visit the application under test

    cy.contains("Hello World")

    // Accessing result
    cy.appFactories([['create', 'invoice', { paid: false }]]).then((records) => {

Example of loading rails test fixtures

# spec/cypress/app_commands/activerecord_fixtures.rb
require "active_record/fixtures"

fixtures_dir = ActiveRecord::Tasks::DatabaseTasks.fixtures_path
fixture_files = Dir["#{fixtures_dir}/**/*.yml"].map { |f| f[(fixtures_dir.size + 1)..-5] }

logger.debug "loading fixtures: { dir: #{fixtures_dir}, files: #{fixture_files} }"
ActiveRecord::FixtureSet.create_fixtures(fixtures_dir, fixture_files)
// spec/cypress/integrations/simple_spec.js
describe('My First Test', function() {
  it('visit root', function() {
    // This calls to the backend to prepare the application state

    // Visit the application under test

    cy.contains("Hello World")

Example of using scenarios

Scenarios are named before blocks that you can reference in your test.

You define a scenario in the spec/cypress/app_commands/scenarios directory:

# spec/cypress/app_commands/scenarios/basic.rb
Profile.create name: "Cypress Hill"

# or if you have factory_bot enabled in your cypress_helper
CypressOnRails::SmartFactoryWrapper.create(:profile, name: "Cypress Hill")

Then reference the scenario in your test:

// spec/cypress/integrations/scenario_example_spec.js
describe('My First Test', function() {
  it('visit root', function() {
    // This calls to the backend to prepare the application state


    cy.contains("Cypress Hill")

Example of using app commands

create a ruby file in spec/cypress/app_commands directory:

# spec/cypress/app_commands/load_seed.rb
load "#{Rails.root}/db/seeds.rb"

Then reference the command in your test with'load_seed'):

// spec/cypress/integrations/simple_spec.js
describe('My First Test', function() {
  beforeEach(() => {'load_seed') })

  it('visit root', function() {


Usage with other rack applications

Add CypressOnRails to your

# an example
require File.expand_path('my_app', File.dirname(__FILE__))

require 'cypress_on_rails/middleware'
CypressOnRails.configure do |c|
  c.cypress_folder = File.expand_path("#{__dir__}/test/cypress")
use CypressOnRails::Middleware

run MyApp

add the following file to cypress

// test/cypress/support/on-rails.js
// CypressOnRails: dont remove these command
Cypress.Commands.add('appCommands', function (body) {
    method: 'POST',
    url: "/__cypress__/command",
    body: JSON.stringify(body),
    log: true,
    failOnStatusCode: true

Cypress.Commands.add('app', function (name, command_options) {
  cy.appCommands({name: name, options: command_options})

Cypress.Commands.add('appScenario', function (name) {'scenarios/' + name)

Cypress.Commands.add('appFactories', function (options) {'factory_bot', options)
// CypressOnRails: end

// The next is optional
beforeEach(() => {'clean') // have a look at cypress/app_commands/clean.rb


  1. Fork it ([my-github-username]/cypress-on-rails/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request