ruby_raider 3.11.0 → 3.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e07bc6e38598246845e628bc2f4fde5aff9155fe2a925f7a16465c97b279ba87
-  data.tar.gz: 78a6aa99c1790db921530d5f6da67727ac984bd3452fdb46573b8a97d683bbee
+  metadata.gz: e1312bb43aceb9be9a70d5e3d09e6694d901f6b5dc3ec80f27b6973de6c8d60c
+  data.tar.gz: ad4e86e9f7dd6bbbacac033fe48f18a93d6397040ab29490d0add8456f6ad2cc
 SHA512:
-  metadata.gz: e846e3fc291059fd5fe7571011b99e837819dd0adba93bd20016981b14b3854e76f1094c2e93b0a08590c0158ef362c0af4b3fcc49822bc3ce17644a423fe159
-  data.tar.gz: 788aed67f16f4ef33ceeb98a8a2bdd6e87a5eef7d5fd3b0a941e036fe76b4ed876ec4ca04d74e5d0ef276f12df251a3076e295d4600e7ee06f0c45ed6c6b804c
+  metadata.gz: b913021e191c5ff9fddc114590bc7b6a4a1b0e340a0fb2257da5477c2e3344dcd73088ea1cbac4eb1b28953b7bc3c250d56c648f15e85977088b8d96d3ddbc2b
+  data.tar.gz: c1d12da3f4447bbabecc6638895129dc0dd9d23dc08389a8b9d6ee9077c3936855b28746b9a6d9d049b3ced2c2e296462154c88e1845d6357078bb41ab8f75f6

data/.github/workflows/reek.yml

@@ -15,10 +15,14 @@ jobs:
         with:
           ruby-version: '3.3'
           bundler-cache: true
-          
+
       - name: reek
         uses: reviewdog/action-reek@v1
         with:
           reek_version: gemfile
           reporter: github-pr-review # Default is github-pr-check
           fail_on_error: true
+
+      - name: reek (whole repo)
+        # With a path: bare `reek` reads stdin when there is no terminal, which checks nothing in CI
+        run: bundle exec reek .

data/.github/workflows/release.yml

@@ -61,7 +61,8 @@ jobs:
         run: bundle exec rubocop
 
       - name: Run Reek
-        run: bundle exec reek
+        # With a path: bare `reek` reads stdin when there is no terminal, which checks nothing in CI
+        run: bundle exec reek .
 
       - name: Build gem
         run: |

data/.github/workflows/system_tests.yml

@@ -39,7 +39,7 @@ jobs:
         run: bundle exec rspec spec/system/selenium_spec.rb --format documentation
 
   watir:
-    name: Watir frameworks
+    name: Watir frameworks (deprecated)
     needs: setup
     runs-on: ubuntu-latest
     steps:

data/.reek.yml

@@ -1,3 +1,7 @@
+# setup-ruby's bundler-cache installs gems into vendor/bundle inside the checkout
+exclude_paths:
+  - vendor
+
 detectors:
   Attribute:
     enabled: false
@@ -49,3 +53,12 @@ detectors:
 
   UtilityFunction:
     enabled: false
+
+  # Baseline of warnings that predate whole-repo reek in CI (2026-10-31). Remove an
+  # entry when its code is reworked.
+  MissingSafeMethod:
+    exclude:
+      - 'ScaffoldingCommands' # validate_project! is a Thor command guard; a non-raising twin has no caller
+  TooManyConstants:
+    exclude:
+      - 'RubyRaider::Ffmpeg' # pinned version, release URL and manifest constants

data/.ruby-version

@@ -1 +1 @@
-3.4.1
+3.4.12

data/README.md

@@ -33,10 +33,12 @@ Ruby Raider is a CLI gem for scaffolding and generating UI test automation frame
 
 ### Web Testing
 
-| Test Framework | Selenium | Watir |
-|----------------|----------|-------|
-| RSpec          | ✅       | ✅    |
-| Cucumber       | ✅       | ✅    |
+| Test Framework | Selenium | Watir (deprecated) |
+|----------------|----------|--------------------|
+| RSpec          | ✅       | ✅                 |
+| Cucumber       | ✅       | ✅                 |
+
+Watir is deprecated and will be removed in the next major version of ruby_raider (4.0); new projects should use Selenium. It is no longer offered in the interactive menu and is available only through `-p automation:watir` until 4.0. See [Migrating from Watir](#migrating-from-watir).
 
 ### Mobile Testing (Appium)
 
@@ -61,6 +63,8 @@ Every generated project comes with:
 - **Page Object Model** — Base page and component classes with example pages
 - **Test examples** — Working login tests against the [Raider Test Store](https://raider-test-site.onrender.com/)
 - **Raider reporting** — RSpec and Cucumber projects include [raider_reporter](https://github.com/RaiderHQ/raider_reporter), which writes results to `raider-results/` and uploads runs to your Raider Hideout server when `RAIDER_TOKEN` and `RAIDER_ENDPOINT` are set; generated CI runs the suite through `raider-reporter exec` with `RAIDER_QUARANTINE`, so quarantined tests do not fail the build; an opt-in `raider-gate` job (`RAIDER_GATE=1`) fails CI when the Raider quality gate fails
+- **Waiting** — generated Selenium and Appium projects wait for elements by themselves (`WaitHelper` and `RaiderElement`): `click`, `send_keys`, `text` and the rest poll until the element is ready, and `eventually { … }` retries assertions, so there is no implicit wait and no `sleep`; `timeout` in `config.yml` sets how long to wait
+- **Example tests or a skeleton (`examples:false`)** — start from the working login examples, or pass `examples:false` for an empty skeleton with the helpers, config, CI and README (see [Getting Started](#getting-started))
 - **Login reuse** — generated web projects (Selenium or Watir) log in once and restore the saved session for examples tagged `:logged_in` (RSpec) or `@logged_in` (Cucumber); `RAIDER_LOGIN_STATE=off|refresh` and `login_state: max_age:` control it, and the state stays in git-ignored `.raider/auth/`
 - **Failure video replay** — Every test is recorded and the video is kept only for failing tests, attached to the report as `video` (WebM from page screenshots for Selenium and Watir, Appium's own MP4 for mobile, which needs `ffmpeg` on the Appium server host for iOS and for Android recordings over 180 s). Turn it off per run with `VIDEO=off`, or per project with `raider u video off`; ffmpeg is downloaded once, SHA-256 checked and cached in `~/.cache/raider`. The RaiderHQ `ffmpeg-7.1` build that the download uses is not published yet, so for now set `RAIDER_FFMPEG_PATH` to an ffmpeg with libvpx to get web videos
 - **GitHub Actions CI** — Ready-to-use test pipeline that caches ffmpeg for failure videos
@@ -118,6 +122,41 @@ raider new my_project -p framework:rspec automation:selenium ci:azure
 Azure Pipelines for mobile (Appium) projects is not available yet: with `ci:azure` no pipeline file is generated and a notice is printed.
 Azure Repos ignores `pr:` triggers, so add the pipeline as a Build validation branch policy to get pull request builds.
 
+Generate an empty skeleton, without the example pages and tests (the menu asks `Do you want example tests?`):
+
+```bash
+raider new my_project -p framework:rspec automation:selenium examples:false
+```
+
+The skeleton keeps the helpers, config, CI and README, and its empty suite passes; grow it with `raider g`. Watir projects always include the examples.
+
+## Migrating from Watir
+
+Watir is deprecated; to move a Watir project to Selenium, generate a Selenium project and port your pages. The common mappings:
+
+| Watir | Selenium project (waiting layer) |
+|-------|----------------------------------|
+| `browser.goto(url)` | `driver.navigate.to(url)` |
+| `browser.text_field(id: 'x').set(v)` | `clear({ id: 'x' })` and `send_keys({ id: 'x' }, v)` |
+| `browser.button(id: 'x').click` | `click({ id: 'x' })` |
+| `Watir.default_timeout = n` | `timeout: n` in `config/config.yml` |
+
+## Adopting waiting in an existing project
+
+Gem upgrades do not rewrite generated code, so existing projects keep their implicit wait until you opt in:
+
+1. Copy both `helpers/wait_helper.rb` and `helpers/raider_element.rb` from a freshly generated project into your
+   `helpers/` folder. Keep them side by side: `wait_helper.rb` loads the other with `require_relative 'raider_element'`.
+2. Include it in `Page`, the spec helper, or the World, after loading it with `require_relative`, for example
+   `require_relative '../../helpers/wait_helper'` at the top of `page_objects/abstract/page.rb`.
+3. Set how long it waits: add `timeout: 10` to `config/config.yml`. Single-platform mobile projects (iOS or Android
+   only) have no `config/config.yml`, so pass `timeout:` to a call, or create `config/config.yml` with that line;
+   without either, it waits 10 seconds.
+4. Remove the `implicit_wait` line.
+5. Move flaky spots to `click`, `send_keys` and `eventually` first.
+
+Keep in mind that keeping the implicit wait while using the layer makes every `find` miss cost up to `timeout` seconds per poll cycle, so remove it once you have moved over.
+
 ## Commands
 
 ###### Anything between square brackets ([...]) is where your input goes

data/lib/commands/utility_commands.rb

@@ -90,7 +90,7 @@ class UtilityCommands < Thor
 
   desc 'start_appium', 'It starts the appium server'
   def start_appium
-    system 'appium  --base-path /wd/hub'
+    system 'appium'
   end
 
   desc 'desktop', 'Downloads the Raider Desktop GUI application'

data/lib/generators/automation/automation_generator.rb

@@ -4,31 +4,36 @@ require_relative '../generator'
 
 class AutomationGenerator < Generator
   def generate_automation_files
+    generate_appium_settings if mobile?
+    generate_abstract_component unless mobile?
+    examples? ? generate_examples : generate_empty_folders
+    generate_abstract_page
+  end
+
+  private
+
+  def generate_examples
     if mobile?
-      generate_appium_settings
       generate_home_page
       generate_pdp_page
     else
-      generate_components
+      generate_header_component
       generate_model_files
       generate_pages
     end
-
-    generate_abstract_page
   end
 
-  private
+  # A skeleton keeps the folders for the pages and components it will grow with `raider g`
+  def generate_empty_folders
+    create_file("#{name}/page_objects/pages/.keep", '')
+    create_file("#{name}/page_objects/components/.keep", '') unless mobile?
+  end
 
   def generate_pages
     generate_login_page
     generate_account_page
   end
 
-  def generate_components
-    generate_abstract_component
-    generate_header_component
-  end
-
   def generate_model_files
     generate_model_factory
     generate_model_data

data/lib/generators/automation/templates/appium_caps.tt

@@ -18,14 +18,13 @@ browserstack:
   platformName: Android
   os_version: '9.0'
   deviceName: Google Pixel 3
-  app: app: <%= ENV['APP_URL'] %>
+  app: <%= ENV['APP_URL'] %>
   browserstack.user: <%= ENV['BROWSERSTACK_USER'] %>
   browserstack.key: <%= ENV['BROWSERSTACK_KEY'] %>
   project: 'RaiderTestApp'
   name: 'RaiderTestApp-Android'
 <% elsif ios? %>platformName: iOS
 appium:options:
-  url: http://localhost:4723/wd/hub
   platformVersion: '17.0'
   deviceName: iPhone 15
   automationName: XCUITest
@@ -43,7 +42,6 @@ browserstack:
   name: 'RaiderTestApp-IOS'
 <% elsif android? %>platformName: Android
 appium:options:
-  url: http://localhost:4723/wd/hub
   platformVersion: '14'
   automationName: UiAutomator2
   deviceName: Pixel 8 API 34
@@ -53,7 +51,7 @@ browserstack:
   platformName: Android
   os_version: '9.0'
   deviceName: Google Pixel 3
-  app: app: <%= ENV['APP_URL'] %>
+  app: <%= ENV['APP_URL'] %>
   browserstack.user: <%= ENV['BROWSERSTACK_USER'] %>
   browserstack.key: <%= ENV['BROWSERSTACK_KEY'] %>
   project: 'RaiderTestApp'

data/lib/generators/automation/templates/home.tt

@@ -3,11 +3,10 @@
 require_relative '../abstract/page'
 
 class Home < Page
-
   # Actions
 
   def go_to_product_detail
-    driver.wait { first_product }.click
+    tap(first_product)
   end
 
   private

data/lib/generators/automation/templates/login.tt

@@ -11,9 +11,9 @@ class Login < Page
 
 <%- if selenium_based? -%>
   def login(username, password)
-    username_field.send_keys username
-    password_field.send_keys password
-    login_button.click
+    send_keys(username_field, username)
+    send_keys(password_field, password)
+    click(login_button)
   end
   alias log_as login
 <%- else -%>
@@ -30,7 +30,7 @@ class Login < Page
 
   def username_field
 <%- if selenium_based? -%>
-    driver.find_element(id: 'loginFrm_loginname')
+    { id: 'loginFrm_loginname' }
 <%- else -%>
     browser.text_field(id: 'loginFrm_loginname')
 <%- end -%>
@@ -38,7 +38,7 @@ class Login < Page
 
   def password_field
 <%- if selenium_based? -%>
-    driver.find_element(id: 'loginFrm_password')
+    { id: 'loginFrm_password' }
 <%- else -%>
     browser.text_field(id: 'loginFrm_password')
 <%- end -%>
@@ -46,7 +46,7 @@ class Login < Page
 
   def login_button
 <%- if selenium_based? -%>
-    driver.find_element(xpath: "//button[@title='Login']")
+    { xpath: "//button[@title='Login']" }
 <%- else -%>
     browser.button(xpath: "//button[@title='Login']")
 <%- end -%>

data/lib/generators/automation/templates/page.tt

@@ -1,26 +1,38 @@
-<%- if web? -%>
+# frozen_string_literal: true
+
+<%- if web? && examples? -%>
 require_relative '../components/header'
 <%- end -%>
+<%- if wait_helper? -%>
+require_relative '../../helpers/wait_helper'
+<%- end -%>
 
 class Page
 <%- if cross_platform? -%>
   include AppiumHelper
 <%- end -%>
-<%=- partial('initialize_selector', trim: false) -%>
-<%=- partial('visit_method', trim: false) -%>
-<%=- partial('url_methods', trim: false) -%>
+<%- if wait_helper? -%>
+  include WaitHelper
+<%- end -%>
+<%- if cross_platform? || wait_helper? -%>
+
+<%- end -%>
+<%= partial('initialize_selector') -%>
+<%= partial('visit_method') -%>
+<%= partial('url_methods') -%>
 
   def to_s
     self.class.to_s.sub('Page', ' Page')
   end
+  <%- if selenium_based? && examples? -%>
 
-  <%- if selenium_based? -%>
   # Components
 
   def header
-    Header.new(driver.find_element(css: '.welcome-msg'))
+    Header.new(find_element(css: '.welcome-msg'))
   end
   <%- elsif watir? -%>
+
   # Components
 
   def header

data/lib/generators/automation/templates/partials/home_page_selector.tt

@@ -1,8 +1,6 @@
-<%- if ios? -%>
-driver.find_element(accessibility_id: 'product-item-1')
-<%- elsif android? -%>
-driver.find_element(accessibility_id: 'product-item-1')
+<%- if cross_platform? -%>
+{ ios: { accessibility_id: 'product-item-1' },
+      android: { accessibility_id: 'product-item-1' } }
 <%- else -%>
-element(ios: { accessibility_id: 'product-item-1' },
-            android: { accessibility_id: 'product-item-1' })
+{ accessibility_id: 'product-item-1' }
 <%- end -%>

data/lib/generators/automation/templates/partials/initialize_selector.tt

@@ -1,13 +1,13 @@
-<% if watir? %>
+<%- if watir? -%>
   attr_reader :browser
 
   def initialize(browser)
     @browser = browser
   end
-<% else %>
+<%- else -%>
   attr_reader :driver
 
   def initialize(driver)
     @driver = driver
   end
-<% end %>
+<%- end -%>

data/lib/generators/automation/templates/partials/pdp_page_selector.tt

@@ -1,8 +1,6 @@
-<%- if ios? -%>
-driver.find_element(accessibility_id: 'add-to-cart-button')
-<%- elsif android? -%>
-driver.find_element(accessibility_id: 'add-to-cart-button')
+<%- if cross_platform? -%>
+{ ios: { accessibility_id: 'add-to-cart-button' },
+      android: { accessibility_id: 'add-to-cart-button' } }
 <%- else -%>
-element(ios: { accessibility_id: 'add-to-cart-button' },
-            android: { accessibility_id: 'add-to-cart-button' })
+{ accessibility_id: 'add-to-cart-button' }
 <%- end -%>

data/lib/generators/automation/templates/partials/url_methods.tt

@@ -1,4 +1,5 @@
-<% if web? %>
+<%- if web? -%>
+
   def full_url(*page)
     "#{base_url}#{url(*page)}"
   end
@@ -10,4 +11,4 @@
   def url(_page)
     raise 'Url must be defined on child pages'
   end
-<% end %>
+<%- end -%>

data/lib/generators/automation/templates/partials/visit_method.tt

@@ -1,11 +1,11 @@
-<% if web? %>
-<% if selenium_based? %>
+<%- if selenium_based? -%>
+
   def visit(*page)
     @driver.navigate.to full_url(page.first)
   end
-<% else %>
+<%- elsif watir? -%>
+
   def visit(*page)
     @browser.goto full_url(page.first)
   end
-<% end %>
-<% end %>
+<%- end -%>

data/lib/generators/automation/templates/pdp.tt

@@ -1,11 +1,12 @@
+# frozen_string_literal: true
+
 require_relative '../abstract/page'
 
 class Pdp < Page
-
   # Actions
 
   def add_to_cart_text
-    driver.wait { add_to_cart_button }.text
+    text(add_to_cart_button)
   end
 
   private

data/lib/generators/cucumber/cucumber_generator.rb

@@ -4,14 +4,27 @@ require_relative '../generator'
 
 class CucumberGenerator < Generator
   def generate_feature
+    return unless examples?
+
     template('feature.tt', "#{name}/features/#{template_name}.feature")
   end
 
   def generate_steps
+    return unless examples?
+
     template('steps.tt', "#{name}/features/step_definitions/#{template_name}_steps.rb")
   end
 
+  # A skeleton keeps an empty step_definitions/ for the steps it will grow with `raider g steps`
+  def generate_empty_steps_folder
+    return if examples?
+
+    create_file("#{name}/features/step_definitions/.keep", '')
+  end
+
   def generate_user_factory
+    return unless examples?
+
     template('user_factory.tt', "#{name}/models/user_factory.rb")
   end
 
@@ -28,18 +41,18 @@ class CucumberGenerator < Generator
   end
 
   def generate_accessibility_feature
-    return unless axe_addon? && web?
+    return unless axe_addon? && web? && examples?
 
     template('accessibility_feature.tt', "#{name}/features/accessibility.feature")
   end
 
   def generate_accessibility_steps
-    return unless axe_addon? && web?
+    return unless axe_addon? && web? && examples?
 
     template('accessibility_steps.tt', "#{name}/features/step_definitions/accessibility_steps.rb")
   end
 
   def template_name
-    @template_name ||= (@_initializer.first & %w[android ios cross_platform]).empty? ? 'login' : 'home'
+    @template_name ||= mobile? ? 'home' : 'login'
   end
 end

data/lib/generators/cucumber/templates/env.tt

@@ -1,7 +1,7 @@
 <%- if selenium_based? -%>
-  <%= partial('selenium_env') -%>
+<%= partial('selenium_env') -%>
 <%- elsif mobile? -%>
-  <%= partial('appium_env') -%>
+<%= partial('appium_env') -%>
 <%- else -%>
-  <%= partial('watir_env') -%>
+<%= partial('watir_env') -%>
 <%- end -%>

data/lib/generators/cucumber/templates/partials/driver_world.tt

@@ -1,9 +1,18 @@
 require_relative '../../helpers/driver_helper'
+<%- if wait_helper? -%>
+require_relative '../../helpers/wait_helper'
+<%- end -%>
 <%- if selenium_based? -%>
+<%- if examples? -%>
 require_relative '../../models/user_factory'
+<%- end -%>
 
 World(DriverHelper)
+World(WaitHelper)
 <%- else -%>
 
 World(DriverHelper)
+<%- if wait_helper? -%>
+World(WaitHelper)
+<%- end -%>
 <%- end -%>

data/lib/generators/cucumber/templates/partials/mobile_steps.tt

@@ -16,5 +16,5 @@ end
 
 Then("I'm redirected to the product details page") do
   pdp_page = Pdp.new(driver)
-  expect(pdp_page.add_to_cart_text).to eq 'Add to Cart'
+  eventually { expect(pdp_page.add_to_cart_text).to eq 'Add to Cart' }
 end

data/lib/generators/cucumber/templates/partials/selenium_env.tt

@@ -9,9 +9,11 @@ require 'tmpdir'
 require 'yaml'
 require_relative '../../helpers/video_helper'
 require_relative '../../helpers/session_state'
+<%- if examples? -%>
 require_relative '../../models/user_factory'
 require_relative '../../page_objects/pages/account'
 require_relative '../../page_objects/pages/login'
+<%- end -%>
 
 Before do
   viewport = YAML.load_file('config/config.yml')['viewport']
@@ -24,6 +26,7 @@ Before do
   @video_recorder.start
 end
 
+<%- if examples? -%>
 Before('@logged_in') do
   user = UserFactory.for('registered user')
   account = Account.new(driver)
@@ -36,6 +39,7 @@ Before('@logged_in') do
   end
 end
 
+<%- end -%>
 After do |scenario|
   video_path = @video_recorder&.stop(keep: scenario.failed?)
   RaiderReporter.attach('video', video_path, type: :webm) if video_path

data/lib/generators/cucumber/templates/partials/web_steps.tt

@@ -20,5 +20,9 @@ end
 Then("I'm logged in") do
   account_page = <% if watir? %>Account.new(browser)<% else %>Account.new(driver)<% end %>
   account_page.visit
+<%- if watir? -%>
   expect(account_page.header.customer_name).to eq "Welcome back #{@user['name']}"
+<%- else -%>
+  eventually { expect(account_page.header.customer_name).to eq "Welcome back #{@user['name']}" }
+<%- end -%>
 end

data/lib/generators/cucumber/templates/steps.tt

@@ -1,5 +1,5 @@
 <%- if web? -%>
-<%= partial('web_steps', strip: true) -%>
+<%= partial('web_steps', strip: true) %>
 <%- else -%>
-<%= partial('mobile_steps', strip: true) -%>
+<%= partial('mobile_steps', strip: true) %>
 <%- end -%>

data/lib/generators/cucumber/templates/user_factory.tt

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'model_factory'
 
 class UserFactory < ModelFactory

data/lib/generators/cucumber/templates/world.tt

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 <%- if watir? -%>
-<%=- partial('watir_world', strip: true) -%>
+<%= partial('watir_world', strip: true) %>
 <%- else -%>
-<%=- partial('driver_world', strip: true) -%>
-<%- end -%>
+<%= partial('driver_world', strip: true) %>
+<%- end -%>