Add cypress-rails compatible rake tasks and server lifecycle hooks (#179)

This PR adds comprehensive test automation support with automatic server
lifecycle management, making cypress-on-rails a drop-in replacement for
the cypress-rails gem while extending support to Playwright.

Key Improvements:

* Rake Tasks for Test Execution
  - Added cypress:open, cypress:run, playwright:open, playwright:run
  - Automatic Rails server startup/shutdown during test execution
  - Dynamic port detection to avoid conflicts
  - Support for CYPRESS_RAILS_HOST and CYPRESS_RAILS_PORT environment variables

* Server Lifecycle Hooks
  - before_server_start: Execute code before Rails server starts
  - after_server_start: Execute code when server is ready
  - after_transaction_start: Execute code after database transaction begins
  - after_state_reset: Execute code after state cleanup (runs AFTER cleanup)
  - before_server_stop: Execute code before server shutdown

* State Reset Functionality
  - Added /cypress_rails_reset_state endpoint for cypress-rails compatibility
  - Added /__cypress__/reset_state endpoint for existing users
  - Automatic database cleanup with referential integrity support
  - Uses disable_referential_integrity when available
  - Proper table name quoting with quote_table_name
  - Rails cache clearing and dependency reset

* Transactional Test Mode
  - Optional automatic database transaction rollback
  - Configurable via transactional_server option
  - Faster test execution for compatible test suites

* Security Improvements
  - Refactored shell command execution to prevent injection attacks
  - Commands passed as argument arrays instead of string interpolation
  - Uses spawn(*args) and system(*args) for safe execution
  - Added missing require 'fileutils' dependency

* Configuration & Documentation
  - New configuration initializer template with all hook examples
  - Comprehensive migration guide from manual server management
  - Migration guide from cypress-rails gem
  - Updated README with rake task usage examples

Breaking Changes:

NONE - This is purely additive functionality. All existing middleware-based
usage continues to work unchanged.

Impact on Users:

New Installations:
- Can immediately use rake tasks for automated test execution
- No need to manually manage Rails test server
- Simplified setup with single-command test execution

Existing Installations:
- No changes required - existing setup continues to work
- Can opt-in to rake tasks for improved workflow
- Can gradually adopt lifecycle hooks for custom test setup
- State reset endpoint provides backward compatibility

Migration from cypress-rails:
- Drop-in replacement with same rake task names
- Compatible state reset endpoint
- Adds Playwright support not available in cypress-rails
- More flexible with configurable hooks and options

Technical Notes:

The implementation uses TCPServer for port detection and spawns the Rails
server as a subprocess. Server readiness is verified by attempting TCP
connections. State reset uses DatabaseCleaner when available, falling back
to manual table truncation with proper referential integrity handling.

All shell commands use argument arrays to prevent command injection
vulnerabilities. Table names are properly quoted using ActiveRecord's
quote_table_name method.

Author: justin808

CHANGELOG.md

@@ -5,6 +5,81 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+### Added
+* **Rake tasks for test execution**: Added `cypress:open` and `cypress:run` rake tasks for seamless test execution, similar to cypress-rails functionality. Also added `playwright:open` and `playwright:run` tasks.
+* **Server lifecycle hooks**: Added configuration hooks for test server management:
+  - `before_server_start`: Run code before Rails server starts
+  - `after_server_start`: Run code after Rails server is ready
+  - `after_transaction_start`: Run code after database transaction begins
+  - `after_state_reset`: Run code after application state is reset
+  - `before_server_stop`: Run code before Rails server stops
+* **State reset endpoint**: Added `/cypress_rails_reset_state` and `/__cypress__/reset_state` endpoints for compatibility with cypress-rails
+* **Transactional test mode**: Added support for automatic database transaction rollback between tests
+* **Environment configuration**: Support for `CYPRESS_RAILS_HOST` and `CYPRESS_RAILS_PORT` environment variables
+* **Automatic server management**: Test server automatically starts and stops with test execution
+
+### Migration Guide
+
+#### From Manual Server Management (Old Way)
+If you were previously running tests manually:
+
+**Before (Manual Process):**
+```bash
+# Terminal 1: Start Rails server
+CYPRESS=1 bin/rails server -p 5017
+
+# Terminal 2: Run tests
+yarn cypress open --project ./e2e
+# or
+npx cypress run --project ./e2e
+```
+
+**After (Automated with Rake Tasks):**
+```bash
+# Single command - server managed automatically!
+bin/rails cypress:open
+# or
+bin/rails cypress:run
+```
+
+#### From cypress-rails Gem
+If migrating from the `cypress-rails` gem:
+
+1. Update your Gemfile:
+   ```ruby
+   # Remove
+   gem 'cypress-rails'
+   
+   # Add
+   gem 'cypress-on-rails', '~> 1.0'
+   ```
+
+2. Run bundle and generator:
+   ```bash
+   bundle install
+   rails g cypress_on_rails:install
+   ```
+
+3. Configure hooks in `config/initializers/cypress_on_rails.rb` (optional):
+   ```ruby
+   CypressOnRails.configure do |c|
+     # These hooks match cypress-rails functionality
+     c.before_server_start = -> { DatabaseCleaner.clean }
+     c.after_server_start = -> { Rails.application.load_seed }
+     c.transactional_server = true
+   end
+   ```
+
+4. Use the same commands you're familiar with:
+   ```bash
+   bin/rails cypress:open
+   bin/rails cypress:run
+   ```
+
+---
+
 ## [1.18.0] — 2025-08-27
 [Compare]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.17.0...v1.18.0
 

README.md

@@ -143,6 +143,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 +529,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.

lib/cypress_on_rails/configuration.rb

@@ -10,6 +10,18 @@ class Configuration
     attr_accessor :before_request
     attr_accessor :logger
     attr_accessor :vcr_options
+    
+    # Server hooks for managing test lifecycle
+    attr_accessor :before_server_start
+    attr_accessor :after_server_start
+    attr_accessor :after_transaction_start
+    attr_accessor :after_state_reset
+    attr_accessor :before_server_stop
+    
+    # Server configuration
+    attr_accessor :server_host
+    attr_accessor :server_port
+    attr_accessor :transactional_server
 
     # Attributes for backwards compatibility
     def cypress_folder
@@ -38,6 +50,18 @@ def reset
       self.before_request = -> (request) {}
       self.logger = Logger.new(STDOUT)
       self.vcr_options = {}
+      
+      # Server hooks
+      self.before_server_start = nil
+      self.after_server_start = nil
+      self.after_transaction_start = nil
+      self.after_state_reset = nil
+      self.before_server_stop = nil
+      
+      # Server configuration
+      self.server_host = ENV.fetch('CYPRESS_RAILS_HOST', 'localhost')
+      self.server_port = ENV.fetch('CYPRESS_RAILS_PORT', nil)
+      self.transactional_server = true
     end
 
     def tagged_logged

lib/cypress_on_rails/railtie.rb

@@ -3,10 +3,17 @@
 
 module CypressOnRails
   class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'tasks/cypress.rake'
+    end
     initializer :setup_cypress_middleware, after: :load_config_initializers do |app|
       if CypressOnRails.configuration.use_middleware?
         require 'cypress_on_rails/middleware'
         app.middleware.use Middleware
+        
+        # Add state reset middleware for compatibility with cypress-rails
+        require 'cypress_on_rails/state_reset_middleware'
+        app.middleware.use StateResetMiddleware
       end
       if CypressOnRails.configuration.use_vcr_middleware?
         require 'cypress_on_rails/vcr/insert_eject_middleware'