cypress-on-rails 1.18.0 → 1.20.0

data/README.md

@@ -47,6 +47,28 @@ Consider first learning the basics of Playwright before attempting to integrate
 
 * [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 to control state as mentioned in [Cypress Best Practices](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State). 
@@ -64,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/)
 
@@ -103,17 +134,52 @@ bin/rails g cypress_on_rails:install --install_with=skip
 bin/rails g cypress_on_rails:install --install_with=skip
 ```
 
-The generator modifies/adds the following files/directory in your application:
-* `config/initializers/cypress_on_rails.rb` used to configure Cypress on Rails
-* `e2e/cypress/integration/` contains your cypress tests
-* `e2e/cypress/support/on-rails.js` contains Cypress on Rails support code
-* `e2e/cypress/e2e_helper.rb` contains helper code to require libraries like factory_bot
-* `e2e/cypress/app_commands/` contains your scenario definitions
-* `e2e/playwright/e2e/` contains your playwright tests
-* `e2e/playwright/support/on-rails.js` contains Playwright on Rails support code
+The generator creates the following structure in your application:
+
+**For Cypress:**
+```
+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
+```
+
+**For Playwright:**
+```
+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
+```
+
+**Additional files:**
+* `config/initializers/cypress_on_rails.rb` - Configuration for Cypress on Rails
+
+**Important:** Note that `e2e_helper.rb` and `app_commands/` are at the root of the install folder (e.g., `e2e/`), NOT inside the framework subdirectory (e.g., `e2e/cypress/`). This allows both Cypress and Playwright to share the same commands and helpers when using both frameworks.
 
-If you are not using `database_cleaner` look at `e2e/cypress/app_commands/clean.rb`.
-If you are not using `factory_bot` look at `e2e/cypress/app_commands/factory_bot.rb`.
+If you are not using `database_cleaner` look at `e2e/app_commands/clean.rb`.
+If you are not using `factory_bot` look at `e2e/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.
 
@@ -143,6 +209,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
@@ -394,8 +483,7 @@ Add your VCR configuration to your `config/cypress_on_rails.rb`
 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")
+  cassette_library_dir: File.expand_path("#{__dir__}/../../e2e/fixtures/vcr_cassettes")
 }
 ```
 
@@ -506,6 +594,44 @@ 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.
@@ -685,15 +811,9 @@ In `config/initializers/cypress_on_rails.rb`, add this line:
     <img alt="BrowserStack" src="https://user-images.githubusercontent.com/4244251/184881129-e1edf4b7-3ae1-4ea8-9e6d-3595cf01609e.png" height="55px">
   </picture>
 </a>
-<a href="https://railsautoscale.com">
-  <img src="https://user-images.githubusercontent.com/4244251/184881144-95c2c25c-9879-4069-864d-4e67d6ed39d2.png" alt="Rails Autoscale" height="55px">
-</a>
 <a href="https://www.honeybadger.io">
   <img src="https://user-images.githubusercontent.com/4244251/184881133-79ee9c3c-8165-4852-958e-31687b9536f4.png" alt="Honeybadger" height="55px">
 </a>
-<a href="https://reviewable.io">
-  <img src="https://user-images.githubusercontent.com/20628911/230848305-c94510a4-82d7-468f-bf9f-eeb81d3f2ce0.png" alt="Reviewable" height="55px">
-</a>
 
 <br />
 <br />

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

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.author      = ["miceportal team", 'Grant Petersen-Speelman']
   s.email       = ["info@miceportal.de", 'grantspeelman@gmail.com']
   s.homepage    = "http://github.com/shakacode/cypress-on-rails"
-  s.summary     = "Integrates cypress with rails or rack applications"
-  s.description = "Integrates cypress with rails or rack applications"
+  s.summary     = "Integrates Cypress and Playwright with Rails or Rack applications"
+  s.description = "Integrates Cypress and Playwright with Rails or Rack applications"
   s.post_install_message = 'The CypressDev constant is being deprecated and will be completely removed and replaced with CypressOnRails.'
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {spec}/*`.split("\n")
@@ -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",