cypress-on-rails 1.17.0 → 1.19.0

data/README.md

@@ -1,4 +1,4 @@
-# CypressOnRails
+# Cypress and Playwright on Rails
 
 ![Build Status](https://github.com/shakacode/cypress-on-rails/actions/workflows/ruby.yml/badge.svg)
 [![cypress-on-rails](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/2b6cjr/master&style=plastic&logo=cypress)](https://dashboard.cypress.io/projects/2b6cjr/runs)
@@ -6,33 +6,78 @@
 
 ----
 
-This project is sponsored by the software consulting firm [ShakaCode](https://www.shakacode.com), creator of the [React on Rails Gem](https://github.com/shakacode/react_on_rails). We focus on React (with TS or ReScript) front-ends, often with Ruby on Rails or Gatsby. See [our recent work](https://www.shakacode.com/recent-work) and [client engagement model](https://www.shakacode.com/blog/client-engagement-model/). Feel free to engage in discussions around this gem at our [Slack Channel](https://join.slack.com/t/reactrails/shared_invite/enQtNjY3NTczMjczNzYxLTlmYjdiZmY3MTVlMzU2YWE0OWM0MzNiZDI0MzdkZGFiZTFkYTFkOGVjODBmOWEyYWQ3MzA2NGE1YWJjNmVlMGE) or our [forum category for Cypress](https://forum.shakacode.com/c/cypress-on-rails/55).
+This project is sponsored by the software consulting firm [ShakaCode](https://www.shakacode.com), creator of the [React on Rails Gem](https://github.com/shakacode/react_on_rails). 
 
-Interested in joining a small team that loves open source? Check our [careers page](https://www.shakacode.com/career/).
+### ShakaCode Support
 
-Need help with cypress-on-rails? Contact [ShakaCode](mailto:justin@shakacode.com).
+[ShakaCode](https://www.shakacode.com) focuses on helping Ruby on Rails teams use React and Webpack better. We can upgrade your project and improve your development and customer experiences, allowing you to focus on building new features or fixing bugs instead. 
+
+For an overview of working with us, see our [Client Engagement Model](https://www.shakacode.com/blog/client-engagement-model/) article and [how we bill for time](https://www.shakacode.com/blog/shortcut-jira-trello-github-toggl-time-and-task-tracking/).
+
+We also specialize in helping development teams lower infrastructure and CI costs. Check out our project [Control Plane Flow](https://github.com/shakacode/control-plane-flow/), which can allow you to get the ease of Heroku with the power of Kubernetes and big cost savings.
+
+If you think ShakaCode can help your project, [click here](https://meetings.hubspot.com/justingordon/30-minute-consultation) to book a call with [Justin Gordon](mailto:justin@shakacode.com), the creator of React on Rails and Shakapacker.
+
+Here's a testimonial of how ShakaCode can help from [Florian Gößler](https://github.com/FGoessler) of [Blinkist](https://www.blinkist.com/), January 2, 2023:
+> Hey Justin 👋
+>
+> I just wanted to let you know that we today shipped the webpacker to shakapacker upgrades and it all seems to be running smoothly! Thanks again for all your support and your teams work! 😍
+>
+> On top of your work, it was now also very easy for me to upgrade Tailwind and include our external node_module based web component library which we were using for our other (more modern) apps already. That work is going to be shipped later this week though as we are polishing the last bits of it. 😉
+>
+> Have a great 2023 and maybe we get to work together again later in the year! 🙌
+
+Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=date_DESC#review-2118154).
+
+---
+
+Feel free to engage in discussions around this gem at our [Slack Channel](https://join.slack.com/t/reactrails/shared_invite/enQtNjY3NTczMjczNzYxLTlmYjdiZmY3MTVlMzU2YWE0OWM0MzNiZDI0MzdkZGFiZTFkYTFkOGVjODBmOWEyYWQ3MzA2NGE1YWJjNmVlMGE) or our [forum category for Cypress](https://forum.shakacode.com/c/cypress-on-rails/55).
+
+Need help with cypress-on-rails? Contact [Justin Gordon](mailto:justin@shakacode.com).
 
 ----
 
-# Totally new to Cypress?
-Suggest you first learn the basics of Cypress before attempting to integrate with Ruby on Rails
+# New to Cypress?
+Consider first learning the basics of Cypress before attempting to integrate with Ruby on Rails.
 
 * [Good start Here](https://docs.cypress.io/examples/tutorials.html#Best-Practices)
 
 # Totally new to Playwright?
-Suggest you first learn the basics of Playwright before attempting to integrate with Ruby on Rails
+Consider first learning the basics of Playwright before attempting to integrate with Ruby on Rails.
 
 * [Good start Here](https://playwright.dev/docs/writing-tests)
 
+## Quick Start
+
+```bash
+# 1. Add to Gemfile
+gem 'cypress-on-rails', '~> 1.0'
+
+# 2. Install and generate
+bundle install
+bin/rails g cypress_on_rails:install
+
+# 3. Run tests (new rake tasks!)
+bin/rails cypress:open    # Open Cypress UI
+bin/rails cypress:run     # Run headless
+```
+
+For Playwright:
+```bash
+bin/rails g cypress_on_rails:install --framework playwright
+bin/rails playwright:open  # Open Playwright UI
+bin/rails playwright:run   # Run headless
+```
+
 ## Overview
 
-Gem for using [cypress.io](http://github.com/cypress-io/) or [playwright.dev](https://playwright.dev/) in Rails and Ruby Rack applications with the goal of controlling state as mentioned in [Cypress Best Practices](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State)
+Gem for using [cypress.io](http://github.com/cypress-io/) or [playwright.dev](https://playwright.dev/) in Rails and Ruby Rack applications to control state as mentioned in [Cypress Best Practices](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State). 
 
-It allows you to run code in the application context when executing cypress or playwright tests.
+It allows you to run code in the context of the application when executing Cypress or Playwright 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
+* use factory_bot to set up data
 * create scenario files used for specific tests
 
 Has examples of setting up state with:
@@ -41,7 +86,16 @@ Has examples of setting up state with:
 * scenarios
 * custom commands
 
-## Resources
+## Documentation
+
+### 📚 Essential Guides
+* **[Best Practices Guide](docs/BEST_PRACTICES.md)** - Recommended patterns and practices
+* **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Solutions to common issues
+* **[Playwright Guide](docs/PLAYWRIGHT_GUIDE.md)** - Complete Playwright documentation
+* **[VCR Integration Guide](docs/VCR_GUIDE.md)** - HTTP recording and mocking
+* **[DX Improvements](docs/DX_IMPROVEMENTS.md)** - Recent improvements based on user feedback
+
+### 🎥 Resources
 * [Video of getting started with this gem](https://grant-ps.blog/2018/08/10/getting-started-with-cypress-io-and-ruby-on-rails/)
 * [Article: Introduction to Cypress on Rails](https://www.shakacode.com/blog/introduction-to-cypress-on-rails/)
 
@@ -96,10 +150,11 @@ Now you can create scenarios and commands that are plain Ruby files that get loa
 
 ### Update your database.yml
 
-When writing and running tests on your local computer it's recommended to start your server in development mode so that changes you
+When writing and running tests on your local computer, it's recommended to start your server in development mode so that changes you
 make are picked up without having to restart your local server.
+
 It's recommended you update your `database.yml` to check if the `CYPRESS` environment variable is set and switch it to the test database
-otherwise cypress will keep clearing your development database.
+otherwise, cypress will keep clearing your development database.
 
 For example:
 ```yaml
@@ -119,6 +174,29 @@ Please use with extra caution if starting your local server on 0.0.0.0 or runnin
 
 Getting started on your local environment
 
+### Using Rake Tasks (Recommended)
+
+The easiest way to run tests is using the provided rake tasks, which automatically manage the Rails server:
+
+```shell
+# For Cypress
+bin/rails cypress:open  # Opens Cypress test runner UI
+bin/rails cypress:run   # Runs Cypress tests in headless mode
+
+# For Playwright
+bin/rails playwright:open  # Opens Playwright test runner UI
+bin/rails playwright:run   # Runs Playwright tests in headless mode
+```
+
+These tasks will:
+- Start the Rails test server automatically
+- Execute your tests
+- Stop the server when done
+
+### Manual Server Management
+
+You can also manage the server manually:
+
 ```shell
 # start rails
 CYPRESS=1 bin/rails server -p 5017
@@ -148,6 +226,7 @@ npx cypress run --project ./e2e
 
 You can run your [factory_bot](https://github.com/thoughtbot/factory_bot) directly as well
 
+then in Cypress
 ```js
 // spec/cypress/e2e/simple.cy.js
 describe('My First Test', () => {
@@ -171,6 +250,32 @@ describe('My First Test', () => {
   })
 })
 ```
+
+then in Playwright
+```js
+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 state
+        await appFactories([
+            ['create_list', 'post', 10],
+            ['create', 'post', { title: 'Hello World' }],
+            ['create', 'post', 'with_comments', { title: 'Factory_bot Traits here' }]
+        ]);
+
+        // Visit the application under test
+        await page.goto('/');
+        
+        await expect(page).toHaveText('Hello World');
+
+        // Accessing result
+        const records = await appFactories([['create', 'invoice', { paid: false }]]);
+        await page.goto(`/invoices/${records[0].id}`);
+    });
+});
+```
+
 You can check the [association docs](docs/factory_bot_associations.md) on more ways to setup association with the correct data.
 
 In some cases, using static Cypress fixtures may not provide sufficient flexibility when mocking HTTP response bodies. It's possible to use `FactoryBot.build` to generate Ruby hashes that can then be used as mock JSON responses:
@@ -331,16 +436,21 @@ yarn add cypress-on-rails --dev
 ### for VCR
 
 This only works when you start the Rails server with a single worker and single thread
+It can be used in two modes:
+- with separate insert/eject calls (more general, recommended way)
+- with use_cassette wrapper (supports only GraphQL integration)
 
-#### setup
+#### basic setup
 
-Add your VCR configuration to your `cypress_helper.rb`
+Add your VCR configuration to your `config/cypress_on_rails.rb`
 
 ```ruby
-require 'vcr'
-VCR.configure do |config|
-  config.hook_into :webmock
-end
+c.vcr_options = {
+  hook_into: :webmock,
+  default_cassette_options: { record: :once },
+  # It's possible to override cassette_library_dir using install_folder
+  cassette_library_dir: File.expand_path("#{__dir__}/../../spec/cypress/fixtures/vcr_cassettes")
+}
 ```
 
 Add to your `cypress/support/index.js`:
@@ -357,13 +467,16 @@ VCR.turn_off!
 WebMock.disable! if defined?(WebMock)
 ```
 
+#### insert/eject setup
+
 Add to your `config/cypress_on_rails.rb`:
 
 ```ruby
   c.use_vcr_middleware = !Rails.env.production? && ENV['CYPRESS'].present?
+  # c.use_vcr_use_cassette_middleware = !Rails.env.production? && ENV['CYPRESS'].present?
 ```
 
-#### usage
+#### insert/eject usage
 
 You have `vcr_insert_cassette` and `vcr_eject_cassette` available. https://www.rubydoc.info/github/vcr/vcr/VCR:insert_cassette
 
@@ -390,6 +503,101 @@ describe('My First Test', () => {
 })
 ```
 
+#### use_cassette setup
+
+Add to your `config/cypress_on_rails.rb`:
+
+```ruby
+  # c.use_vcr_middleware = !Rails.env.production? && ENV['CYPRESS'].present?
+  c.use_vcr_use_cassette_middleware = !Rails.env.production? && ENV['CYPRESS'].present?
+```
+
+Adjust record mode in `config/cypress_on_rails.rb` if needed:
+
+```ruby
+c.vcr_options = {
+  hook_into: :webmock,
+  default_cassette_options: { record: :once },
+} 
+```
+
+Add to your `cypress/support/command.js`:
+
+```js
+  // Add proxy-like mock to add operation name into query string
+  Cypress.Commands.add('mockGraphQL', () => {
+    cy.on('window:before:load', (win) => {
+      const originalFetch = win.fetch;
+      const fetch = (path, options, ...rest) => {
+        if (options && options.body) {
+          try {
+            const body = JSON.parse(options.body);
+            if (body.operationName) {
+              return originalFetch(`${path}?operation=${body.operationName}`, options, ...rest);
+            }
+          } catch (e) {
+            return originalFetch(path, options, ...rest);
+          }
+        }
+        return originalFetch(path, options, ...rest);
+      };
+      cy.stub(win, 'fetch', fetch);
+    });
+  });
+```
+
+Add to your `cypress/support/on-rails.js`, to `beforeEach`:
+
+```js
+  cy.mockGraphQL() // for GraphQL usage with use_cassette, see cypress/support/commands.rb
+```
+
+#### use_cassette usage
+
+There is nothing special to be called during the Cypress scenario. Each request is wrapped with `VCR.use_cassette`.
+Consider VCR configuration in `cypress_helper.rb` to ignore hosts.
+
+All cassettes will be recorded and saved automatically, using the pattern `<vcs_cassettes_path>/graphql/<operation_name>`
+
+
+## Server Hooks Configuration
+
+When using the rake tasks (`cypress:open`, `cypress:run`, `playwright:open`, `playwright:run`), you can configure lifecycle hooks to customize test server behavior:
+
+```ruby
+CypressOnRails.configure do |c|
+  # Run code before Rails server starts
+  c.before_server_start = -> { 
+    puts "Preparing test environment..."
+  }
+  
+  # Run code after Rails server is ready
+  c.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 reset
+  c.after_state_reset = -> {
+    Rails.cache.clear
+  }
+  
+  # Run code before Rails server stops
+  c.before_server_stop = -> {
+    puts "Cleaning up test environment..."
+  }
+  
+  # Configure server settings
+  c.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 rollback
+end
+```
+
 ## `before_request` configuration
 
 You may perform any custom action before running a CypressOnRails command, such as authentication, or sending metrics.  Please set `before_request` as part of the CypressOnRails configuration.
@@ -485,6 +693,46 @@ beforeEach(() => {
 });
 ```
 
+add the following file to Playwright
+```js
+// test/playwright/support/on-rails.js
+async function appCommands(body) {
+    const context = await request.newContext();
+    const response = await context.post('/__e2e__/command', {
+        data: body,
+        headers: {
+            'Content-Type': 'application/json'
+        }
+    });
+
+    if (response.status() !== 201) {
+        const responseBody = await response.text();
+        throw new Error(`Expected status 201 but got ${response.status()} - ${responseBody}`);
+    }
+
+    return response.json();
+}
+
+async function app(name, commandOptions = {}) {
+    const body = await appCommands({ name, options: commandOptions });
+    return body[0];
+}
+
+async function appScenario(name, options = {}) {
+    const body = { name: `scenarios/${name}`, options };
+    const result = await appCommands(body);
+    return result[0];
+}
+
+async function appFactories(options) {
+    return app('factory_bot', options);
+}
+
+async function clean() {
+    await app('clean');
+}
+```
+
 ## API Prefix
 
 If your Rails server is exposed under a proxy, typically https://my-local.dev/api, you can use the `api_prefix` option.
@@ -506,8 +754,8 @@ In `config/initializers/cypress_on_rails.rb`, add this line:
 
 ## Supporters
 
-<a href="https://www.jetbrains.com">
-  <img src="https://user-images.githubusercontent.com/4244251/184881139-42e4076b-024b-4b30-8c60-c3cd0e758c0a.png" alt="JetBrains" height="120px">
+<a href="https://jb.gg/OpenSource" style="margin-right: 20px;">
+  <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains" height="120px">
 </a>
 <a href="https://scoutapp.com">
   <picture>
@@ -516,7 +764,7 @@ In `config/initializers/cypress_on_rails.rb`, add this line:
     <img alt="ScoutAPM" src="https://user-images.githubusercontent.com/4244251/184881152-9f2d8fba-88ac-4ba6-873b-22387f8711c5.png" height="120px">
   </picture>
 </a>
-<a href="https://controlplane.com">
+<a href="https://shakacode.controlplane.com">
   <picture>
     <img alt="Control Plane" src="https://github.com/shakacode/.github/assets/20628911/90babd87-62c4-4de3-baa4-3d78ef4bec25" height="120px">
   </picture>

data/RELEASING.md

@@ -0,0 +1,200 @@
+# Release Process
+
+This document describes how to release a new version of cypress-playwright-on-rails.
+
+## Prerequisites
+
+1. Maintainer access to the repository
+2. RubyGems account with publish permissions for `cypress-on-rails`
+3. Clean working directory on `master` branch
+4. Development dependencies installed: `bundle install`
+   - Includes `gem-release` for gem management (like react_on_rails)
+
+## Release Command
+
+The project uses a single rake task to automate the entire release process:
+
+```bash
+rake release[VERSION,DRY_RUN]
+```
+
+### Examples
+
+```bash
+# Release version 1.19.0
+rake release[1.19.0]
+
+# Automatic patch version bump (e.g., 1.18.0 -> 1.18.1)
+rake release
+
+# Dry run to preview what would happen
+rake release[1.19.0,true]
+```
+
+### What the Release Task Does
+
+The `rake release` task will:
+
+1. Pull latest changes from master
+2. Bump the version in `lib/cypress_on_rails/version.rb`
+3. Update `Gemfile.lock` via `bundle install`
+4. Commit the version bump and Gemfile.lock changes
+5. Create a git tag (e.g., `v1.19.0`)
+6. Push the commit and tag to GitHub
+7. Build and publish the gem to RubyGems (will prompt for OTP)
+
+### Post-Release Steps
+
+After publishing, complete these manual steps:
+
+1. **Update CHANGELOG.md**
+   ```bash
+   bundle exec rake update_changelog
+   git commit -a -m 'Update CHANGELOG.md'
+   git push
+   ```
+
+2. **Create GitHub Release**
+   - Go to the releases page: https://github.com/shakacode/cypress-playwright-on-rails/releases
+   - Click on the newly created tag
+   - Copy release notes from CHANGELOG.md
+   - Publish the release
+
+3. **Announce the Release** (optional)
+   - Post in Slack channel
+   - Tweet about the release
+   - Update forum posts if needed
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (X.0.0): Breaking changes
+- **MINOR** (1.X.0): New features, backwards compatible
+- **PATCH** (1.19.X): Bug fixes, backwards compatible
+
+### Examples
+
+```bash
+# Patch release (bug fixes)
+rake release[1.18.1]
+
+# Minor release (new features)
+rake release[1.19.0]
+
+# Major release (breaking changes)
+rake release[2.0.0]
+
+# Automatic patch bump
+rake release
+```
+
+## Pre-Release Checklist
+
+Before running `rake release`:
+
+- [ ] All PRs for the release are merged
+- [ ] CI is passing on master
+- [ ] CHANGELOG.md has [Unreleased] section with all changes
+- [ ] Major changes have been tested manually
+- [ ] Documentation is up to date
+
+## Troubleshooting
+
+### "Must be on master branch" error
+
+```bash
+git checkout master
+git pull --rebase
+```
+
+### "Working directory is not clean" error
+
+```bash
+# Commit or stash your changes
+git status
+git add -A && git commit -m "Your message"
+# or
+git stash
+```
+
+
+### "Failed to push gem to RubyGems" error
+
+Ensure you're authenticated with RubyGems:
+```bash
+gem signin
+# Enter your RubyGems credentials
+```
+
+### Tag already exists
+
+If you need to re-release the same version:
+```bash
+# Delete local tag
+git tag -d v1.19.0
+
+# Delete remote tag
+git push origin :v1.19.0
+
+# Reset to before the release commit
+git reset --hard HEAD~1
+
+# Try the release again
+rake release[1.19.0]
+```
+
+## Rollback
+
+If you need to rollback a release:
+
+### Yank the gem from RubyGems
+```bash
+gem yank cypress-on-rails -v 1.19.0
+```
+
+### Delete the git tag
+```bash
+git tag -d v1.19.0
+git push origin :v1.19.0
+```
+
+### Revert the version commit
+```bash
+git revert HEAD
+git push origin master
+```
+
+## Example Release Flow
+
+```bash
+# 1. Ensure you're on master and up to date
+git checkout master
+git pull --rebase
+
+# 2. Check CI is passing
+# Visit: https://github.com/shakacode/cypress-playwright-on-rails/actions
+
+# 3. Release (will handle everything automatically)
+rake release[1.19.0]
+# Enter your RubyGems OTP when prompted
+
+# 4. Update the changelog
+bundle exec rake update_changelog
+git commit -a -m 'Update CHANGELOG.md'
+git push
+
+# 5. Create GitHub release
+open "https://github.com/shakacode/cypress-playwright-on-rails/releases"
+# Click on the new tag, add release notes from CHANGELOG.md
+
+# 6. Celebrate! 🎉
+```
+
+## Notes
+
+- The release task handles all git operations (commit, tag, push) automatically
+- Always ensure CI is green before releasing
+- The task will fail fast if working directory is not clean
+- Failed releases can be retried after fixing issues
+- Use dry run mode (`rake release[VERSION,true]`) to preview changes

data/Rakefile

@@ -1,9 +1,6 @@
-require 'bundler/gem_tasks'
-
-
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.pattern = 'spec/cypress_on_rails/*_spec.rb'
 end
 
-task default: %w[spec build]
+task default: :spec

data/cypress-on-rails.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'railties', '>= 3.2'
   s.add_development_dependency 'factory_bot', '!= 6.4.5'
   s.add_development_dependency 'vcr'
+  s.add_development_dependency 'gem-release'
   s.metadata = {
     "bug_tracker_uri"   => "https://github.com/shakacode/cypress-on-rails/issues",
     "changelog_uri"     => "https://github.com/shakacode/cypress-on-rails/blob/master/CHANGELOG.md",