ShakaCode Support

New to Cypress?

Totally new to Playwright?

Quick Start

# 1. Add to Gemfilegem'cypress-on-rails','~> 1.0'# 2. Install and generatebundle installbin/rails g cypress_on_rails:install# 3. Run tests (new rake tasks!)bin/rails cypress:open# Open Cypress UIbin/rails cypress:run# Run headless

bin/rails g cypress_on_rails:install --framework playwrightbin/rails playwright:open# Open Playwright UIbin/rails playwright:run# Run headless

Overview

Documentation

📚 Essential Guides

🎥 Resources

Installation

group:test,:developmentdogem'cypress-on-rails','~> 1.0'end

# by default installs only cypressbin/rails g cypress_on_rails:install# if you have/want a different cypress folder (default is e2e)bin/rails g cypress_on_rails:install --install_folder=spec/cypress# to install playwright instead of cypressbin/rails g cypress_on_rails:install --framework playwright# if you target the Rails server with a path prefix to your URLbin/rails g cypress_on_rails:install --api_prefix=/api# if you want to install with npm insteadbin/rails g cypress_on_rails:install --install_with=npm# if you already have cypress installed globallybin/rails g cypress_on_rails:install --install_with=skip# to update the generated files runbin/rails g cypress_on_rails:install --install_with=skip

e2e/  cypress.config.js              # Cypress configuration  e2e_helper.rb                  # Helper code for factory_bot, database_cleaner, etc.  app_commands/                  # Your custom commands and scenarios    clean.rb    factory_bot.rb    scenarios/      basic.rb  fixtures/    vcr_cassettes/               # VCR recordings (if using VCR)  cypress/    support/      index.js      commands.js      on-rails.js                # Cypress on Rails support code    e2e/      rails_examples/            # Example tests

e2e/  playwright.config.js           # Playwright configuration  e2e_helper.rb                  # Helper code for factory_bot, database_cleaner, etc.  app_commands/                  # Your custom commands and scenarios (shared with Cypress)  fixtures/    vcr_cassettes/               # VCR recordings (if using VCR)  playwright/    support/      index.js      on-rails.js                # Playwright on Rails support code    e2e/      rails_examples/            # Example tests

Update your database.yml

development:<<:*defaultdatabase:<%= ENV['CYPRESS'] ? 'my_db_test' : 'my_db_development' %>test:<<:*defaultdatabase:my_db_test

WARNING

Usage

Using Rake Tasks (Recommended)

# For Cypressbin/rails cypress:open# Opens Cypress test runner UIbin/rails cypress:run# Runs Cypress tests in headless mode# For Playwrightbin/rails playwright:open# Opens Playwright test runner UIbin/rails playwright:run# Runs Playwright tests in headless mode

Manual Server Management

# start railsCYPRESS=1 bin/rails server -p 5017# in separate window start cypressyarn cypress open --project ./e2e# or for npmnpx cypress open --project ./e2e# or for playwrightyarn playwrighttest --ui# or using npmnpx playwrighttest --ui

# setup rails and start server in background# ...yarn run cypress run --project ./e2e# or for npmnpx cypress run --project ./e2e

Example of using factory bot

// spec/cypress/e2e/simple.cy.jsdescribe('My First Test',()=>{it('visit root',()=>{// This calls to the backend to prepare the application statecy.appFactories([['create_list','post',10],['create','post',{title:'Hello World'}],['create','post','with_comments',{title:'Factory_bot Traits here'}]// use traits])// Visit the application under testcy.visit('/')cy.contains('Hello World')// Accessing resultcy.appFactories([['create','invoice',{paid:false}]]).then((records)=>{cy.visit(`/invoices/${records[0].id}`);});})})

const{ test, expect, request}=require('@playwright/test');test.describe('My First Test',()=>{test('visit root',async({ page})=>{// This calls to the backend to prepare the application stateawaitappFactories([['create_list','post',10],['create','post',{title:'Hello World'}],['create','post','with_comments',{title:'Factory_bot Traits here'}]]);// Visit the application under testawaitpage.goto('/');awaitexpect(page).toHaveText('Hello World');// Accessing resultconstrecords=awaitappFactories([['create','invoice',{paid:false}]]);awaitpage.goto(`/invoices/${records[0].id}`);});});

FactoryBot.definedofactory:some_web_response,class:Hashdoinitialize_with{attributes.deep_stringify_keys}id{123}name{'Mr Blobby'}occupation{'Evil pink clown'}endendFactoryBot.build(:some_web_response=>{'id'=>123,'name'=>'Mr Blobby','occupation'=>'Evil pink clown'})

describe('My First Test',()=>{it('visit root',()=>{// This calls to the backend to generate the mocked responsecy.appFactories([['build','some_web_response',{name:'Baby Blobby'}]]).then(([responseBody])=>{cy.intercept('http://some-external-url.com/endpoint',{body:responseBody});// Visit the application under testcy.visit('/')})cy.contains('Hello World')})})

Example of loading Rails test fixtures

# spec/e2e/app_commands/activerecord_fixtures.rbrequire"active_record/fixtures"fixtures_dir=ActiveRecord::Tasks::DatabaseTasks.fixtures_pathfixture_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.reset_cacheActiveRecord::FixtureSet.create_fixtures(fixtures_dir,fixture_files)

// spec/cypress/e2e/simple.cy.jsdescribe('My First Test',()=>{it('visit root',()=>{// This calls to the backend to prepare the application statecy.appFixtures()// Visit the application under testcy.visit('/')cy.contains('Hello World')})})

Example of using scenarios

# spec/cypress/app_commands/scenarios/basic.rbProfile.createname:"Cypress Hill"# or if you have factory_bot enabled in your cypress_helperCypressOnRails::SmartFactoryWrapper.create(:profile,name:"Cypress Hill")

// spec/cypress/e2e/scenario_example.cy.jsdescribe('My First Test',()=>{it('visit root',()=>{// This calls to the backend to prepare the application statecy.appScenario('basic')cy.visit('/profiles')cy.contains('Cypress Hill')})})

Example of using app commands

# spec/e2e/app_commands/load_seed.rbload"#{Rails.root}/db/seeds.rb"

// spec/cypress/e2e/simple.cy.jsdescribe('My First Test',()=>{beforeEach(()=>{cy.app('load_seed')})it('visit root',()=>{cy.visit('/')cy.contains("Seeds")})})

Example of using scenario with Playwright

# spec/e2e/app_commands/scenarios/basic.rbProfile.createname:"Cypress Hill"# or if you have factory_bot enabled in your cypress_helperCypressOnRails::SmartFactoryWrapper.create(:profile,name:"Cypress Hill")

// spec/playwright/e2e/scenario_example.spec.jsimport{test,expect}from"@playwright/test";import{app,appScenario}from'../../support/on-rails';test.describe("Rails using scenarios examples",()=>{test.beforeEach(async({ page})=>{awaitapp('clean');});test("setup basic scenario",async({ page})=>{awaitappScenario('basic');awaitpage.goto("/");});});

Experimental Features (matching npm package)

yarn add cypress-on-rails --dev

for VCR

basic setup

c.vcr_options={hook_into::webmock,default_cassette_options:{record::once},cassette_library_dir:File.expand_path("#{__dir__}/../../e2e/fixtures/vcr_cassettes")}

import'cypress-on-rails/support/index'

VCR.eject_cassette# make sure we no cassettes inserted before the next test startsVCR.turn_off!WebMock.disable!ifdefined?(WebMock)

insert/eject setup

c.use_vcr_middleware= !Rails.env.production? &&ENV['CYPRESS'].present?# c.use_vcr_use_cassette_middleware = !Rails.env.production? && ENV['CYPRESS'].present?

insert/eject usage

describe('My First Test',()=>{beforeEach(()=>{cy.app('load_seed')})it('visit root',()=>{cy.app('clean')// have a look at e2e/app_commands/clean.rbcy.vcr_insert_cassette('cats',{record:"new_episodes"})cy.visit('/using_vcr/index')cy.get('a').contains('Cats').click()cy.contains('Wikipedia has a recording of a cat meowing, because why not?')cy.vcr_eject_cassette()cy.vcr_insert_cassette('cats')cy.visit('/using_vcr/record_cats')cy.contains('Wikipedia has a recording of a cat meowing, because why not?')})})

use_cassette setup

# c.use_vcr_middleware = !Rails.env.production? && ENV['CYPRESS'].present?c.use_vcr_use_cassette_middleware= !Rails.env.production? &&ENV['CYPRESS'].present?

c.vcr_options={hook_into::webmock,default_cassette_options:{record::once},}

// Add proxy-like mock to add operation name into query stringCypress.Commands.add('mockGraphQL',()=>{cy.on('window:before:load',(win)=>{constoriginalFetch=win.fetch;constfetch=(path,options, ...rest)=>{if(options&&options.body){try{constbody=JSON.parse(options.body);if(body.operationName){returnoriginalFetch(`${path}?operation=${body.operationName}`,options, ...rest);}}catch(e){returnoriginalFetch(path,options, ...rest);}}returnoriginalFetch(path,options, ...rest);};cy.stub(win,'fetch',fetch);});});

cy.mockGraphQL()// for GraphQL usage with use_cassette, see cypress/support/commands.rb

use_cassette usage

Server Hooks Configuration

CypressOnRails.configuredo |c|# Run code before Rails server startsc.before_server_start=->{puts"Preparing test environment..."}# Run code after Rails server is readyc.after_server_start=->{puts"Server is ready for testing!"}# Run code after database transaction begins (transactional mode only)c.after_transaction_start=->{# Load seed data that should be rolled back after tests}# Run code after application state is resetc.after_state_reset=->{Rails.cache.clear}# Run code before Rails server stopsc.before_server_stop=->{puts"Cleaning up test environment..."}# Configure server settingsc.server_host='localhost'# or use ENV['CYPRESS_RAILS_HOST']c.server_port=3001# or use ENV['CYPRESS_RAILS_PORT']c.transactional_server=true# Enable automatic transaction rollbackend

before_request configuration

Authenticate CypressOnRails

CypressOnRails.configuredo |c|# ...# Refer to https://www.rubydoc.info/gems/rack/Rack/Request for the `request` argument.c.before_request=lambda{ |request|body=JSON.parse(request.body.string)ifbody['cypress_token'] !=ENV.fetch('SWEEP_CYPRESS_SECRET_TOKEN')# You may also use warden for authentication:#   if !request.env['warden'].authenticate(:secret_key)return[401,{},['unauthorized']]end}end

Send usage metrics

CypressOnRails.configuredo |c|# ...# Refer to https://www.rubydoc.info/gems/rack/Rack/Request for the `request` argument.c.before_request=lambda{ |request|statsd=Datadog::Statsd.new('localhost',8125)statsd.increment('cypress_on_rails.requests')}end

Usage with other rack applications

# an example config.rurequireFile.expand_path('my_app',File.dirname(__FILE__))require'cypress_on_rails/middleware'CypressOnRails.configuredo |c|c.cypress_folder=File.expand_path("#{__dir__}/test/cypress")enduseCypressOnRails::MiddlewarerunMyApp

// test/cypress/support/on-rails.js// CypressOnRails: don't remove these commandsCypress.Commands.add('appCommands',(body)=>{cy.request({method:'POST',url:'/__cypress__/command',body:JSON.stringify(body),headers:{'Content-Type':'application/json; charset=utf-8',},log:true,failOnStatusCode:true})});Cypress.Commands.add('app',(name,command_options)=>{cy.appCommands({name:name,options:command_options})});Cypress.Commands.add('appScenario',(name)=>{cy.app('scenarios/'+name)});Cypress.Commands.add('appFactories',(options)=>{cy.app('factory_bot',options)});// CypressOnRails: end// The next is optionalbeforeEach(()=>{cy.app('clean')// have a look at cypress/app_commands/clean.rb});

// test/playwright/support/on-rails.jsasyncfunctionappCommands(body){constcontext=awaitrequest.newContext();constresponse=awaitcontext.post('/__e2e__/command',{data:body,headers:{'Content-Type':'application/json'}});if(response.status()!==201){constresponseBody=awaitresponse.text();thrownewError(`Expected status 201 but got${response.status()} -${responseBody}`);}returnresponse.json();}asyncfunctionapp(name,commandOptions={}){constbody=awaitappCommands({ name,options:commandOptions});returnbody[0];}asyncfunctionappScenario(name,options={}){constbody={name:`scenarios/${name}`, options};constresult=awaitappCommands(body);returnresult[0];}asyncfunctionappFactories(options){returnapp('factory_bot',options);}asyncfunctionclean(){awaitapp('clean');}

API Prefix

CypressOnRails.configuredo |c|# ...c.api_prefix='/api'end

Contributing

Supporters