cypress-on-rails 1.19.0 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dcd66d2ef6067166c4e132ca63c09961b26bc0d246063621212fb18fd08c683
-  data.tar.gz: 79307a5b690fbc8b658d2d7c2eecf65f50ea7c883436ba2fbe8299dde44f9528
+  metadata.gz: 9c135e18e23ddeea1d0d2bbd246de9147b9ce42969bd862e51f1e3dec39abbe0
+  data.tar.gz: a295806731243324fbfda475ec6be6a6c4bce60651755b278431afd722501cab
 SHA512:
-  metadata.gz: 39cf1fd4210c02e3f42b1fa0fb570fd8d5c9bbea19307b71a88d125a772a6f5188a282dd9fcec7cd0c648ff1cad61a8148c6b091f9dd897babee5f63283f06b2
-  data.tar.gz: 1353e78c41a987613cec39d906b1db1ed7a28b7506236ebd4b6ed30c3dd8e84268fe158b58afd31e7131f9d7465443087d51c7fb281c89f1d82bd8b0d0920d76
+  metadata.gz: 501aebab098ec19fbec53e3f7ea0ef8adc966c0d4ec2d60a0c424c45e369ad652899270b5e411376f5e582ef8a29acc3d02814cccee85654fe989bdc0aad9c1f
+  data.tar.gz: f833268a8c93e4853fbb28d5b26f653ae741817c4314756975ebd46cac69b6791ca0d436a1d4ab20c9f0be88d4e14b4e399d3d59326cbaf01fb4f2d0b57f24d4

data/CHANGELOG.md

@@ -7,6 +7,84 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed
+* **BREAKING: Generator folder structure**: Fixed install generator to create `e2e_helper.rb` and `app_commands/` at the install folder root (e.g., `e2e/`) instead of inside the framework subdirectory (e.g., `e2e/cypress/`). This ensures compatibility between Cypress/Playwright config file location and middleware expectations. [#201]
+
+### Migration Guide for Folder Structure Change
+
+#### Breaking Change Notice
+If you previously ran the install generator (versions prior to 1.20.0), the file structure created was incorrect. The generator placed helper and command files in the framework subdirectory when they should be at the install folder root.
+
+**Old (Incorrect) Structure:**
+```
+e2e/
+  cypress.config.js
+  cypress/
+    e2e_helper.rb          ← Wrong location
+    app_commands/          ← Wrong location
+    support/
+    e2e/
+```
+
+**New (Correct) Structure:**
+```
+e2e/
+  cypress.config.js
+  e2e_helper.rb            ← Correct location
+  app_commands/            ← Correct location
+  fixtures/
+    vcr_cassettes/         ← VCR cassettes also at root
+  cypress/
+    support/
+    e2e/
+```
+
+#### How to Migrate
+
+**Option 1: Fresh Installation (Recommended for new projects)**
+```bash
+# Remove old structure
+rm -rf e2e/
+
+# Re-run generator
+bin/rails g cypress_on_rails:install --force
+```
+
+**Option 2: Manual Migration (For existing projects with custom code)**
+```bash
+# Move files to correct location
+mv e2e/cypress/e2e_helper.rb e2e/
+mv e2e/cypress/app_commands e2e/
+
+# Update VCR cassettes path if using VCR
+mv e2e/cypress/fixtures e2e/
+
+# Verify your initializer has the correct path
+# Should be: c.install_folder = File.expand_path("#{__dir__}/../../e2e")
+# Not: c.install_folder = File.expand_path("#{__dir__}/../../e2e/cypress")
+```
+
+**Option 3: Update Initializer Only (Quick fix, not recommended)**
+If you cannot migrate files immediately, you can temporarily update your initializer:
+```ruby
+# config/initializers/cypress_on_rails.rb
+c.install_folder = File.expand_path("#{__dir__}/../../e2e/cypress")
+```
+However, this means Cypress may have issues finding config files. We recommend migrating to the correct structure.
+
+#### Why This Change?
+The middleware expects to find `e2e_helper.rb` at `#{install_folder}/e2e_helper.rb` and commands at `#{install_folder}/app_commands/`. Meanwhile, Cypress/Playwright expect config files at the install_folder root when using `--project` flag. The previous structure created a conflict where these requirements couldn't both be satisfied.
+
+#### Testing Your Migration
+After migrating, verify:
+1. Run `bin/rails cypress:open` or `bin/rails playwright:open` - should open successfully
+2. Run a test that uses app commands - should execute without "file not found" errors
+3. Check that VCR cassettes (if used) are being created/loaded correctly
+
+---
+
+## [1.19.0] - 2025-10-01
+
 ### 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:
@@ -434,8 +512,10 @@ If migrating from the `cypress-rails` gem:
 [PR 27]: https://github.com/shakacode/cypress-playwright-on-rails/pull/27
 [PR 31]: https://github.com/shakacode/cypress-playwright-on-rails/pull/31
 [PR 18]: https://github.com/shakacode/cypress-playwright-on-rails/pull/18
+[#201]: https://github.com/shakacode/cypress-playwright-on-rails/issues/201
 
 <!-- Version diff reference list -->
+[1.19.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/shakacode/cypress-playwright-on-rails/compare/v1.15.1...v1.16.0

data/README.md

@@ -134,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
-
-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`.
+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/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.
 
@@ -448,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")
 }
 ```
 
@@ -777,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/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")

data/lib/cypress_on_rails/command_executor.rb

@@ -16,11 +16,35 @@ module CypressOnRails
     def self.load_e2e_helper
       e2e_helper_file = "#{configuration.install_folder}/e2e_helper.rb"
       cypress_helper_file = "#{configuration.install_folder}/cypress_helper.rb"
+
+      # Check for old structure (files in framework subdirectory)
+      old_cypress_location = "#{configuration.install_folder}/cypress/e2e_helper.rb"
+      old_playwright_location = "#{configuration.install_folder}/playwright/e2e_helper.rb"
+
+      # Try to load from the correct location first
       if File.exist?(e2e_helper_file)
         Kernel.require e2e_helper_file
       elsif File.exist?(cypress_helper_file)
         Kernel.require cypress_helper_file
         warn "cypress_helper.rb is deprecated, please rename the file to e2e_helper.rb"
+      # Fallback: load from old location if new location doesn't exist
+      elsif File.exist?(old_cypress_location) || File.exist?(old_playwright_location)
+        old_location = File.exist?(old_cypress_location) ? old_cypress_location : old_playwright_location
+        logger.warn "=" * 80
+        logger.warn "DEPRECATION WARNING: Old folder structure detected!"
+        logger.warn "Found e2e_helper.rb at: #{old_location}"
+        logger.warn "This file should be at: #{e2e_helper_file}"
+        logger.warn ""
+        logger.warn "Loading from old location for now, but this will stop working in a future version."
+        logger.warn "The generator now creates e2e_helper.rb and app_commands/ at the install_folder"
+        logger.warn "root, not inside the framework subdirectory."
+        logger.warn ""
+        logger.warn "To fix this, run: mv #{old_location} #{e2e_helper_file}"
+        logger.warn "Also move app_commands: mv #{File.dirname(old_location)}/app_commands #{configuration.install_folder}/"
+        logger.warn "See CHANGELOG.md for full migration guide."
+        logger.warn "=" * 80
+        # Load from old location as fallback
+        Kernel.require old_location
       else
         logger.warn "could not find #{e2e_helper_file} nor #{cypress_helper_file}"
       end

data/lib/cypress_on_rails/configuration.rb

@@ -22,6 +22,12 @@ module CypressOnRails
     attr_accessor :server_host
     attr_accessor :server_port
     attr_accessor :transactional_server
+    # HTTP path to check for server readiness (default: '/')
+    # Can be set via CYPRESS_RAILS_READINESS_PATH environment variable
+    attr_accessor :server_readiness_path
+    # Timeout in seconds for individual HTTP readiness checks (default: 5)
+    # Can be set via CYPRESS_RAILS_READINESS_TIMEOUT environment variable
+    attr_accessor :server_readiness_timeout
 
     # Attributes for backwards compatibility
     def cypress_folder
@@ -62,6 +68,8 @@ module CypressOnRails
       self.server_host = ENV.fetch('CYPRESS_RAILS_HOST', 'localhost')
       self.server_port = ENV.fetch('CYPRESS_RAILS_PORT', nil)
       self.transactional_server = true
+      self.server_readiness_path = ENV.fetch('CYPRESS_RAILS_READINESS_PATH', '/')
+      self.server_readiness_timeout = ENV.fetch('CYPRESS_RAILS_READINESS_TIMEOUT', '5').to_i
     end
 
     def tagged_logged

data/lib/cypress_on_rails/server.rb

@@ -1,6 +1,7 @@
 require 'socket'
 require 'timeout'
 require 'fileutils'
+require 'net/http'
 require 'cypress_on_rails/configuration'
 
 module CypressOnRails
@@ -9,13 +10,16 @@ module CypressOnRails
 
     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)
+      # Process management: track PID and process group for proper cleanup
+      @server_pid = nil
+      @server_pgid = nil
     end
 
     def open
@@ -105,34 +109,91 @@ module CypressOnRails
 
       puts "Starting Rails server: #{server_args.join(' ')}"
 
-      spawn(*server_args, out: $stdout, err: $stderr)
+      @server_pid = spawn(*server_args, out: $stdout, err: $stderr, pgroup: true)
+      begin
+        @server_pgid = Process.getpgid(@server_pid)
+      rescue Errno::ESRCH => e
+        # Edge case: process terminated before we could get pgid
+        # This is OK - send_term_signal will fall back to single-process kill
+        CypressOnRails.configuration.logger.warn("Process #{@server_pid} terminated immediately after spawn: #{e.message}")
+        @server_pgid = nil
+      end
+      @server_pid
     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
+          break if server_responding?
+          sleep 0.1
         end
       end
     rescue Timeout::Error
       raise "Rails server failed to start on #{host}:#{port} after #{timeout} seconds"
     end
 
+    def server_responding?
+      config = CypressOnRails.configuration
+      readiness_path = config.server_readiness_path || '/'
+      timeout = config.server_readiness_timeout || 5
+      uri = URI("http://#{host}:#{port}#{readiness_path}")
+
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: timeout, read_timeout: timeout) do |http|
+        http.get(uri.path)
+      end
+
+      # Accept 200-399 (success and redirects), reject 404 and 5xx
+      # 3xx redirects are considered "ready" because the server is responding correctly
+      (200..399).cover?(response.code.to_i)
+    rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, Errno::ETIMEDOUT, SocketError,
+           Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse
+      false
+    end
+
     def stop_server(pid)
-      if pid
-        puts "Stopping Rails server (PID: #{pid})"
-        Process.kill('TERM', pid)
-        Process.wait(pid)
+      return unless pid
+
+      puts "Stopping Rails server (PID: #{pid})"
+      send_term_signal(pid)
+
+      begin
+        Timeout.timeout(10) do
+          Process.wait(pid)
+        end
+      rescue Timeout::Error
+        CypressOnRails.configuration.logger.warn("Server did not terminate after TERM signal, sending KILL")
+        safe_kill_process('KILL', pid)
+        Process.wait(pid) rescue Errno::ESRCH
       end
     rescue Errno::ESRCH
       # Process already terminated
     end
 
+    def send_term_signal(pid)
+      if @server_pgid && process_exists?(pid)
+        Process.kill('TERM', -@server_pgid)
+      else
+        safe_kill_process('TERM', pid)
+      end
+    rescue Errno::ESRCH, Errno::EPERM => e
+      CypressOnRails.configuration.logger.warn("Failed to kill process group #{@server_pgid}: #{e.message}, trying single process")
+      safe_kill_process('TERM', pid)
+    end
+
+    def process_exists?(pid)
+      return false unless pid
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def safe_kill_process(signal, pid)
+      Process.kill(signal, pid) if pid
+    rescue Errno::ESRCH, Errno::EPERM
+      # Process already terminated or permission denied
+    end
+
     def base_url
       "http://#{host}:#{port}"
     end

data/lib/cypress_on_rails/version.rb

@@ -1,3 +1,3 @@
 module CypressOnRails
-  VERSION = '1.19.0'.freeze
+  VERSION = '1.20.0'.freeze
 end

data/lib/generators/cypress_on_rails/install_generator.rb

@@ -42,8 +42,8 @@ module CypressOnRails
 
     def add_initial_files
       template "config/initializers/cypress_on_rails.rb.erb", "config/initializers/cypress_on_rails.rb"
-      template "spec/e2e/e2e_helper.rb.erb", "#{options.install_folder}/#{options.framework}/e2e_helper.rb"
-      directory 'spec/e2e/app_commands', "#{options.install_folder}/#{options.framework}/app_commands"
+      template "spec/e2e/e2e_helper.rb.erb", "#{options.install_folder}/e2e_helper.rb"
+      directory 'spec/e2e/app_commands', "#{options.install_folder}/app_commands"
       if options.framework == 'cypress'
         copy_file "spec/cypress/support/on-rails.js", "#{options.install_folder}/cypress/support/on-rails.js"
         directory 'spec/cypress/e2e/rails_examples', "#{options.install_folder}/cypress/e2e/rails_examples"

data/lib/generators/cypress_on_rails/templates/config/initializers/cypress_on_rails.rb.erb

@@ -1,7 +1,7 @@
 if defined?(CypressOnRails)
   CypressOnRails.configure do |c|
     c.api_prefix = "<%= options.api_prefix %>"
-    c.install_folder = File.expand_path("#{__dir__}/../../<%= options.install_folder %>/<%= options.framework %>")
+    c.install_folder = File.expand_path("#{__dir__}/../../<%= options.install_folder %>")
     # WARNING!! CypressOnRails can execute arbitrary ruby code
     # please use with extra caution if enabling on hosted servers or starting your local server on 0.0.0.0
     c.use_middleware = !Rails.env.production?
@@ -12,7 +12,7 @@ if defined?(CypressOnRails)
     <% unless options.experimental %># <% end %> c.vcr_options = {
     <% unless options.experimental %># <% end %>   hook_into: :webmock,
     <% unless options.experimental %># <% end %>   default_cassette_options: { record: :once },
-    <% unless options.experimental %># <% end %>   cassette_library_dir: File.expand_path("#{__dir__}/../../<%= options.install_folder %>/<%= options.framework %>/fixtures/vcr_cassettes")
+    <% unless options.experimental %># <% end %>   cassette_library_dir: File.expand_path("#{__dir__}/../../<%= options.install_folder %>/fixtures/vcr_cassettes")
     <% unless options.experimental %># <% end %> }
     c.logger = Rails.logger
     

data/spec/cypress_on_rails/configuration_spec.rb

@@ -10,6 +10,8 @@ RSpec.describe CypressOnRails::Configuration do
     expect(CypressOnRails.configuration.logger).to_not be_nil
     expect(CypressOnRails.configuration.before_request).to_not be_nil
     expect(CypressOnRails.configuration.vcr_options).to eq({})
+    expect(CypressOnRails.configuration.server_readiness_path).to eq('/')
+    expect(CypressOnRails.configuration.server_readiness_timeout).to eq(5)
   end
 
   it 'can be configured' do
@@ -22,6 +24,8 @@ RSpec.describe CypressOnRails::Configuration do
       config.logger = my_logger
       config.before_request = before_request_lambda
       config.vcr_options = { hook_into: :webmock }
+      config.server_readiness_path = '/health'
+      config.server_readiness_timeout = 10
     end
     expect(CypressOnRails.configuration.api_prefix).to eq('/api')
     expect(CypressOnRails.configuration.install_folder).to eq('my/path')
@@ -29,5 +33,7 @@ RSpec.describe CypressOnRails::Configuration do
     expect(CypressOnRails.configuration.logger).to eq(my_logger)
     expect(CypressOnRails.configuration.before_request).to eq(before_request_lambda)
     expect(CypressOnRails.configuration.vcr_options).to eq(hook_into: :webmock)
+    expect(CypressOnRails.configuration.server_readiness_path).to eq('/health')
+    expect(CypressOnRails.configuration.server_readiness_timeout).to eq(10)
   end
 end

data/spec/generators/install_generator_spec.rb

@@ -0,0 +1,222 @@
+require 'spec_helper'
+require 'rails/generators'
+require 'generators/cypress_on_rails/install_generator'
+require 'tmpdir'
+require 'fileutils'
+
+RSpec.describe CypressOnRails::InstallGenerator, type: :generator do
+  let(:destination_root) { Dir.mktmpdir }
+
+  before do
+    # Set up a minimal Rails app structure
+    FileUtils.mkdir_p(File.join(destination_root, 'config', 'initializers'))
+    FileUtils.mkdir_p(File.join(destination_root, 'bin'))
+
+    # Mock the generator's destination_root
+    allow(Dir).to receive(:pwd).and_return(destination_root)
+
+    # Prevent actual npm/yarn installation in tests
+    # Mock only package manager commands, let file operations through
+    allow_any_instance_of(CypressOnRails::InstallGenerator).to receive(:system) do |_, command|
+      # Return true for yarn/npm install commands to skip actual installation
+      command.to_s.match?(/yarn|npm/)
+    end
+  end
+
+  after do
+    FileUtils.rm_rf(destination_root)
+  end
+
+  describe 'with default options (cypress framework, e2e folder)' do
+    let(:args) { [] }
+    let(:options) { {} }
+
+    before do
+      run_generator(args, options)
+    end
+
+    it 'creates the initializer with correct install_folder path' do
+      initializer_path = File.join(destination_root, 'config', 'initializers', 'cypress_on_rails.rb')
+      expect(File).to exist(initializer_path)
+
+      content = File.read(initializer_path)
+      # Should point to e2e, not e2e/cypress
+      expect(content).to include('c.install_folder = File.expand_path("#{__dir__}/../../e2e")')
+    end
+
+    it 'creates cypress config at install_folder root' do
+      config_path = File.join(destination_root, 'e2e', 'cypress.config.js')
+      expect(File).to exist(config_path)
+    end
+
+    it 'creates e2e_helper.rb at install_folder root' do
+      helper_path = File.join(destination_root, 'e2e', 'e2e_helper.rb')
+      expect(File).to exist(helper_path)
+    end
+
+    it 'creates app_commands directory at install_folder root' do
+      commands_path = File.join(destination_root, 'e2e', 'app_commands')
+      expect(File).to be_directory(commands_path)
+    end
+
+    it 'creates cypress support files in framework subdirectory' do
+      support_path = File.join(destination_root, 'e2e', 'cypress', 'support', 'index.js')
+      expect(File).to exist(support_path)
+    end
+
+    it 'creates cypress examples in framework subdirectory' do
+      examples_path = File.join(destination_root, 'e2e', 'cypress', 'e2e', 'rails_examples')
+      expect(File).to be_directory(examples_path)
+    end
+  end
+
+  describe 'with playwright framework' do
+    let(:args) { [] }
+    let(:options) { { framework: 'playwright' } }
+
+    before do
+      run_generator(args, options)
+    end
+
+    it 'creates the initializer with correct install_folder path' do
+      initializer_path = File.join(destination_root, 'config', 'initializers', 'cypress_on_rails.rb')
+      expect(File).to exist(initializer_path)
+
+      content = File.read(initializer_path)
+      # Should point to e2e, not e2e/playwright
+      expect(content).to include('c.install_folder = File.expand_path("#{__dir__}/../../e2e")')
+    end
+
+    it 'creates playwright config at install_folder root' do
+      config_path = File.join(destination_root, 'e2e', 'playwright.config.js')
+      expect(File).to exist(config_path)
+    end
+
+    it 'creates e2e_helper.rb at install_folder root' do
+      helper_path = File.join(destination_root, 'e2e', 'e2e_helper.rb')
+      expect(File).to exist(helper_path)
+    end
+
+    it 'creates app_commands directory at install_folder root' do
+      commands_path = File.join(destination_root, 'e2e', 'app_commands')
+      expect(File).to be_directory(commands_path)
+    end
+
+    it 'creates playwright support files in framework subdirectory' do
+      support_path = File.join(destination_root, 'e2e', 'playwright', 'support', 'index.js')
+      expect(File).to exist(support_path)
+    end
+
+    it 'creates playwright examples in framework subdirectory' do
+      examples_path = File.join(destination_root, 'e2e', 'playwright', 'e2e', 'rails_examples')
+      expect(File).to be_directory(examples_path)
+    end
+  end
+
+  describe 'with custom install_folder' do
+    let(:args) { [] }
+    let(:options) { { install_folder: 'spec/system' } }
+
+    before do
+      run_generator(args, options)
+    end
+
+    it 'creates files in the custom folder' do
+      helper_path = File.join(destination_root, 'spec', 'system', 'e2e_helper.rb')
+      expect(File).to exist(helper_path)
+
+      commands_path = File.join(destination_root, 'spec', 'system', 'app_commands')
+      expect(File).to be_directory(commands_path)
+    end
+
+    it 'sets the correct install_folder in the initializer' do
+      initializer_path = File.join(destination_root, 'config', 'initializers', 'cypress_on_rails.rb')
+      content = File.read(initializer_path)
+      expect(content).to include('c.install_folder = File.expand_path("#{__dir__}/../../spec/system")')
+    end
+  end
+
+  describe 'file structure ensures middleware and framework compatibility' do
+    let(:args) { [] }
+    let(:options) { {} }
+
+    before do
+      run_generator(args, options)
+    end
+
+    it 'does not create e2e_helper.rb in old location (framework subdirectory)' do
+      old_cypress_path = File.join(destination_root, 'e2e', 'cypress', 'e2e_helper.rb')
+      old_playwright_path = File.join(destination_root, 'e2e', 'playwright', 'e2e_helper.rb')
+      expect(File).not_to exist(old_cypress_path)
+      expect(File).not_to exist(old_playwright_path)
+    end
+
+    it 'does not create app_commands in old location (framework subdirectory)' do
+      old_cypress_path = File.join(destination_root, 'e2e', 'cypress', 'app_commands')
+      old_playwright_path = File.join(destination_root, 'e2e', 'playwright', 'app_commands')
+      expect(File).not_to exist(old_cypress_path)
+      expect(File).not_to exist(old_playwright_path)
+    end
+
+    it 'places e2e_helper.rb where middleware expects it (install_folder/e2e_helper.rb)' do
+      # Middleware looks for #{install_folder}/e2e_helper.rb
+      helper_path = File.join(destination_root, 'e2e', 'e2e_helper.rb')
+      expect(File).to exist(helper_path)
+      expect(File.read(helper_path)).to include('CypressOnRails')
+    end
+
+    it 'places app_commands where middleware expects it (install_folder/app_commands)' do
+      # Middleware looks for #{install_folder}/app_commands/#{command}.rb
+      commands_path = File.join(destination_root, 'e2e', 'app_commands')
+      expect(File).to be_directory(commands_path)
+
+      # Check that command files exist
+      clean_cmd = File.join(commands_path, 'clean.rb')
+      expect(File).to exist(clean_cmd)
+    end
+
+    it 'places cypress.config.js where cypress --project flag expects it' do
+      # Cypress runs with --project install_folder, expects config at that level
+      config_path = File.join(destination_root, 'e2e', 'cypress.config.js')
+      expect(File).to exist(config_path)
+
+      # Verify the config references the correct relative path for support files
+      content = File.read(config_path)
+      expect(content).to include('cypress/support/index.js')
+    end
+
+    it 'creates a valid directory structure' do
+      # The expected structure:
+      # e2e/
+      #   cypress.config.js       <- Config at root of install_folder
+      #   e2e_helper.rb           <- Helper at root of install_folder
+      #   app_commands/           <- Commands at root of install_folder
+      #   cypress/                <- Framework-specific subdirectory
+      #     support/
+      #     e2e/
+
+      expect(File).to exist(File.join(destination_root, 'e2e', 'cypress.config.js'))
+      expect(File).to exist(File.join(destination_root, 'e2e', 'e2e_helper.rb'))
+      expect(File).to be_directory(File.join(destination_root, 'e2e', 'app_commands'))
+      expect(File).to be_directory(File.join(destination_root, 'e2e', 'cypress'))
+      expect(File).to be_directory(File.join(destination_root, 'e2e', 'cypress', 'support'))
+      expect(File).to be_directory(File.join(destination_root, 'e2e', 'cypress', 'e2e'))
+    end
+  end
+
+  def run_generator(args, options)
+    generator_options = []
+    options.each do |key, value|
+      generator_options << "--#{key}=#{value}"
+    end
+
+    CypressOnRails::InstallGenerator.start(
+      args + generator_options,
+      {
+        destination_root: destination_root,
+        shell: Thor::Shell::Basic.new,
+        behavior: :invoke
+      }
+    )
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cypress-on-rails
 version: !ruby/object:Gem::Version
-  version: 1.19.0
+  version: 1.20.0
 platform: ruby
 authors:
 - miceportal team
@@ -108,7 +108,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Integrates cypress with rails or rack applications
+description: Integrates Cypress and Playwright with Rails or Rack applications
 email:
 - info@miceportal.de
 - grantspeelman@gmail.com
@@ -197,6 +197,7 @@ files:
 - spec/cypress_on_rails/smart_factory_wrapper_spec.rb
 - spec/cypress_on_rails/vcr/insert_eject_middleware_spec.rb
 - spec/cypress_on_rails/vcr/use_cassette_middleware_spec.rb
+- spec/generators/install_generator_spec.rb
 - spec/spec_helper.rb
 - specs_e2e/cypress.config.js
 - specs_e2e/playwright.config.js
@@ -436,5 +437,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Integrates cypress with rails or rack applications
+summary: Integrates Cypress and Playwright with Rails or Rack applications
 test_files: []