Add cypress-rails compatible rake tasks and server lifecycle hooks

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'