Add comprehensive migration guide and deprecation warnings

Added for users upgrading from old generator structure:

1. CHANGELOG.md:
   - Breaking change notice with detailed explanation
   - Three migration options (fresh install, manual, temporary workaround)
   - Testing checklist to verify migration success
   - Clear before/after structure diagrams

2. README.md:
   - Explicit directory structure documentation for both Cypress and Playwright
   - Clear note that e2e_helper.rb and app_commands/ are at install_folder root
   - Visual structure trees with comments

3. Command Executor:
   - Runtime deprecation warning when old structure detected
   - Detects files in cypress/ or playwright/ subdirectories
   - Provides clear migration instructions with exact commands
   - References CHANGELOG for full migration guide

These changes help existing users understand the breaking change and provide
clear paths to migrate, while new users get proper documentation of the
expected structure.

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

Co-Authored-By: Claude <[email protected]>

Author: justin808

CHANGELOG.md

@@ -7,6 +7,82 @@ 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

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.
 

lib/cypress_on_rails/command_executor.rb

@@ -16,6 +16,26 @@ def self.perform(file,command_options = nil)
     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"
+
+      if 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 "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 "See CHANGELOG.md for full migration guide."
+        logger.warn "=" * 80
+      end
+
       if File.exist?(e2e_helper_file)
         Kernel.require e2e_helper_file
       elsif File.exist?(cypress_helper_file)