Add cypress-rails compatible rake tasks and server lifecycle hooks

This enhancement brings cypress-rails functionality to cypress-playwright-on-rails:

- Added rake tasks for cypress:open, cypress:run, playwright:open, playwright:run
- Implemented automatic Rails server management with dynamic port selection
- Added server lifecycle hooks (before_server_start, after_server_start, etc.)
- Added transactional test mode for automatic database rollback
- Added state reset middleware for /cypress_rails_reset_state endpoint
- Support for CYPRESS_RAILS_HOST and CYPRESS_RAILS_PORT environment variables

These changes make cypress-playwright-on-rails a more complete replacement for
cypress-rails, providing the same developer-friendly test execution experience
while maintaining all the existing cypress-on-rails functionality.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

CHANGELOG.md

@@ -5,6 +5,23 @@ 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
+
+---
+
 ## [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'

lib/cypress_on_rails/server.rb

@@ -0,0 +1,196 @@
+require 'socket'
+require 'timeout'
+require 'cypress_on_rails/configuration'
+
+module CypressOnRails
+  class Server
+    attr_reader :host, :port, :framework, :install_folder
+
+    def initialize(options = {})
+      config = CypressOnRails.configuration
+      
+      @framework = options[:framework] || :cypress
+      @host = options[:host] || config.server_host
+      @port = options[:port] || config.server_port || find_available_port
+      @port = @port.to_i if @port
+      @install_folder = options[:install_folder] || config.install_folder || detect_install_folder
+      @transactional = options.fetch(:transactional, config.transactional_server)
+    end
+
+    def open
+      start_server do
+        run_command(open_command, "Opening #{framework} test runner")
+      end
+    end
+
+    def run
+      start_server do
+        result = run_command(run_command_str, "Running #{framework} tests")
+        exit(result ? 0 : 1)
+      end
+    end
+
+    def init
+      ensure_install_folder_exists
+      puts "#{framework.to_s.capitalize} configuration initialized at #{install_folder}"
+    end
+
+    private
+
+    def detect_install_folder
+      # Check common locations for cypress/playwright installation
+      possible_folders = ['e2e', 'spec/e2e', 'spec/cypress', 'spec/playwright', 'cypress', 'playwright']
+      folder = possible_folders.find { |f| File.exist?(f) }
+      folder || 'e2e'
+    end
+
+    def ensure_install_folder_exists
+      unless File.exist?(install_folder)
+        puts "Creating #{install_folder} directory..."
+        FileUtils.mkdir_p(install_folder)
+      end
+    end
+
+    def find_available_port
+      server = TCPServer.new('127.0.0.1', 0)
+      port = server.addr[1]
+      server.close
+      port
+    end
+
+    def start_server(&block)
+      config = CypressOnRails.configuration
+      
+      run_hook(config.before_server_start)
+      
+      ENV['CYPRESS'] = '1'
+      ENV['RAILS_ENV'] = 'test'
+      
+      server_pid = spawn_server
+      
+      begin
+        wait_for_server
+        run_hook(config.after_server_start)
+        
+        puts "Rails server started on #{base_url}"
+        
+        if @transactional && defined?(ActiveRecord::Base)
+          ActiveRecord::Base.connection.begin_transaction(joinable: false)
+          run_hook(config.after_transaction_start)
+        end
+        
+        yield
+        
+      ensure
+        run_hook(config.before_server_stop)
+        
+        if @transactional && defined?(ActiveRecord::Base)
+          ActiveRecord::Base.connection.rollback_transaction if ActiveRecord::Base.connection.transaction_open?
+        end
+        
+        stop_server(server_pid)
+        ENV.delete('CYPRESS')
+      end
+    end
+
+    def spawn_server
+      rails_command = if File.exist?('bin/rails')
+        'bin/rails'
+      else
+        'bundle exec rails'
+      end
+
+      server_command = "#{rails_command} server -p #{port} -b #{host}"
+      
+      puts "Starting Rails server: #{server_command}"
+      
+      spawn(server_command, out: $stdout, err: $stderr)
+    end
+
+    def wait_for_server(timeout = 30)
+      Timeout.timeout(timeout) do
+        loop do
+          begin
+            TCPSocket.new(host, port).close
+            break
+          rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+            sleep 0.1
+          end
+        end
+      end
+    rescue Timeout::Error
+      raise "Rails server failed to start on #{host}:#{port} after #{timeout} seconds"
+    end
+
+    def stop_server(pid)
+      if pid
+        puts "Stopping Rails server (PID: #{pid})"
+        Process.kill('TERM', pid)
+        Process.wait(pid)
+      end
+    rescue Errno::ESRCH
+      # Process already terminated
+    end
+
+    def base_url
+      "http://#{host}:#{port}"
+    end
+
+    def open_command
+      case framework
+      when :cypress
+        if command_exists?('yarn')
+          "yarn cypress open --project #{install_folder} --config baseUrl=#{base_url}"
+        elsif command_exists?('npx')
+          "npx cypress open --project #{install_folder} --config baseUrl=#{base_url}"
+        else
+          "cypress open --project #{install_folder} --config baseUrl=#{base_url}"
+        end
+      when :playwright
+        if command_exists?('yarn')
+          "yarn playwright test --ui"
+        elsif command_exists?('npx')
+          "npx playwright test --ui"
+        else
+          "playwright test --ui"
+        end
+      end
+    end
+
+    def run_command_str
+      case framework
+      when :cypress
+        if command_exists?('yarn')
+          "yarn cypress run --project #{install_folder} --config baseUrl=#{base_url}"
+        elsif command_exists?('npx')
+          "npx cypress run --project #{install_folder} --config baseUrl=#{base_url}"
+        else
+          "cypress run --project #{install_folder} --config baseUrl=#{base_url}"
+        end
+      when :playwright
+        if command_exists?('yarn')
+          "yarn playwright test"
+        elsif command_exists?('npx')
+          "npx playwright test"
+        else
+          "playwright test"
+        end
+      end
+    end
+
+    def run_command(command, description)
+      puts "#{description}: #{command}"
+      system(command)
+    end
+
+    def command_exists?(command)
+      system("which #{command} > /dev/null 2>&1")
+    end
+
+    def run_hook(hook)
+      if hook && hook.respond_to?(:call)
+        hook.call
+      end
+    end
+  end
+end

lib/cypress_on_rails/state_reset_middleware.rb

@@ -0,0 +1,45 @@
+module CypressOnRails
+  class StateResetMiddleware
+    def initialize(app)
+      @app = app
+    end
+    
+    def call(env)
+      if env['PATH_INFO'] == '/__cypress__/reset_state' || env['PATH_INFO'] == '/cypress_rails_reset_state'
+        reset_application_state
+        [200, { 'Content-Type' => 'text/plain' }, ['State reset completed']]
+      else
+        @app.call(env)
+      end
+    end
+    
+    private
+    
+    def reset_application_state
+      config = CypressOnRails.configuration
+      
+      # Run after_state_reset hook if configured
+      run_hook(config.after_state_reset)
+      
+      # Default state reset actions
+      if defined?(DatabaseCleaner)
+        DatabaseCleaner.clean_with(:truncation)
+      elsif defined?(ActiveRecord::Base)
+        ActiveRecord::Base.connection.tables.each do |table|
+          next if table == 'schema_migrations' || table == 'ar_internal_metadata'
+          ActiveRecord::Base.connection.execute("DELETE FROM #{table}")
+        end
+      end
+      
+      # Clear Rails cache
+      Rails.cache.clear if defined?(Rails) && Rails.cache
+      
+      # Reset any class-level state
+      ActiveSupport::Dependencies.clear if defined?(ActiveSupport::Dependencies)
+    end
+    
+    def run_hook(hook)
+      hook.call if hook && hook.respond_to?(:call)
+    end
+  end
+end