ruby_raider 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d6b5fccbc2b3752d7f63391226d903a61a1368a404831ef10b1d0d230774fa5
-  data.tar.gz: 7d4be1564e22cb7bf47e0d08ced4ae00868140bbd0c65833e733a904e634ecf4
+  metadata.gz: 4ef04718aea3c6036141557edd000ddc0ecb4df784bbfa6434ddf7a275edb73f
+  data.tar.gz: 1ba77ec6eeb15fe8520819dce31dde3b4a8763b83d901ddf32a4b7ca47411cdc
 SHA512:
-  metadata.gz: d9c67f3a57b7bfe7c3426ea0a5220af9b2623d9ce7003c1ebf2052bb19e23125a2f88ee277e89349dece675d13e07833818a93b25dbdbaf2a712dc8661fd0fa3
-  data.tar.gz: 840873be251968d311b86e15586219fe402f433a7cf81f5eccd46e1b8227dfa52c95274099818d4eabf764b015e28cce116bcaac2334ba7e840be6a379a4d6d0
+  metadata.gz: a78ba73874f84e22f137f7c996a44fbe5703b80527422966bb31ecb83e1dfc0e21442edcfdcc1bf015bcc7129a4683a711d10c4c1c78da6f362ac7faf70b1230
+  data.tar.gz: eaac9b04da1d97f865ba8ebee4643bb9a594ffbaf884aa905b204ed2e1759d5189a560d3e1165721af4fa60de4c603a1e7be31572e5ebbc53eeace5d60b4a7d4

data/lib/commands/scaffolding_commands.rb

@@ -2,6 +2,7 @@
 
 require 'thor'
 require 'fileutils'
+require 'pathname'
 require_relative '../generators/menu_generator'
 require_relative '../scaffolding/scaffolding'
 require_relative '../scaffolding/name_normalizer'
@@ -165,7 +166,27 @@ class ScaffoldingCommands < Thor
 
   no_commands do
     def load_config_path(type)
-      YAML.load_file('config/config.yml')["#{type}_path"] if Pathname.new('config/config.yml').exist?
+      ScaffoldProjectDetector.config_path(type)
+    end
+
+    def validate_project!
+      warnings = ScaffoldProjectDetector.validate_project
+      warnings.each { |w| say "Warning: #{w}", :yellow }
+      show_detection_defaults
+    end
+
+    def show_detection_defaults
+      gemfile = ScaffoldProjectDetector.read_gemfile
+      if gemfile.empty?
+        say 'Warning: No Gemfile found, defaulting to selenium + rspec templates.', :yellow
+      else
+        automation = ScaffoldProjectDetector.detect_automation(gemfile)
+        framework = ScaffoldProjectDetector.detect_framework(gemfile)
+        if automation.nil?
+          say 'Warning: Could not detect automation library from Gemfile, defaulting to selenium.', :yellow
+        end
+        say 'Warning: Could not detect test framework from Gemfile, defaulting to rspec.', :yellow if framework.nil?
+      end
     end
 
     def delete_scaffolding(name, type)
@@ -186,6 +207,7 @@ class ScaffoldingCommands < Thor
     end
 
     def generate_default_scaffold(name)
+      validate_project!
       uses = options[:uses]
       if Pathname.new('spec').exist? && !Pathname.new('features').exist?
         generate_scaffolding(name, 'spec', load_config_path('spec'), uses:)
@@ -197,6 +219,7 @@ class ScaffoldingCommands < Thor
     end
 
     def generate_selected_components(name, components)
+      validate_project!
       uses = options[:uses]
       components.each do |comp|
         comp = comp.downcase.strip
@@ -211,6 +234,7 @@ class ScaffoldingCommands < Thor
 
     def generate_crud(name)
       require_relative '../scaffolding/crud_generator'
+      validate_project!
       if options[:dry_run]
         crud = CrudGenerator.new(name, Scaffolding, method(:load_config_path))
         DryRunPresenter.preview(crud.planned_files)
@@ -266,6 +290,7 @@ class ScaffoldingCommands < Thor
 
     def interactive_scaffold
       require_relative '../scaffolding/scaffold_menu'
+      validate_project!
       result = ScaffoldMenu.new.run
       return unless result
 

data/lib/commands/utility_commands.rb

@@ -35,7 +35,7 @@ class UtilityCommands < Thor
     browser_options(selected_options) if selected_options || options[:delete]
   end
 
-  desc 'browser_options [OPTIONS]', 'Sets the browser options for the project'
+  desc 'browser_options [OPTIONS]', 'Sets the browser arguments for the current browser (e.g. no-sandbox, headless)'
   option :delete,
          type: :boolean, required: false, desc: 'This will delete your browser options', aliases: '-d'
 
@@ -44,6 +44,15 @@ class UtilityCommands < Thor
     Utilities.delete_browser_options if options[:delete]
   end
 
+  desc 'headless [on/off]', 'Toggles headless mode for browser tests'
+
+  def headless(toggle)
+    enabled = %w[on true 1 yes].include?(toggle.downcase)
+    Utilities.headless = enabled
+    state = enabled ? 'enabled' : 'disabled'
+    say "Headless mode #{state}", :green
+  end
+
   desc 'raid', 'It runs all the tests in a project'
   option :parallel,
          type: :boolean, required: false, desc: 'It runs the tests in parallel', aliases: '-p'

data/lib/generators/templates/helpers/browser_helper.tt

@@ -20,7 +20,7 @@ module BrowserHelper
     Watir.default_timeout = config.fetch('timeout', 10)
     browser_name = config['browser'].to_s
     args = args.empty? ? config['browser_arguments'][browser_name] : args
-    args += ['--headless'] if ENV['HEADLESS'] && !args.include?('--headless')
+    args += ['--headless'] if (ENV['HEADLESS'] || config['headless']) && !args.include?('--headless')
     capitalized = browser_name == 'ie' ? browser_name.upcase : browser_name.capitalize
     browser_options = "Selenium::WebDriver::#{capitalized}::Options".constantize.new(args:)
     debug_cfg = config['debug'] || {}

data/lib/generators/templates/helpers/capybara_helper.tt

@@ -20,7 +20,7 @@ module CapybaraHelper
     Capybara.register_driver :selenium do |app|
       browser = config['browser'].to_sym
       args = config['browser_arguments'][config['browser']] || []
-      args += ['--headless'] if ENV['HEADLESS'] && !args.include?('--headless')
+      args += ['--headless'] if (ENV['HEADLESS'] || config['headless']) && !args.include?('--headless')
       options = Selenium::WebDriver::Chrome::Options.new(args:)
       debug_cfg = config['debug'] || {}
       if debug_cfg.fetch('enabled', false) || ENV['DEBUG']&.downcase == 'true'

data/lib/generators/templates/helpers/partials/selenium_driver.tt

@@ -8,7 +8,7 @@
 
   def browser_arguments(*opts)
     args = opts.empty? ? @config['browser_arguments'][@config['browser']] : opts
-    args += ['--headless'] if ENV['HEADLESS'] && !args.include?('--headless')
+    args += ['--headless'] if (ENV['HEADLESS'] || @config['headless']) && !args.include?('--headless')
     args
   end
 

data/lib/scaffolding/project_detector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'yaml'
+
 module ScaffoldProjectDetector
   AUTOMATION_GEMS = {
     'capybara' => 'capybara',
@@ -17,6 +19,10 @@ module ScaffoldProjectDetector
     'minitest' => 'minitest'
   }.freeze
 
+  CONFIG_PATH = 'config/config.yml'
+
+  class Error < StandardError; end
+
   module_function
 
   def detect
@@ -62,11 +68,29 @@ module ScaffoldProjectDetector
     detect_automation == 'watir'
   end
 
+  # Validates that the current directory looks like a Ruby Raider project.
+  # Returns an array of warning messages (empty = valid project).
+  def validate_project
+    warnings = []
+    warnings << 'Gemfile not found. Are you in a Ruby Raider project directory?' unless File.exist?('Gemfile')
+    unless File.exist?(CONFIG_PATH)
+      warnings << "#{CONFIG_PATH} not found. Scaffolded pages won't include URL navigation methods."
+    end
+    warnings
+  end
+
+  # Loads and parses config/config.yml. Returns a hash.
+  # Raises ScaffoldProjectDetector::Error on malformed YAML.
   def config
-    return {} unless File.exist?('config/config.yml')
+    return {} unless File.exist?(CONFIG_PATH)
+
+    YAML.safe_load(File.read(CONFIG_PATH), permitted_classes: [Symbol]) || {}
+  rescue Psych::SyntaxError => e
+    raise Error, "#{CONFIG_PATH} has invalid YAML syntax: #{e.message}"
+  end
 
-    YAML.safe_load(File.read('config/config.yml'), permitted_classes: [Symbol]) || {}
-  rescue StandardError
-    {}
+  # Returns the custom path for a scaffold type from config, or nil.
+  def config_path(type)
+    config["#{type}_path"]
   end
 end

data/lib/utilities/utilities.rb

@@ -44,14 +44,22 @@ module Utilities
     end
 
     def browser_options=(opts)
-      set('browser_options', Array(opts).flatten)
+      browser_name = config['browser'] || 'chrome'
+      config['browser_arguments'] ||= {}
+      config['browser_arguments'][browser_name] = Array(opts).flatten
+      overwrite_yaml
     end
 
     def delete_browser_options
-      config.delete('browser_options')
+      browser_name = config['browser'] || 'chrome'
+      config['browser_arguments']&.delete(browser_name)
       overwrite_yaml
     end
 
+    def headless=(enabled)
+      set('headless', enabled)
+    end
+
     def llm_provider=(provider)
       set('llm_provider', provider)
     end

data/lib/version

@@ -1 +1 @@
-3.0.0
+3.0.1

data/spec/commands/scaffolding_commands_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+RSpec.describe 'ScaffoldingCommands' do
+  describe 'dependencies' do
+    it 'loads without relying on transitive requires for Pathname' do
+      # Loads the file in a clean Ruby process where nothing else has required 'pathname'.
+      # This catches the exact bug where Pathname is used but never explicitly required,
+      # which works in test suites (rspec loads pathname transitively) but crashes at runtime.
+      script = <<~RUBY
+        require_relative '../../lib/commands/scaffolding_commands'
+        puts 'OK'
+      RUBY
+
+      stdout, stderr, status = Open3.capture3('ruby', '-e', script, chdir: __dir__)
+      expect(status.success?).to be(true),
+                                 "ScaffoldingCommands failed to load in isolation:\n#{stderr}"
+      expect(stdout.strip).to eq('OK')
+    end
+  end
+end

data/spec/integration/commands/utility_commands_spec.rb

@@ -43,10 +43,10 @@ describe UtilityCommands do
       expect(config['browser']).to eql ':firefox'
     end
 
-    it 'updates the browser options' do
+    it 'updates the browser arguments for the current browser' do
       utility.new.invoke(:browser, nil, %w[:firefox --opts headless start-maximized start-fullscreen])
       config = YAML.load_file('config/config.yml')
-      expect(config['browser_options']).to eql %w[headless start-maximized start-fullscreen]
+      expect(config['browser_arguments'][':firefox']).to eql %w[headless start-maximized start-fullscreen]
     end
   end
 
@@ -91,23 +91,23 @@ describe UtilityCommands do
       expect(config['feature_path']).to eql path
     end
 
-    it 'updates only the browser options' do
+    it 'updates the browser arguments for the current browser' do
       utility.new.invoke(:browser, nil, %w[:firefox --opts headless])
       config = YAML.load_file('config/config.yml')
-      expect(config['browser_options']).to eql %w[headless]
+      expect(config['browser_arguments'][':firefox']).to eql %w[headless]
     end
 
-    it 'deletes the browser options when passed with the delete parameter' do
+    it 'deletes the browser arguments when passed with the delete parameter' do
       utility.new.invoke(:browser, nil, %w[:firefox --opts headless --delete])
       config = YAML.load_file('config/config.yml')
-      expect(config['browser_options']).to be_nil
+      expect(config.dig('browser_arguments', ':firefox')).to be_nil
     end
 
-    it 'deletes the browser options' do
+    it 'deletes the browser arguments' do
       utility.new.invoke(:browser, nil, %w[:firefox --opts headless])
       utility.new.invoke(:browser, nil, %w[--delete])
       config = YAML.load_file('config/config.yml')
-      expect(config['browser_options']).to be_nil
+      expect(config.dig('browser_arguments', ':firefox')).to be_nil
     end
   end
 end

data/spec/integration/scaffolding_e2e_spec.rb

@@ -0,0 +1,775 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require_relative '../../lib/commands/scaffolding_commands'
+require_relative '../../lib/scaffolding/scaffolding'
+
+# Custom matchers (defined inline to avoid pulling in integration spec_helper)
+RSpec::Matchers.define :have_frozen_string_literal do
+  match { |content| content.include?('# frozen_string_literal: true') }
+  failure_message { 'expected file to contain frozen_string_literal magic comment' }
+end
+
+RSpec::Matchers.define :have_valid_ruby_syntax do
+  match do |content|
+    RubyVM::InstructionSequence.compile(content)
+    true
+  rescue SyntaxError
+    false
+  end
+  failure_message { |_content| "expected valid Ruby syntax but got SyntaxError: #{$ERROR_INFO&.message}" }
+end
+
+# End-to-end scaffolding tests that verify the scaffold command creates the right
+# files with the right content across all automation × framework combinations.
+describe 'Scaffolding E2E' do # rubocop:disable RSpec/DescribeClass
+
+  WEB_AUTOMATIONS = %w[selenium capybara watir].freeze
+  TEST_FRAMEWORKS = %w[rspec cucumber minitest].freeze
+
+  # The scaffolding system's generate_default_scaffold checks for spec/ or features/.
+  # Minitest projects have test/ only — so the scaffold falls through to feature+steps.
+  def self.scaffold_style(framework)
+    case framework
+    when 'rspec'    then :spec
+    when 'cucumber' then :feature
+    when 'minitest' then :feature # no spec/ dir → falls to else clause
+    end
+  end
+
+  # Build a minimal mock project that the scaffolding system can detect.
+  def self.build_mock_project(automation, framework) # rubocop:disable Metrics/MethodLength
+    dir = File.expand_path("tmp_scaffold_e2e_#{framework}_#{automation}")
+    FileUtils.rm_rf(dir)
+    FileUtils.mkdir_p("#{dir}/page_objects/pages")
+    FileUtils.mkdir_p("#{dir}/page_objects/abstract")
+    FileUtils.mkdir_p("#{dir}/page_objects/components")
+    FileUtils.mkdir_p("#{dir}/helpers")
+    FileUtils.mkdir_p("#{dir}/config")
+    FileUtils.mkdir_p("#{dir}/models/data")
+
+    case framework
+    when 'rspec'    then FileUtils.mkdir_p("#{dir}/spec")
+    when 'cucumber' then FileUtils.mkdir_p("#{dir}/features/step_definitions")
+                         FileUtils.mkdir_p("#{dir}/features/support")
+    when 'minitest' then FileUtils.mkdir_p("#{dir}/test")
+    end
+
+    gems = []
+    case automation
+    when 'selenium'  then gems << "gem 'selenium-webdriver'"
+    when 'capybara'  then gems << "gem 'capybara'"
+    when 'watir'     then gems << "gem 'watir'"
+    end
+    case framework
+    when 'rspec'    then gems << "gem 'rspec'"
+    when 'cucumber' then gems << "gem 'cucumber'"
+    when 'minitest' then gems << "gem 'minitest'"
+    end
+    File.write("#{dir}/Gemfile", gems.join("\n") + "\n")
+    File.write("#{dir}/config/config.yml", "browser: chrome\nurl: http://localhost:3000\n")
+    File.write("#{dir}/page_objects/abstract/page.rb", "class Page; end\n")
+    File.write("#{dir}/page_objects/abstract/component.rb", "class Component; end\n")
+
+    dir
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Page object content
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded page' do
+    it 'has frozen_string_literal' do
+      expect(page_content).to have_frozen_string_literal
+    end
+
+    it 'has valid Ruby syntax' do
+      expect(page_content).to have_valid_ruby_syntax
+    end
+
+    it 'inherits from Page' do
+      expect(page_content).to include('class CheckoutPage < Page')
+    end
+
+    it 'requires abstract page' do
+      expect(page_content).to include("require_relative '../abstract/page'")
+    end
+
+    it 'includes url method (config has url)' do
+      expect(page_content).to include("def url(_page)")
+      expect(page_content).to include("'checkout'")
+    end
+  end
+
+  shared_examples 'selenium scaffolded page' do
+    it 'has driver.find_element example' do
+      expect(page_content).to include('driver.find_element')
+    end
+
+    it 'has private section' do
+      expect(page_content).to include('private')
+    end
+
+    it 'does not have capybara fill_in' do
+      expect(page_content).not_to include('fill_in')
+    end
+
+    it 'does not have watir browser.text_field' do
+      expect(page_content).not_to include('browser.text_field')
+    end
+  end
+
+  shared_examples 'capybara scaffolded page' do
+    it 'has fill_in example' do
+      expect(page_content).to include('fill_in')
+    end
+
+    it 'has no private section' do
+      expect(page_content).not_to include('private')
+    end
+
+    it 'does not have selenium find_element' do
+      expect(page_content).not_to include('driver.find_element')
+    end
+
+    it 'does not have watir browser.text_field' do
+      expect(page_content).not_to include('browser.text_field')
+    end
+  end
+
+  shared_examples 'watir scaffolded page' do
+    it 'has browser.text_field example' do
+      expect(page_content).to include('browser.text_field')
+    end
+
+    it 'has private section' do
+      expect(page_content).to include('private')
+    end
+
+    it 'does not have selenium find_element' do
+      expect(page_content).not_to include('driver.find_element')
+    end
+
+    it 'does not have capybara fill_in' do
+      expect(page_content).not_to include('fill_in')
+    end
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Spec content (RSpec)
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded spec' do
+    it 'has frozen_string_literal' do
+      expect(spec_content).to have_frozen_string_literal
+    end
+
+    it 'has valid Ruby syntax' do
+      expect(spec_content).to have_valid_ruby_syntax
+    end
+
+    it 'describes the page class' do
+      expect(spec_content).to include("describe 'CheckoutPage'")
+    end
+
+    it 'requires the page object' do
+      expect(spec_content).to include("require_relative '../page_objects/pages/checkout'")
+    end
+
+    it 'has pending test' do
+      expect(spec_content).to include("pending 'implement test'")
+    end
+
+    it 'has before block with navigation' do
+      expect(spec_content).to include('before do')
+    end
+  end
+
+  shared_examples 'selenium scaffolded spec' do
+    it 'instantiates page with driver' do
+      expect(spec_content).to include('CheckoutPage.new(driver)')
+    end
+
+    it 'navigates with driver' do
+      expect(spec_content).to include('driver.navigate.to')
+    end
+
+    it 'does not use capybara visit' do
+      expect(spec_content).not_to match(/^\s+visit '/)
+    end
+  end
+
+  shared_examples 'capybara scaffolded spec' do
+    it 'instantiates page without arguments' do
+      expect(spec_content).to include('CheckoutPage.new')
+      expect(spec_content).not_to include('CheckoutPage.new(driver)')
+      expect(spec_content).not_to include('CheckoutPage.new(browser)')
+    end
+
+    it 'uses visit for navigation' do
+      expect(spec_content).to include("visit 'checkout'")
+    end
+  end
+
+  shared_examples 'watir scaffolded spec' do
+    it 'instantiates page with browser' do
+      expect(spec_content).to include('CheckoutPage.new(browser)')
+    end
+
+    it 'navigates with browser.goto' do
+      expect(spec_content).to include('browser.goto')
+    end
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Feature content (Cucumber)
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded feature' do
+    it 'has Feature keyword' do
+      expect(feature_content).to include('Feature: Checkout')
+    end
+
+    it 'has Scenario keyword' do
+      expect(feature_content).to include('Scenario: Scenario name')
+    end
+
+    it 'has Given/When/Then steps' do
+      expect(feature_content).to include('Given I am on the checkout page')
+      expect(feature_content).to include('When I perform an action')
+      expect(feature_content).to include('Then I see the expected result')
+    end
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Steps content (Cucumber)
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded steps' do
+    it 'has frozen_string_literal' do
+      expect(steps_content).to have_frozen_string_literal
+    end
+
+    it 'has valid Ruby syntax' do
+      expect(steps_content).to have_valid_ruby_syntax
+    end
+
+    it 'requires the page object' do
+      expect(steps_content).to include("require_relative '../../page_objects/pages/checkout'")
+    end
+
+    it 'has Given/When/Then blocks' do
+      expect(steps_content).to include("Given('I am on the checkout page')")
+      expect(steps_content).to include("When('I perform an action')")
+      expect(steps_content).to include("Then('I see the expected result')")
+    end
+
+    it 'has pending steps' do
+      expect(steps_content).to include("pending 'implement step'")
+    end
+  end
+
+  shared_examples 'selenium scaffolded steps' do
+    it 'instantiates page with driver' do
+      expect(steps_content).to include('CheckoutPage.new(driver)')
+    end
+
+    it 'does not use capybara visit' do
+      expect(steps_content).not_to match(/^\s+visit '/)
+    end
+  end
+
+  shared_examples 'capybara scaffolded steps' do
+    it 'uses visit for Given step' do
+      expect(steps_content).to include("visit 'checkout'")
+    end
+
+    it 'does not instantiate with driver' do
+      expect(steps_content).not_to include('.new(driver)')
+    end
+  end
+
+  shared_examples 'watir scaffolded steps' do
+    it 'instantiates page with browser' do
+      expect(steps_content).to include('CheckoutPage.new(browser)')
+    end
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Helper content
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded helper' do
+    it 'has frozen_string_literal' do
+      expect(helper_content).to have_frozen_string_literal
+    end
+
+    it 'has valid Ruby syntax' do
+      expect(helper_content).to have_valid_ruby_syntax
+    end
+
+    it 'defines helper module' do
+      expect(helper_content).to include('module CheckoutHelper')
+    end
+
+    it 'has helper placeholder comment' do
+      expect(helper_content).to include('# Add your helper code here')
+    end
+  end
+
+  # ──────────────────────────────────────────────
+  # Shared examples: Component content
+  # ──────────────────────────────────────────────
+
+  shared_examples 'valid scaffolded component' do
+    it 'has frozen_string_literal' do
+      expect(component_content).to have_frozen_string_literal
+    end
+
+    it 'has valid Ruby syntax' do
+      expect(component_content).to have_valid_ruby_syntax
+    end
+
+    it 'inherits from Component' do
+      expect(component_content).to include('class Sidebar < Component')
+    end
+
+    it 'requires abstract component' do
+      expect(component_content).to include("require_relative '../abstract/component'")
+    end
+  end
+
+  shared_examples 'selenium scaffolded component' do
+    it 'has driver.find_element example' do
+      expect(component_content).to include('driver.find_element')
+    end
+
+    it 'has private section' do
+      expect(component_content).to include('private')
+    end
+
+    it 'has content method' do
+      expect(component_content).to include('def content')
+    end
+  end
+
+  shared_examples 'capybara scaffolded component' do
+    it 'has find(.selector) example' do
+      expect(component_content).to include("find('.selector')")
+    end
+
+    it 'has no private section' do
+      expect(component_content).not_to include('private')
+    end
+
+    it 'does not have driver.find_element' do
+      expect(component_content).not_to include('driver.find_element')
+    end
+  end
+
+  shared_examples 'watir scaffolded component' do
+    it 'has browser.element example' do
+      expect(component_content).to include('browser.element')
+    end
+
+    it 'has private section' do
+      expect(component_content).to include('private')
+    end
+
+    it 'has content method' do
+      expect(component_content).to include('def content')
+    end
+  end
+
+  # ══════════════════════════════════════════════
+  # Test matrix: automation × framework
+  # ══════════════════════════════════════════════
+
+  WEB_AUTOMATIONS.each do |automation|
+    TEST_FRAMEWORKS.each do |framework|
+      style = scaffold_style(framework)
+
+      context "with #{framework} and #{automation}" do # rubocop:disable RSpec/ContextWording
+        let(:scaffold) { ScaffoldingCommands }
+
+        # Use absolute path so Dir.chdir is safe regardless of current CWD
+        project_dir = build_mock_project(automation, framework)
+
+        before do
+          Dir.chdir(project_dir)
+        end
+
+        after do
+          Dir.chdir(File.dirname(project_dir))
+        end
+
+        after(:all) do # rubocop:disable RSpec/BeforeAfterAll
+          FileUtils.rm_rf(project_dir)
+        end
+
+        # ── Default scaffold ───────────────────
+
+        describe 'default scaffold' do
+          before do
+            scaffold.new.invoke(:scaffold, nil, %w[checkout])
+          end
+
+          after do
+            FileUtils.rm_f('page_objects/pages/checkout.rb')
+            FileUtils.rm_f('spec/checkout_page_spec.rb')
+            if framework == 'cucumber'
+              FileUtils.rm_f('features/checkout.feature')
+              FileUtils.rm_f('features/step_definitions/checkout_steps.rb')
+            else
+              FileUtils.rm_rf('features')
+              FileUtils.rm_rf('spec') unless framework == 'rspec'
+            end
+          end
+
+          it 'creates page object' do
+            expect(Pathname.new('page_objects/pages/checkout.rb')).to be_file
+          end
+
+          if style == :spec
+            it 'creates spec file' do
+              expect(Pathname.new('spec/checkout_page_spec.rb')).to be_file
+            end
+
+            it 'does not create feature file' do
+              expect(Pathname.new('features/checkout.feature')).not_to be_file
+            end
+          else # :feature
+            it 'creates feature file' do
+              expect(Pathname.new('features/checkout.feature')).to be_file
+            end
+
+            it 'creates steps file' do
+              expect(Pathname.new('features/step_definitions/checkout_steps.rb')).to be_file
+            end
+          end
+
+          # Page content validation
+          let(:page_content) { File.read('page_objects/pages/checkout.rb') }
+
+          include_examples 'valid scaffolded page'
+          include_examples "#{automation} scaffolded page"
+
+          # Test content validation (depends on scaffold style)
+          if style == :spec
+            let(:spec_content) { File.read('spec/checkout_page_spec.rb') }
+            include_examples 'valid scaffolded spec'
+            include_examples "#{automation} scaffolded spec"
+          else # :feature
+            let(:feature_content) { File.read('features/checkout.feature') }
+            include_examples 'valid scaffolded feature'
+
+            let(:steps_content) { File.read('features/step_definitions/checkout_steps.rb') }
+            include_examples 'valid scaffolded steps'
+            include_examples "#{automation} scaffolded steps"
+          end
+        end
+
+        # ── Component scaffold ─────────────────
+
+        describe 'component scaffold' do
+          before do
+            scaffold.new.invoke(:component, nil, %w[sidebar])
+          end
+
+          after do
+            FileUtils.rm_f('page_objects/components/sidebar.rb')
+          end
+
+          let(:component_content) { File.read('page_objects/components/sidebar.rb') }
+
+          include_examples 'valid scaffolded component'
+          include_examples "#{automation} scaffolded component"
+        end
+
+        # ── Helper scaffold ────────────────────
+
+        describe 'helper scaffold' do
+          before do
+            scaffold.new.invoke(:helper, nil, %w[checkout])
+          end
+
+          after do
+            FileUtils.rm_f('helpers/checkout_helper.rb')
+          end
+
+          let(:helper_content) { File.read('helpers/checkout_helper.rb') }
+
+          include_examples 'valid scaffolded helper'
+        end
+
+        # ── CRUD scaffold ──────────────────────
+        # CrudGenerator checks Dir.exist?('features'), Dir.exist?('test') separately.
+
+        describe 'CRUD scaffold' do
+          before do
+            scaffold.new.invoke(:scaffold, nil, %w[product --crud])
+          end
+
+          after do
+            %w[product_list product_create product_detail product_edit].each do |page|
+              FileUtils.rm_f("page_objects/pages/#{page}.rb")
+              FileUtils.rm_f("spec/#{page}_page_spec.rb")
+              FileUtils.rm_f("features/#{page}.feature")
+              FileUtils.rm_f("features/step_definitions/#{page}_steps.rb")
+            end
+            FileUtils.rm_rf('features') unless framework == 'cucumber'
+            FileUtils.rm_rf('spec') unless framework == 'rspec'
+            FileUtils.rm_f('models/data/product.yml')
+          end
+
+          it 'creates pages for all CRUD actions' do
+            %w[product_list product_create product_detail product_edit].each do |page|
+              expect(Pathname.new("page_objects/pages/#{page}.rb")).to be_file
+            end
+          end
+
+          it 'creates model data file' do
+            expect(Pathname.new('models/data/product.yml')).to be_file
+          end
+
+          it 'model data has expected sections' do
+            content = File.read('models/data/product.yml')
+            expect(content).to include('default:')
+            expect(content).to include('valid:')
+            expect(content).to include('invalid:')
+          end
+
+          if framework == 'cucumber'
+            it 'creates feature files for all CRUD actions' do
+              %w[product_list product_create product_detail product_edit].each do |page|
+                expect(Pathname.new("features/#{page}.feature")).to be_file
+              end
+            end
+
+            it 'creates step files for all CRUD actions' do
+              %w[product_list product_create product_detail product_edit].each do |page|
+                expect(Pathname.new("features/step_definitions/#{page}_steps.rb")).to be_file
+              end
+            end
+          elsif framework == 'rspec'
+            it 'creates spec files for all CRUD actions' do
+              %w[product_list product_create product_detail product_edit].each do |page|
+                expect(Pathname.new("spec/#{page}_page_spec.rb")).to be_file
+              end
+            end
+          else # minitest — CrudGenerator checks test/ and generates specs
+            it 'creates spec files for all CRUD actions' do
+              %w[product_list product_create product_detail product_edit].each do |page|
+                expect(Pathname.new("spec/#{page}_page_spec.rb")).to be_file
+              end
+            end
+          end
+
+          it 'all CRUD pages have valid Ruby syntax' do
+            %w[product_list product_create product_detail product_edit].each do |page|
+              content = File.read("page_objects/pages/#{page}.rb")
+              expect(content).to have_valid_ruby_syntax
+            end
+          end
+
+          it 'all CRUD pages have frozen_string_literal' do
+            %w[product_list product_create product_detail product_edit].each do |page|
+              content = File.read("page_objects/pages/#{page}.rb")
+              expect(content).to have_frozen_string_literal
+            end
+          end
+        end
+
+        # ── Selective --with ───────────────────
+
+        describe 'selective scaffold' do
+          after do
+            %w[settings payment order].each do |name|
+              FileUtils.rm_f("page_objects/pages/#{name}.rb")
+              FileUtils.rm_f("spec/#{name}_page_spec.rb")
+              FileUtils.rm_f("helpers/#{name}_helper.rb")
+              FileUtils.rm_f("models/data/#{name}.yml")
+            end
+            FileUtils.rm_rf('features') unless framework == 'cucumber'
+            FileUtils.rm_rf('spec') unless framework == 'rspec'
+          end
+
+          it 'generates only page when --with page' do
+            scaffold.new.invoke(:scaffold, nil, %w[settings --with page])
+            expect(Pathname.new('page_objects/pages/settings.rb')).to be_file
+            expect(Pathname.new('spec/settings_page_spec.rb')).not_to be_file
+            expect(Pathname.new('features/settings.feature')).not_to be_file
+          end
+
+          it 'generates page and helper with --with page helper' do
+            scaffold.new.invoke(:scaffold, nil, %w[payment --with page helper])
+            expect(Pathname.new('page_objects/pages/payment.rb')).to be_file
+            expect(Pathname.new('helpers/payment_helper.rb')).to be_file
+          end
+
+          it 'generates model data with --with model' do
+            scaffold.new.invoke(:scaffold, nil, %w[order --with model])
+            expect(Pathname.new('models/data/order.yml')).to be_file
+          end
+        end
+
+        # ── Destroy ────────────────────────────
+
+        describe 'destroy' do
+          it 'removes scaffolded files' do
+            scaffold.new.invoke(:scaffold, nil, %w[temp_item])
+            expect(Pathname.new('page_objects/pages/temp_item.rb')).to be_file
+
+            scaffold.new.invoke(:destroy, nil, %w[temp_item])
+            expect(Pathname.new('page_objects/pages/temp_item.rb')).not_to be_file
+
+            if style == :spec
+              expect(Pathname.new('spec/temp_item_page_spec.rb')).not_to be_file
+            else
+              expect(Pathname.new('features/temp_item.feature')).not_to be_file
+              expect(Pathname.new('features/step_definitions/temp_item_steps.rb')).not_to be_file
+            end
+          end
+        end
+
+        # ── Batch scaffold ─────────────────────
+
+        describe 'batch scaffold' do
+          after do
+            %w[search filter].each do |name|
+              FileUtils.rm_f("page_objects/pages/#{name}.rb")
+              FileUtils.rm_f("spec/#{name}_page_spec.rb")
+              FileUtils.rm_f("features/#{name}.feature")
+              FileUtils.rm_f("features/step_definitions/#{name}_steps.rb")
+            end
+            FileUtils.rm_rf('features') unless framework == 'cucumber'
+            FileUtils.rm_rf('spec') unless framework == 'rspec'
+          end
+
+          it 'generates multiple scaffolds at once' do
+            scaffold.new.invoke(:scaffold, nil, %w[search filter])
+            expect(Pathname.new('page_objects/pages/search.rb')).to be_file
+            expect(Pathname.new('page_objects/pages/filter.rb')).to be_file
+
+            if style == :spec
+              expect(Pathname.new('spec/search_page_spec.rb')).to be_file
+              expect(Pathname.new('spec/filter_page_spec.rb')).to be_file
+            else
+              expect(Pathname.new('features/search.feature')).to be_file
+              expect(Pathname.new('features/filter.feature')).to be_file
+            end
+          end
+        end
+
+        # ── Name normalization ─────────────────
+
+        describe 'name normalization' do
+          after do
+            %w[cart shopping_cart checkout].each do |name|
+              FileUtils.rm_f("page_objects/pages/#{name}.rb")
+            end
+          end
+
+          it 'strips _page suffix' do
+            scaffold.new.invoke(:page, nil, %w[cart_page])
+            expect(Pathname.new('page_objects/pages/cart.rb')).to be_file
+          end
+
+          it 'converts CamelCase to snake_case' do
+            scaffold.new.invoke(:page, nil, %w[ShoppingCart])
+            expect(Pathname.new('page_objects/pages/shopping_cart.rb')).to be_file
+          end
+
+          it 'handles CamelCase with Page suffix' do
+            scaffold.new.invoke(:page, nil, %w[CheckoutPage])
+            expect(Pathname.new('page_objects/pages/checkout.rb')).to be_file
+          end
+        end
+
+        # ── Relationships ──────────────────────
+
+        describe 'relationships' do
+          before do
+            File.write('page_objects/pages/login.rb', "class LoginPage < Page; end\n")
+          end
+
+          after do
+            FileUtils.rm_f('page_objects/pages/dashboard.rb')
+            FileUtils.rm_f('spec/dashboard_page_spec.rb')
+            FileUtils.rm_f('features/dashboard.feature')
+            FileUtils.rm_f('features/step_definitions/dashboard_steps.rb')
+            FileUtils.rm_f('page_objects/pages/login.rb')
+            FileUtils.rm_rf('features') unless framework == 'cucumber'
+            FileUtils.rm_rf('spec') unless framework == 'rspec'
+          end
+
+          it 'adds require_relative for dependent page' do
+            scaffold.new.invoke(:page, nil, %w[dashboard --uses login])
+            content = File.read('page_objects/pages/dashboard.rb')
+            expect(content).to include("require_relative 'login'")
+          end
+
+          if style == :spec
+            it 'adds dependency to spec let declarations' do
+              scaffold.new.invoke(:spec, nil, %w[dashboard --uses login])
+              content = File.read('spec/dashboard_page_spec.rb')
+              expect(content).to include('LoginPage')
+
+              case automation
+              when 'selenium' then expect(content).to include('LoginPage.new(driver)')
+              when 'watir'    then expect(content).to include('LoginPage.new(browser)')
+              when 'capybara' then expect(content).to include('LoginPage.new')
+              end
+            end
+          end
+        end
+
+        # ── Template overrides ─────────────────
+
+        describe 'template overrides' do
+          after do
+            FileUtils.rm_rf('.ruby_raider')
+            FileUtils.rm_f('page_objects/pages/custom_override.rb')
+            FileUtils.rm_f('page_objects/pages/default_fallback.rb')
+          end
+
+          it 'uses override template when present' do
+            FileUtils.mkdir_p('.ruby_raider/templates')
+            File.write('.ruby_raider/templates/page_object.tt', <<~ERB)
+              # frozen_string_literal: true
+
+              class <%= page_class_name %> < Page
+                # E2E_CUSTOM_MARKER
+              end
+            ERB
+
+            scaffold.new.invoke(:page, nil, %w[custom_override])
+            content = File.read('page_objects/pages/custom_override.rb')
+            expect(content).to include('E2E_CUSTOM_MARKER')
+            expect(content).to include('class CustomOverridePage < Page')
+          end
+
+          it 'falls back to default template without override' do
+            scaffold.new.invoke(:page, nil, %w[default_fallback])
+            content = File.read('page_objects/pages/default_fallback.rb')
+            expect(content).not_to include('E2E_CUSTOM_MARKER')
+            expect(content).to include('class DefaultFallbackPage < Page')
+          end
+        end
+
+        # ── Dry run ────────────────────────────
+
+        describe 'dry run' do
+          it 'does not create files with --dry-run' do
+            expect do
+              scaffold.new.invoke(:page, nil, %w[phantom --dry-run])
+            end.to output(/phantom/).to_stdout
+
+            expect(Pathname.new('page_objects/pages/phantom.rb')).not_to be_file
+          end
+        end
+      end
+    end
+  end
+end

data/spec/scaffolding/scaffold_project_detector_spec.rb

@@ -87,6 +87,44 @@ RSpec.describe ScaffoldProjectDetector do
     end
   end
 
+  describe '.validate_project' do
+    it 'warns when Gemfile is missing' do
+      warnings = described_class.validate_project
+      expect(warnings).to include(match(/Gemfile not found/))
+    end
+
+    it 'warns when config/config.yml is missing' do
+      File.write('Gemfile', "gem 'rspec'\n")
+      warnings = described_class.validate_project
+      expect(warnings).to include(match(/config\.yml not found/))
+    end
+
+    it 'returns no warnings for valid project' do
+      File.write('Gemfile', "gem 'rspec'\n")
+      FileUtils.mkdir_p('config')
+      File.write('config/config.yml', "browser: chrome\n")
+      expect(described_class.validate_project).to be_empty
+    end
+  end
+
+  describe '.config' do
+    it 'returns empty hash when config missing' do
+      expect(described_class.config).to eq({})
+    end
+
+    it 'parses valid config' do
+      FileUtils.mkdir_p('config')
+      File.write('config/config.yml', "browser: chrome\nurl: http://localhost\n")
+      expect(described_class.config).to eq({ 'browser' => 'chrome', 'url' => 'http://localhost' })
+    end
+
+    it 'raises Error on malformed YAML' do
+      FileUtils.mkdir_p('config')
+      File.write('config/config.yml', "browser: chrome\n  bad:\nindent")
+      expect { described_class.config }.to raise_error(ScaffoldProjectDetector::Error, /invalid YAML syntax/)
+    end
+  end
+
   describe '.detect' do
     before do
       File.write('Gemfile', "gem 'selenium-webdriver'\ngem 'rspec'\n")

data/spec/utilities/headless_config_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+require 'erb'
+
+RSpec.describe 'Headless config support in driver templates' do
+  let(:tmp_dir) { 'tmp_headless_test' }
+
+  before do
+    FileUtils.mkdir_p(tmp_dir)
+    Dir.chdir(tmp_dir)
+  end
+
+  after do
+    Dir.chdir('..')
+    FileUtils.rm_rf(tmp_dir)
+  end
+
+  describe 'selenium driver template' do
+    it 'checks config headless key' do
+      content = File.read(File.expand_path('../../lib/generators/templates/helpers/partials/selenium_driver.tt',
+                                           __dir__))
+      expect(content).to include("@config['headless']")
+    end
+
+    it 'checks ENV HEADLESS' do
+      content = File.read(File.expand_path('../../lib/generators/templates/helpers/partials/selenium_driver.tt',
+                                           __dir__))
+      expect(content).to include("ENV['HEADLESS']")
+    end
+  end
+
+  describe 'capybara helper template' do
+    it 'checks config headless key' do
+      content = File.read(File.expand_path('../../lib/generators/templates/helpers/capybara_helper.tt', __dir__))
+      expect(content).to include("config['headless']")
+    end
+  end
+
+  describe 'browser helper template (watir)' do
+    it 'checks config headless key' do
+      content = File.read(File.expand_path('../../lib/generators/templates/helpers/browser_helper.tt', __dir__))
+      expect(content).to include("config['headless']")
+    end
+  end
+
+  describe 'headless via config.yml' do
+    it 'config key is used when YAML has headless: true' do
+      FileUtils.mkdir_p('config')
+      File.write('config/config.yml', <<~YAML)
+        browser: chrome
+        headless: true
+        browser_arguments:
+          chrome:
+            - no-sandbox
+      YAML
+
+      config = YAML.load_file('config/config.yml')
+      args = config['browser_arguments'][config['browser']]
+
+      # Simulate the template logic
+      args += ['--headless'] if (ENV['HEADLESS'] || config['headless']) && !args.include?('--headless')
+
+      expect(args).to include('--headless')
+    end
+
+    it 'config key is not used when headless: false' do
+      FileUtils.mkdir_p('config')
+      File.write('config/config.yml', <<~YAML)
+        browser: chrome
+        headless: false
+        browser_arguments:
+          chrome:
+            - no-sandbox
+      YAML
+
+      config = YAML.load_file('config/config.yml')
+      args = config['browser_arguments'][config['browser']]
+
+      # Temporarily clear ENV to isolate config behavior
+      original_env = ENV.delete('HEADLESS')
+      args += ['--headless'] if (ENV['HEADLESS'] || config['headless']) && !args.include?('--headless')
+      ENV['HEADLESS'] = original_env if original_env
+
+      expect(args).not_to include('--headless')
+    end
+  end
+end

data/spec/utilities/utilities_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+require_relative '../../lib/utilities/utilities'
+
+RSpec.describe Utilities do
+  let(:tmp_dir) { 'tmp_utilities_test' }
+  let(:config_path) { 'config/config.yml' }
+
+  before do
+    FileUtils.mkdir_p(tmp_dir)
+    Dir.chdir(tmp_dir)
+    FileUtils.mkdir_p('config')
+    File.write(config_path, <<~YAML)
+      browser: chrome
+      url: 'http://localhost:3000'
+      timeout: 10
+      viewport:
+        width: 1920
+        height: 1080
+      browser_arguments:
+        chrome:
+          - no-sandbox
+          - disable-dev-shm-usage
+        firefox:
+          - acceptInsecureCerts
+    YAML
+    # Reset cached config between tests
+    described_class.instance_variable_set(:@config, nil)
+  end
+
+  after do
+    Dir.chdir('..')
+    FileUtils.rm_rf(tmp_dir)
+  end
+
+  describe '.browser_options=' do
+    it 'writes to browser_arguments for the current browser' do
+      described_class.browser_options = %w[no-sandbox headless]
+      config = YAML.load_file(config_path)
+      expect(config['browser_arguments']['chrome']).to eq(%w[no-sandbox headless])
+    end
+
+    it 'writes to the correct browser key when browser is firefox' do
+      described_class.browser = 'firefox'
+      described_class.instance_variable_set(:@config, nil)
+      described_class.browser_options = %w[headless]
+      config = YAML.load_file(config_path)
+      expect(config['browser_arguments']['firefox']).to eq(%w[headless])
+    end
+
+    it 'preserves other browser arguments' do
+      described_class.browser_options = %w[headless]
+      config = YAML.load_file(config_path)
+      expect(config['browser_arguments']['firefox']).to eq(%w[acceptInsecureCerts])
+    end
+  end
+
+  describe '.delete_browser_options' do
+    it 'removes browser_arguments for the current browser' do
+      described_class.delete_browser_options
+      config = YAML.load_file(config_path)
+      expect(config['browser_arguments']['chrome']).to be_nil
+    end
+
+    it 'preserves other browser arguments' do
+      described_class.delete_browser_options
+      config = YAML.load_file(config_path)
+      expect(config['browser_arguments']['firefox']).to eq(%w[acceptInsecureCerts])
+    end
+  end
+
+  describe '.headless=' do
+    it 'sets headless to true' do
+      described_class.headless = true
+      config = YAML.load_file(config_path)
+      expect(config['headless']).to be true
+    end
+
+    it 'sets headless to false' do
+      described_class.headless = true
+      described_class.instance_variable_set(:@config, nil)
+      described_class.headless = false
+      config = YAML.load_file(config_path)
+      expect(config['headless']).to be false
+    end
+  end
+
+  describe '.viewport=' do
+    it 'sets viewport dimensions' do
+      described_class.viewport = '375x812'
+      config = YAML.load_file(config_path)
+      expect(config['viewport']).to eq({ 'width' => 375, 'height' => 812 })
+    end
+  end
+
+  describe '.browser_options= writes to browser_arguments not browser_options' do
+    it 'does not create a browser_options key' do
+      described_class.browser_options = %w[headless]
+      config = YAML.load_file(config_path)
+      expect(config).not_to have_key('browser_options')
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_raider
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Agustin Pequeno
@@ -375,6 +375,7 @@ files:
 - spec/adopter/project_analyzer_spec.rb
 - spec/adopter/project_detector_spec.rb
 - spec/commands/raider_commands_spec.rb
+- spec/commands/scaffolding_commands_spec.rb
 - spec/generators/fixtures/templates/test.tt
 - spec/generators/fixtures/templates/test_partial.tt
 - spec/generators/generator_spec.rb
@@ -409,6 +410,7 @@ files:
 - spec/integration/generators/rspec_generator_spec.rb
 - spec/integration/generators/skip_flags_spec.rb
 - spec/integration/generators/visual_addon_spec.rb
+- spec/integration/scaffolding_e2e_spec.rb
 - spec/integration/settings_helper.rb
 - spec/integration/spec_helper.rb
 - spec/llm/client_spec.rb
@@ -429,6 +431,8 @@ files:
 - spec/system/support/system_test_helper.rb
 - spec/system/watir_spec.rb
 - spec/utilities/desktop_downloader_spec.rb
+- spec/utilities/headless_config_spec.rb
+- spec/utilities/utilities_spec.rb
 homepage: https://github.com/RubyRaider/ruby_raider
 licenses:
 - MIT