ruby_raider 3.12.1 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1312bb43aceb9be9a70d5e3d09e6694d901f6b5dc3ec80f27b6973de6c8d60c
-  data.tar.gz: ad4e86e9f7dd6bbbacac033fe48f18a93d6397040ab29490d0add8456f6ad2cc
+  metadata.gz: 6e4d2e6fae8f8504215b558818a81660fca9652f52886c6b72f3e1d6850d01bd
+  data.tar.gz: 3a8e5a4290303aab776bce5e6e9e8c86023e88a036b935de18a2c56ded688c8c
 SHA512:
-  metadata.gz: b913021e191c5ff9fddc114590bc7b6a4a1b0e340a0fb2257da5477c2e3344dcd73088ea1cbac4eb1b28953b7bc3c250d56c648f15e85977088b8d96d3ddbc2b
-  data.tar.gz: c1d12da3f4447bbabecc6638895129dc0dd9d23dc08389a8b9d6ee9077c3936855b28746b9a6d9d049b3ced2c2e296462154c88e1845d6357078bb41ab8f75f6
+  metadata.gz: f0af4e104fc9cc2b0a99f0ebd4a996994f16500302e5f1cabf635569de8d404c30bf289ce4df145376fad0579b5cf1dc865cee19fd45e757954aa0ebcd4c75bc
+  data.tar.gz: 67dd60f0a67b57a2cd09605a7aec9b91a822d198ed95c3be94d67663f6aef5b4db0d4b024ef09bd97e764396381d12c0f0b413552efde25f87fac44d57b48d88

data/README.md

@@ -67,6 +67,7 @@ Every generated project comes with:
 - **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
+- **Failure trace replay** (Selenium with RSpec or Cucumber) — Failing tests keep a step-by-step trace: each action with its locator and wait time, a screenshot and the page HTML after every step that changes the page, plus network requests and console messages on Chrome, Edge and Firefox. It is saved as `raider-results/attachments/<n>-trace.zip`, attached to the report as `trace` and opened in Raider Desktop or on Hideout. `TRACE=on` keeps passing tests too, `TRACE=off` captures nothing, and `raider u trace on|off` sets it for the project. Typed values in password fields and `RAIDER_SECRET_*` values are hidden; other typed values, page text and URLs are kept, so treat a trace like the video. Request headers, cookies and bodies are never captured
 - **GitHub Actions CI** — Ready-to-use test pipeline that caches ffmpeg for failure videos
 - **Rake tasks** — Default, smoke, and regression tasks with tag-based filtering
 - **Retry support** — RSpec retry with configurable retry count via `RETRY_COUNT` env var
@@ -204,6 +205,7 @@ raider u platform [PLATFORM]    # Set platform for cross-platform tests
 raider u start_appium           # Start Appium server
 raider u desktop                # Download Raider Desktop
 raider u video [ACTION]         # Failure videos: install (ffmpeg), status, on, off
+raider u trace [on/off]         # Failure traces: turn on or off (Selenium)
 ```
 
 ## Development

data/lib/commands/utility_commands.rb

@@ -123,7 +123,23 @@ class UtilityCommands < Thor
     end
   end
 
+  desc 'trace [on|off]', 'Turns trace capture on or off (writes trace.enabled in config/config.yml)'
+
+  def trace(action)
+    case action
+    when 'on', 'off' then trace_toggle(action == 'on')
+    else
+      say_error "Unknown trace command '#{action}'. Use on|off", :red
+      exit 1
+    end
+  end
+
   no_commands do
+    def trace_toggle(enabled)
+      Utilities.trace_enabled = enabled
+      say "Trace capture #{enabled ? 'enabled' : 'disabled'}", :green
+    end
+
     def video_install
       require_relative '../ruby_raider/ffmpeg'
       path = RubyRaider::Ffmpeg.ensure!

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

@@ -8,6 +8,9 @@ require 'raider_reporter/cucumber'
 require 'tmpdir'
 require 'yaml'
 require_relative '../../helpers/video_helper'
+<%- if trace_helper? -%>
+require_relative '../../helpers/trace_helper'
+<%- end -%>
 require_relative '../../helpers/session_state'
 <%- if examples? -%>
 require_relative '../../models/user_factory'
@@ -15,7 +18,47 @@ require_relative '../../page_objects/pages/account'
 require_relative '../../page_objects/pages/login'
 <%- end -%>
 
-Before do
+<%- if trace_helper? -%>
+# Attempts per scenario across --retry, keyed on the scenario's location, for the trace of each attempt.
+TRACE_ATTEMPTS = Hash.new(0) unless defined?(TRACE_ATTEMPTS)
+
+# Each Gherkin step becomes a group in the trace, named by its keyword and text; hook steps are not steps.
+InstallPlugin do |config, _registry|
+  if defined?(TraceHelper)
+    begin
+      ast_lookup = Cucumber::Formatter::AstLookup.new(config)
+      groups = {}
+      config.on_event(:test_step_started) do |event|
+        next if event.test_step.hook?
+
+        step = event.test_step
+        keyword = begin
+          ast_lookup.step_source(step).step.keyword.strip
+        rescue StandardError
+          nil
+        end
+        location = { file: step.location.file, line: step.location.lines.min }
+        groups[step.id] = TraceHelper.active_recorder&.step_started(name: [keyword, step.text].compact.join(' '), source: location)
+      rescue StandardError => e
+        TraceHelper.disable!("step groups failed: #{e.message}") if defined?(TraceHelper)
+      end
+      config.on_event(:test_step_finished) do |event|
+        next if event.test_step.hook?
+
+        status = %i[passed failed].include?(event.result.to_sym) ? event.result.to_sym : :skipped
+        error = event.result.failed? ? event.result.exception : nil
+        TraceHelper.active_recorder&.step_finished(groups.delete(event.test_step.id), status: status, error: error)
+      rescue StandardError => e
+        TraceHelper.disable!("step groups failed: #{e.message}") if defined?(TraceHelper)
+      end
+    rescue StandardError => e
+      TraceHelper.warn_once("Gherkin step groups unavailable: #{e.message}")
+    end
+  end
+end
+
+<%- end -%>
+Before do<%= trace_helper? ? ' |scenario|' : '' %>
   viewport = YAML.load_file('config/config.yml')['viewport']
   if viewport
     driver.manage.window.resize_to(viewport['width'], viewport['height'])
@@ -24,6 +67,14 @@ Before do
   end
   @video_recorder = VideoHelper.recorder_for(driver)
   @video_recorder.start
+<%- if trace_helper? -%>
+  if defined?(TraceHelper)
+    @trace_attempt = (TRACE_ATTEMPTS[scenario.location.to_s] += 1)
+    @trace_test = { identifier: scenario.location.to_s, full_name: scenario.name, attempt: @trace_attempt }
+    @trace_recorder = TraceHelper.recorder_for(driver)
+    @trace_recorder.start
+  end
+<%- end -%>
 end
 
 <%- if examples? -%>
@@ -41,8 +92,18 @@ end
 
 <%- end -%>
 After do |scenario|
+<%- if trace_helper? -%>
+  if defined?(TraceHelper)
+    keep_trace = TraceHelper.keep_all? || scenario.failed?
+    trace_test = @trace_test&.merge(status: scenario.failed? ? 'failed' : 'passed', error: scenario.exception)
+    trace_path = @trace_recorder&.stop(keep: keep_trace, test: trace_test)
+  end
+<%- end -%>
   video_path = @video_recorder&.stop(keep: scenario.failed?)
   RaiderReporter.attach('video', video_path, type: :webm) if video_path
+<%- if trace_helper? -%>
+  RaiderReporter.attach('trace', trace_path, type: :trace, attempt: @trace_attempt) if trace_path
+<%- end -%>
   if scenario.failed?
     Dir.mktmpdir do |temp_folder|
       screenshot_path = File.join(temp_folder, 'screenshot.png')
@@ -51,6 +112,9 @@ After do |scenario|
     end
   end
 ensure
+<%- if trace_helper? -%>
+  @trace_recorder&.cleanup
+<%- end -%>
   @video_recorder&.cleanup
   driver.quit
 end

data/lib/generators/generator.rb

@@ -73,6 +73,11 @@ class Generator < Thor::Group
     !watir?
   end
 
+  # Selenium web projects record a trace per test; it needs WaitHelper's actions, and mobile has none yet
+  def trace_helper?
+    wait_helper? && !mobile?
+  end
+
   # False for `raider new -p examples:false`: an empty skeleton without the example pages, tests and wiring
   def examples?
     !options_after_name.include?('no_examples')
@@ -90,8 +95,12 @@ class Generator < Thor::Group
     selenium?
   end
 
+  def ruby_raider_version
+    File.read(File.expand_path('../version', __dir__)).strip
+  end
+
   def ruby_raider_version_requirement
-    major, minor = File.read(File.expand_path('../version', __dir__)).strip.split('.')
+    major, minor = ruby_raider_version.split('.')
     "~> #{major}.#{minor}"
   end
 

data/lib/generators/helper_generator.rb

@@ -11,6 +11,7 @@ class HelpersGenerator < Generator
     generate_video_helper
     generate_session_state
     generate_wait_helper
+    generate_trace_helper
   end
 
   private
@@ -50,6 +51,12 @@ class HelpersGenerator < Generator
     template('helpers/raider_element.tt', "#{name}/helpers/raider_element.rb")
   end
 
+  def generate_trace_helper
+    return unless trace_helper?
+
+    template('helpers/trace_helper.tt', "#{name}/helpers/trace_helper.rb")
+  end
+
   def generate_appium_helper
     return unless cross_platform?
 

data/lib/generators/templates/common/gemfile.tt

@@ -14,7 +14,7 @@ gem 'cucumber'
 <%- end -%>
 gem 'parallel_split_test'
 gem 'parallel_tests'
-gem 'raider_reporter', '~> 0.10'
+gem 'raider_reporter', '~> 0.12'
 gem 'rake'
 gem 'reek'
 gem 'rspec'

data/lib/generators/templates/common/partials/web_config.tt

@@ -19,6 +19,13 @@ video:
   enabled: true
   fps: 5
   max_width: 1280
+<%- if trace_helper? -%>
+
+trace:
+  enabled: true      # capture traces; failing tests keep theirs
+  max_steps: 200     # newest steps are kept; older ones lose screenshots and snapshots first
+  max_mb: 20         # the zip stays under this; see Cost
+<%- end -%>
 
 login_state:
   max_age: 3600 # seconds a saved login is reused before logging in again

data/lib/generators/templates/common/read_me.tt

@@ -224,6 +224,9 @@ timeout: 15
 - `headless`: not in the file by default. Add `headless: true`, or set `HEADLESS=true` for one run, to run the
   browser without a window.
 - `video`: failure videos, see [Video replay](#video-replay).
+<%- if trace_helper? -%>
+- `trace`: failing-test traces, see [Trace replay](#trace-replay).
+<%- end -%>
 - `login_state`: how long a saved login is reused, see [Reusing the login](#reusing-the-login).
 <%- end -%>
 
@@ -530,6 +533,10 @@ The wait helper is ordinary code in your project, so you can take it out. To do
 <%- end -%>
 5. Scaffolding (`raider g page` and `raider g component`) then writes plain `driver.find_element` examples on its
    own, because it checks for `helpers/wait_helper.rb`.
+<%- if trace_helper? -%>
+
+Note that without WaitHelper a trace records only navigation and the failure (see [Trace replay](#trace-replay)).
+<%- end -%>
 
 <%- end -%>
 <%- if web? -%>
@@ -674,6 +681,44 @@ The video is a `video.webm` built from page screenshots with ffmpeg.
   no video.
 <%- end -%>
 
+<%- if trace_helper? -%>
+### Trace replay
+
+Every test records a trace, and the trace is kept only for failing tests<%= rspec? ? ' (on the last retry attempt)' : '' %>. A trace is a step-by-step
+record of the test: each action and page load, with the locator, how long it waited, a screenshot and the page HTML
+after it, the network requests, and the browser console. It is saved as `raider-results/attachments/<n>-trace.zip`,
+next to the failure screenshot and video, and attached to the report as `trace`.
+
+- Keep the trace of passing tests too with `TRACE=on bundle exec <%= rspec? ? 'rspec' : 'cucumber' %>`. Capture nothing for one run with
+  `TRACE=off bundle exec <%= rspec? ? 'rspec' : 'cucumber' %>`, or for the project with `raider u trace off` (`raider u trace on` turns it back on).
+  `raider u trace on` and `raider u trace off` write `enabled:` under `trace:` in `config/config.yml`.
+- Open a trace in Raider Desktop, or from the test's page on Hideout when the run is uploaded.
+- Cost: a trace takes one screenshot and one page HTML for every step that changes the page (a click, typing,
+  a page load), including in passing tests, whose traces are then thrown away. If that slows your suite down,
+  switch tracing off as above.
+- Caps, under `trace:` in `config/config.yml`: `max_steps` (200) keeps the newest steps, and `max_mb` (20) keeps the
+  zip under that size. When a cap is reached, the HTML of the oldest steps is dropped first, then their
+  screenshots, then the oldest network and console entries. The last 10 steps always keep theirs.
+- Network requests and console messages are captured only on Chrome, Edge or Firefox. Other browsers, such as
+  Safari, get a trace with steps, screenshots and HTML only. Capture is passive: the trace listens to the browser and
+  never changes a request.
+- The trace helper never fails a test. When it has to leave something out, such as network on a browser without
+  BiDi or a screenshot it could not take, you get at most one `[trace]` notice on stderr for the run. If capturing
+  breaks, you get one more `[trace]` line ending in "tracing disabled for this run", and no more traces for that run.
+
+**Treat a trace like the video: it can contain secrets.** What is hidden: values typed into password fields
+(`type=password`, or an `autocomplete` that contains "password"), and any typed value equal to a `RAIDER_SECRET_*`
+environment variable. Everything else is kept: other typed values, page text, URLs with their query strings, and
+console text. So a secret typed into an ordinary field, or shown on the page, ends up in the trace. Failure messages
+can contain typed text too, because an assertion message is kept as it is. Request headers, cookies and request or
+response bodies are never captured. Do not share or upload traces from runs that handle real credentials.
+
+**Removing the trace helper.** The trace helper is ordinary code in your project. Delete `helpers/trace_helper.rb` and
+the `require_relative` lines that load `trace_helper`: in <%= rspec? ? '`helpers/driver_helper.rb`' : '`helpers/driver_helper.rb` and `features/support/env.rb`' %>. The other lines that use it
+(in <%= rspec? ? '`helpers/spec_helper.rb`' : '`features/support/env.rb`' %> and the driver helper's listeners) only run when `TraceHelper` is defined,
+so they can stay. Remove the `trace:` block from `config/config.yml` if you like.
+
+<%- end -%>
 <%- unless azure? && mobile? -%>
 ### Quarantine
 

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

@@ -5,12 +5,34 @@ require 'yaml'
 require 'active_support/inflector'
 require 'selenium-webdriver'
 require_relative 'video_helper'
+<%- if trace_helper? -%>
+require_relative 'trace_helper'
+<%- end -%>
 <%- else -%>
 require 'appium_lib'
 <%- end -%>
 
 module DriverHelper
   <%- if selenium_based? -%>
+  # Selenium takes one listener: this one hands every event on to the video and trace listeners.
+  class FanOutListener < Selenium::WebDriver::Support::AbstractEventListener
+    def self.for(listeners)
+      listeners.empty? ? nil : new(listeners)
+    end
+
+    def initialize(listeners)
+      super()
+      @listeners = listeners
+    end
+
+    Selenium::WebDriver::Support::AbstractEventListener.instance_methods(false).each do |event|
+      define_method(event) do |*args|
+        @listeners.each { |listener| listener.public_send(event, *args) if listener.respond_to?(event) }
+        nil
+      end
+    end
+  end
+
   def driver(*opts)
     @driver ||= create_driver(*opts)
   end

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

@@ -2,11 +2,19 @@
     @config = YAML.load_file('config/config.yml')
     browser = @config['browser']
     arguments = { options: create_webdriver_options(*opts) }
-    listener = VideoHelper.listener
+    listener = FanOutListener.for(listeners)
     arguments[:listener] = listener if listener
     Selenium::WebDriver.for(browser.to_sym, **arguments)
   end
 
+  # The helpers' Selenium listeners. Deleting video_helper.rb or trace_helper.rb needs only its require.
+  def listeners
+    listeners = []
+    listeners << VideoHelper.listener if defined?(VideoHelper)
+    listeners << TraceHelper.listener if defined?(TraceHelper)
+    listeners.compact
+  end
+
   def browser_arguments(*opts)
     args = opts.empty? ? @config['browser_arguments'][@config['browser']] : opts
     args += ['--headless'] if (ENV['HEADLESS'] || @config['headless']) && !args.include?('--headless')
@@ -18,5 +26,7 @@
     browser = load_browser == 'ie' ? load_browser.upcase : load_browser.capitalize
     options = "Selenium::WebDriver::#{browser}::Options".constantize.new
     browser_arguments(*opts).each { |arg| options.add_argument(arg) }
+    # WebDriver BiDi carries the trace's network and console (chrome, edge and firefox).
+    options.web_socket_url = true if defined?(TraceHelper) && TraceHelper.bidi?(load_browser)
     options
   end

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

@@ -65,13 +65,13 @@ class RaiderElement
   end
 
   def send_keys(*keys, timeout: nil)
-    perform(:send_keys, timeout) { |element| element.send_keys(*keys) }
+    perform(:send_keys, timeout, args: keys) { |element| element.send_keys(*keys) }
     self
   end
 
 <%- unless mobile? -%>
   def select_by(how, what, timeout: nil)
-    perform(:select_by, timeout) { |element| Selenium::WebDriver::Support::Select.new(element).select_by(how, what) }
+    perform(:select_by, timeout, args: [how, what]) { |element| Selenium::WebDriver::Support::Select.new(element).select_by(how, what) }
     self
   end
 
@@ -143,8 +143,8 @@ class RaiderElement
     WaitHelper::Lookup.for(@driver, locator, by, scope: @lookup)
   end
 
-  def perform(action, timeout, &block)
-    waiter(timeout).perform_action(action, @lookup, WaitHelper::Waiter::CHECKS.fetch(action), &block)
+  def perform(action, timeout, args: nil, &block)
+    waiter(timeout).perform_action(action, @lookup, WaitHelper::Waiter::CHECKS.fetch(action), args: args, &block)
   end
 
   def method_missing(name, *args, **options, &block)

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

@@ -62,6 +62,10 @@ module SpecHelper
     <%- end -%>
       @video_recorder = VideoHelper.recorder_for(<%= watir? ? 'browser' : 'driver' %>)
       @video_recorder.start
+<%- if trace_helper? -%>
+      @trace_recorder = TraceHelper.recorder_for(driver) if defined?(TraceHelper)
+      @trace_recorder&.start
+<%- end -%>
     end
 <%- if web? && examples? -%>
 
@@ -80,6 +84,15 @@ module SpecHelper
 
     config.after(:each) do |example|
       example_name = example.description
+<%- if trace_helper? -%>
+      if defined?(TraceHelper)
+        attempt = example.metadata[:retry_attempts].to_i + 1
+        keep_trace = TraceHelper.keep_all? || (example.exception && (defined?(VideoHelper) ? VideoHelper.final_attempt?(example) : true))
+        trace_test = { identifier: example.id.delete_prefix('./'), full_name: example.full_description,
+                       status: example.exception ? 'failed' : 'passed', attempt: attempt, error: example.exception }
+        trace_path = @trace_recorder&.stop(keep: keep_trace, test: trace_test)
+      end
+<%- end -%>
       keep_video = example.exception ? VideoHelper.final_attempt?(example) : false
       video_path = @video_recorder&.stop(keep: keep_video)
       if example.exception
@@ -91,7 +104,13 @@ module SpecHelper
         end
       end
       RaiderReporter.attach('video', video_path, type: <%= mobile? ? ':mp4' : ':webm' %>) if video_path
+<%- if trace_helper? -%>
+      RaiderReporter.attach('trace', trace_path, type: :trace, attempt: attempt) if trace_path
+<%- end -%>
     ensure
+<%- if trace_helper? -%>
+      @trace_recorder&.cleanup
+<%- end -%>
       @video_recorder&.cleanup
       <%= partial('quit_driver', strip: true) %>
     end