cypress-on-rails 1.18.0 → 1.19.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/)
 
@@ -143,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
@@ -506,6 +560,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.

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",