ruby_raider 3.9.0 → 3.11.0

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

@@ -1,270 +1,437 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+<%- unless mobile? -%>
+require 'open3'
+require 'selenium-webdriver'
+<%- end -%>
+require 'tmpdir'
 require 'yaml'
-require 'json'
-require 'base64'
 
+# Records each test and keeps the video only when the test fails.
+<%- if mobile? -%>
+# Appium records the device screen natively (mp4).
+<%- else -%>
+# Web tests capture a page screenshot after each navigation, click and text
+# change (FrameListener), plus one final frame, and only failing tests are
+# encoded to WebM with the ffmpeg provisioned by the ruby_raider gem.
+# When no ffmpeg can be obtained, recording is off from the first driver on.
+<%- end -%>
+# Any recorder error prints one [video] warning and turns recording off for
+# the rest of the run; it never raises into a test. VIDEO=off skips recording.
 module VideoHelper
-  VIDEO_DIR = 'videos'
+  DEFAULTS = { 'enabled' => true, 'fps' => 5, 'max_width' => 1280 }.freeze
+<%- unless mobile? -%>
+  MAX_FRAME_SECONDS = 2.0
+  ENCODE_TIMEOUT = 120
+  NO_FFMPEG = 'no ffmpeg available for this platform yet (set RAIDER_FFMPEG_PATH, or run ' \
+              '`raider u video install` once the ffmpeg release is published)'
+<%- end -%>
 
-  module_function
+  @disabled = false
+  @warned = false
+<%- unless mobile? -%>
+  @active_recorder = nil
+  @ffmpeg_obtainable = nil
+<%- end -%>
 
-  def config
-    @config ||= begin
-      yml = YAML.load_file('config/config.yml')
-      yml['video'] || {}
-    rescue StandardError
-      {}
+  class << self
+<%- unless mobile? -%>
+    attr_accessor :active_recorder
+
+<%- end -%>
+    def config
+      @config ||= DEFAULTS.merge(video_config)
     end
-  end
+<%- if mobile? -%>
 
-  def enabled?
-    config.fetch('enabled', false)
-  end
+    # Seconds of device recording per test; video.time_limit in config.yml overrides.
+    def time_limit
+      configured = config['time_limit'].to_i
+      return configured if configured.positive?
 
-  def recorder_for(driver_or_browser)
-    return NullRecorder.new unless enabled?
+      limits = AppiumRecorder::TIME_LIMITS
+      limits.fetch(platform, limits['android'])
+    end
 
-    strategy = config.fetch('strategy', 'auto')
-    case strategy
-    when 'cdp' then CdpRecorder.new(resolve_selenium_driver(driver_or_browser))
-    when 'screen' then ScreenCaptureRecorder.new
-<%- if mobile? -%>
-    when 'appium' then AppiumRecorder.new(driver_or_browser)
+    def platform
+<%- if cross_platform? -%>
+      YAML.load_file('config/config.yml')['platform'].to_s.delete_prefix(':')
+    rescue StandardError
+      ''
+<%- else -%>
+      '<%= android? ? 'android' : 'ios' %>'
 <%- end -%>
-    when 'auto' then auto_detect(driver_or_browser)
-    else NullRecorder.new
     end
-  end
+<%- end -%>
+
+    def enabled?
+      config['enabled'] != false && ENV['VIDEO'] != 'off' && !@disabled
+    end
 
-  def auto_detect(driver_or_browser)
-    sel_driver = resolve_selenium_driver(driver_or_browser)
+    def recorder_for(driver_or_browser)
 <%- if mobile? -%>
-    return AppiumRecorder.new(driver_or_browser) if defined?(Appium::Driver)
+      return NullRecorder.new unless enabled?
+<%- else -%>
+      return NullRecorder.new unless enabled? && ffmpeg_obtainable?
 <%- end -%>
-    return CdpRecorder.new(sel_driver) if chrome_or_edge?(sel_driver)
 
-    if ffmpeg_available?
-      ScreenCaptureRecorder.new
-    else
+<%- if mobile? -%>
+      AppiumRecorder.new(driver_or_browser)
+<%- else -%>
+      FrameRecorder.new(selenium_driver(driver_or_browser))
+<%- end -%>
+    rescue StandardError => e
+      disable!("could not create a recorder: #{e.message}")
       NullRecorder.new
     end
-  end
 
-  def resolve_selenium_driver(obj)
-    if obj.respond_to?(:driver) && !obj.is_a?(Selenium::WebDriver::Driver)
-      obj.driver
-    elsif obj.respond_to?(:browser) && obj.browser.respond_to?(:driver)
-      obj.browser.driver
-    else
-      obj
+    # True when the example passed or no retry is left, so a failed attempt
+    # that will be retried does not pay for an encode. rspec-retry sets
+    # metadata[:retry_attempts] (0-based) before each attempt, and after(:each)
+    # hooks run inside that attempt.
+    def final_attempt?(example)
+      return true unless example.exception
+
+      example.metadata[:retry_attempts].to_i + 1 >= retry_count(example)
     end
-  rescue StandardError
-    obj
-  end
 
-  def chrome_or_edge?(driver)
-    browser_name = driver.capabilities[:browser_name].to_s.downcase
-    %w[chrome chromium msedge edge].any? { |b| browser_name.include?(b) }
-  rescue StandardError
-    false
-  end
+    # A nil reason means the cause was already reported (by RubyRaider::Ffmpeg).
+    def disable!(reason = nil)
+      @disabled = true
+<%- unless mobile? -%>
+      @active_recorder = nil
+<%- end -%>
+      return nil if @warned
 
-  def ffmpeg_available?
-    system('ffmpeg -version > /dev/null 2>&1') ||
-      system('ffmpeg -version > NUL 2>&1')
-  end
+      @warned = true
+      say("#{reason}; recording disabled for this run") if reason
+      nil
+    end
+<%- unless mobile? -%>
 
-  def ensure_video_dir
-    FileUtils.mkdir_p(VIDEO_DIR)
-  end
+    # Passed to Selenium as `listener:` when the driver is created.
+    def listener
+      return nil unless enabled? && ffmpeg_obtainable?
+
+      @listener ||= FrameListener.new
+    end
 
-  # --- CDP Recorder: Chrome/Edge, works headless ---
+    def release(recorder)
+      @active_recorder = nil if @active_recorder.equal?(recorder)
+    end
 
-  class CdpRecorder
-    def initialize(driver)
-      @driver = driver
-      @frames = []
-      @recording = false
+    def fps
+      value = config['fps'].to_f
+      value.positive? ? value : DEFAULTS['fps']
     end
 
-    def start(test_name)
-      @test_name = sanitize(test_name)
-      @frames = []
-      @frame_index = 0
-      @recording = true
-      @driver.execute_cdp('Page.startScreencast',
-                          format: 'jpeg', quality: 60,
-                          maxWidth: 1280, maxHeight: 720,
-                          everyNthFrame: 2)
-      start_frame_collector
-    rescue StandardError => e
-      warn "[video] CDP recording failed to start: #{e.message}"
-      @recording = false
+    def max_width
+      value = config['max_width'].to_i
+      value.positive? ? value : DEFAULTS['max_width']
     end
 
-    def stop
-      return nil unless @recording
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
 
-      @recording = false
-      @driver.execute_cdp('Page.stopScreencast')
-      sleep 0.2 # allow final frames to arrive
-      assemble_video
-    rescue StandardError => e
-      warn "[video] CDP recording failed to stop: #{e.message}"
-      nil
+    # A screenshot while an alert is open would dismiss it, so skip that frame.
+    # An alert opened between this check and the screenshot can still be hit.
+    def alert_open?(driver)
+      driver.switch_to.alert
+      true
+    rescue Selenium::WebDriver::Error::NoSuchAlertError
+      false
+    end
+
+    # frames: [[file name, monotonic time], ...] inside dir. Returns the video path or nil.
+    def encode(dir, frames)
+      ffmpeg = ffmpeg_path
+      return nil unless ffmpeg
+
+      list = File.join(dir, 'list.txt')
+      File.write(list, concat_list(frames))
+      output = File.join(dir, 'video.webm')
+      ok, log = run_ffmpeg(ffmpeg_arguments(ffmpeg, list, output))
+      return output if ok && File.size?(output)
+
+      disable!("ffmpeg could not encode the video: #{log.to_s.strip.lines.last || 'no output'}")
     end
+<%- end -%>
 
     private
 
-    def start_frame_collector
-      @collector = Thread.new do
-        while @recording
-          begin
-            collect_frame
-          rescue StandardError
-            sleep 0.1
-          end
-          sleep 0.05
-        end
+    def video_config
+      video = YAML.load_file('config/config.yml')['video']
+      video.is_a?(Hash) ? video : {}
+    rescue StandardError
+      {}
+    end
+
+    # Same precedence as rspec-retry, which never retries fewer than once.
+    def retry_count(example)
+      configured = ENV['RSPEC_RETRY_RETRY_COUNT'] || example.metadata[:retry] || default_retry_count
+      [configured.to_i, 1].max
+    end
+
+    def default_retry_count
+      RSpec.configuration.respond_to?(:default_retry_count) ? RSpec.configuration.default_retry_count : 0
+    end
+
+    # $stderr.puts, not Kernel#warn: warn is silenced under -W0.
+    # rubocop:disable Style/StderrPuts
+    def say(message)
+      $stderr.puts("[video] #{message}")
+    end
+    # rubocop:enable Style/StderrPuts
+<%- unless mobile? -%>
+
+    # Watir::Browser wraps the Selenium driver.
+    def selenium_driver(driver_or_browser)
+      driver_or_browser.respond_to?(:wd) ? driver_or_browser.wd : driver_or_browser
+    end
+
+    # Decided once per process, at the first listener/recorder_for call, so a run
+    # that can never get an ffmpeg warns at the start and pays no capture cost.
+    def ffmpeg_obtainable?
+      return @ffmpeg_obtainable unless @ffmpeg_obtainable.nil?
+
+      @ffmpeg_obtainable = check_ffmpeg_obtainable
+    end
+
+    def check_ffmpeg_obtainable
+      require 'ruby_raider/ffmpeg'
+      return true if RubyRaider::Ffmpeg.obtainable?
+
+      disable!(NO_FFMPEG)
+      false
+    rescue LoadError, NoMethodError
+      disable!('ruby_raider gem too old for video; update it')
+      false
+    end
+
+    def ffmpeg_path
+      require 'ruby_raider/ffmpeg'
+      RubyRaider::Ffmpeg.ensure! || disable!
+    rescue LoadError
+      disable!('ruby_raider gem too old for video; update it')
+    end
+
+    # Concat demuxer list: each frame lasts until the next one, clamped to
+    # [1/fps, MAX_FRAME_SECONDS], so playback follows the test's real time.
+    def concat_list(frames)
+      shortest = 1.0 / fps
+      lines = frames.each_with_index.flat_map do |(name, time), index|
+        following = frames[index + 1]
+        duration = following ? (following[1] - time).clamp(shortest, MAX_FRAME_SECONDS) : shortest
+        ["file '#{name}'", format('duration %.3f', duration)]
       end
+      (lines << "file '#{frames.last[0]}'").join("\n") << "\n"
     end
 
-    def collect_frame
-      # CDP screencast events are handled by polling via execute_cdp
-      # We capture screenshots at intervals as a reliable alternative
-      VideoHelper.ensure_video_dir
-      frame_path = File.join(VideoHelper::VIDEO_DIR, "#{@test_name}_frame_#{format('%04d', @frame_index)}.jpg")
-      @driver.save_screenshot(frame_path)
-      @frames << frame_path
-      @frame_index += 1
+    def ffmpeg_arguments(ffmpeg, list, output)
+      [ffmpeg, '-y', '-loglevel', 'error', '-f', 'concat', '-safe', '0', '-i', list,
+       '-vf', "scale='min(#{max_width},iw)':-2", '-c:v', 'libvpx', '-deadline', 'realtime',
+       '-b:v', '1M', '-r', format('%g', fps), '-pix_fmt', 'yuv420p', output]
     end
 
-    def assemble_video
-      return nil if @frames.empty?
+    # ffmpeg may exit between the join timeout and the kill.
+    def kill(process)
+      Process.kill('KILL', process.pid)
+    rescue Errno::ESRCH
+      nil
+    end
 
-      @collector&.join(2)
-      VideoHelper.ensure_video_dir
-      output = File.join(VideoHelper::VIDEO_DIR, "#{@test_name}.mp4")
-      pattern = File.join(VideoHelper::VIDEO_DIR, "#{@test_name}_frame_%04d.jpg")
+    def run_ffmpeg(arguments)
+      Open3.popen2e(*arguments) do |stdin, output, process|
+        stdin.close
+        reader = Thread.new { output.read }
+        reader.report_on_exception = false
+        return [process.value.success?, reader.value] if process.join(ENCODE_TIMEOUT)
+
+        kill(process)
+        process.value
+        reader.join(1)
+        [false, "ffmpeg timed out after #{ENCODE_TIMEOUT} seconds"]
+      end
+    end
+<%- end -%>
+  end
+<%- unless mobile? -%>
 
-      system("ffmpeg -y -framerate 10 -i \"#{pattern}\" -c:v libx264 -pix_fmt yuv420p " \
-             "-movflags +faststart -loglevel error \"#{output}\"")
+  # Forwards the state-changing Selenium events to the active FrameRecorder.
+  # One recorded driver per process: every frame goes to the active recorder.
+  class FrameListener < Selenium::WebDriver::Support::AbstractEventListener
+    def after_navigate_to(_url, driver)
+      capture(driver)
+    end
 
-      cleanup_frames
-      File.exist?(output) ? output : nil
+    def after_click(_element, driver)
+      capture(driver)
     end
 
-    def cleanup_frames
-      @frames.each { |f| FileUtils.rm_f(f) }
+    def after_change_value_of(_element, driver)
+      capture(driver)
     end
 
-    def sanitize(name)
-      name.gsub(/[^a-zA-Z0-9_-]/, '_')[0..80]
+    private
+
+    def capture(driver)
+      VideoHelper.active_recorder&.capture(driver)
+      nil
+    rescue StandardError => e
+      VideoHelper.disable!("frame capture failed: #{e.message}")
     end
   end
 
-  # --- Screen Capture Recorder: Any browser, requires FFmpeg + display ---
+  # Saves frames to its own tmpdir; encodes them only when the test failed.
+  class FrameRecorder
+    attr_reader :dir
 
-  class ScreenCaptureRecorder
-    def initialize
+    def initialize(driver)
+      @driver = driver
+      @frames = []
       @recording = false
     end
 
-    def start(test_name)
-      @test_name = sanitize(test_name)
-      VideoHelper.ensure_video_dir
-      @output = File.join(VideoHelper::VIDEO_DIR, "#{@test_name}.mp4")
+    def start
+      @dir = Dir.mktmpdir('raider-video')
+      @frames = []
       @recording = true
+      VideoHelper.active_recorder = self
+      nil
+    rescue StandardError => e
+      VideoHelper.disable!("recording failed to start: #{e.message}")
+      discard
+    end
 
-      input = screen_input
-      @pid = spawn("ffmpeg -y #{input} -r 15 -c:v libx264 -pix_fmt yuv420p " \
-                   "-loglevel error \"#{@output}\"",
-                   %i[out err] => '/dev/null')
+    def capture(driver = @driver)
+      return nil unless @recording && VideoHelper.enabled?
+
+      snap(driver)
     rescue StandardError => e
-      warn "[video] Screen recording failed to start: #{e.message}"
-      @recording = false
+      VideoHelper.disable!("frame capture failed: #{e.message}")
     end
 
-    def stop
+    def stop(keep:)
       return nil unless @recording
 
-      @recording = false
-      Process.kill('INT', @pid)
-      Process.wait(@pid)
-      File.exist?(@output) ? @output : nil
+      final_frame if keep
+      finish
+      return discard unless keep && VideoHelper.enabled? && @frames.any?
+
+      VideoHelper.encode(@dir, @frames) || discard
     rescue StandardError => e
-      warn "[video] Screen recording failed to stop: #{e.message}"
+      finish
+      VideoHelper.disable!("recording failed to stop: #{e.message}")
+      discard
+    end
+
+    def cleanup
+      FileUtils.rm_rf(@dir) if @dir
       nil
+    rescue StandardError => e
+      VideoHelper.disable!("could not remove video frames: #{e.message}")
     end
 
     private
 
-    def screen_input
-      case RbConfig::CONFIG['host_os']
-      when /darwin/i
-        '-f avfoundation -i "1:none"'
-      when /linux/i
-        display = ENV.fetch('DISPLAY', ':99')
-        "-f x11grab -i #{display}"
-      when /mswin|mingw|cygwin/i
-        '-f gdigrab -i desktop'
-      else
-        '-f x11grab -i :0'
-      end
+    def snap(driver)
+      return nil if VideoHelper.alert_open?(driver)
+
+      name = format('frame-%06d.png', @frames.size + 1)
+      time = VideoHelper.monotonic_now
+      driver.save_screenshot(File.join(@dir, name))
+      @frames << [name, time]
+      nil
     end
 
-    def sanitize(name)
-      name.gsub(/[^a-zA-Z0-9_-]/, '_')[0..80]
+    # The browser is often gone after a failure; keep the frames already saved.
+    def final_frame
+      snap(@driver) if VideoHelper.enabled?
+    rescue StandardError
+      nil
     end
-  end
 
-<%- if mobile? -%>
-  # --- Appium Recorder: Mobile, uses native API ---
+    def finish
+      @recording = false
+      VideoHelper.release(self)
+    end
+
+    def discard
+      cleanup
+      nil
+    end
+  end
+<%- else -%>
 
+  # Appium's native screen recording; the mp4 is written as-is. It needs ffmpeg on
+  # the Appium server host for iOS, and for Android recordings over 180 s.
   class AppiumRecorder
+    # Android keeps Appium's 180 s default so it works without ffmpeg on the Appium host.
+    TIME_LIMITS = { 'ios' => 1800, 'android' => 180 }.freeze
+
+    attr_reader :dir
+
     def initialize(driver)
-      @driver = driver
+      # appium_lib's Appium::Driver keeps the recording API on its core driver.
+      @driver = driver.respond_to?(:start_recording_screen) ? driver : driver.driver
       @recording = false
     end
 
-    def start(test_name)
-      @test_name = sanitize(test_name)
+    def start
+      @dir = Dir.mktmpdir('raider-video')
+      @driver.start_recording_screen(time_limit: VideoHelper.time_limit)
       @recording = true
-      @driver.start_recording_screen
+      nil
     rescue StandardError => e
-      warn "[video] Appium recording failed to start: #{e.message}"
-      @recording = false
+      VideoHelper.disable!("recording failed to start: #{e.message}")
+      discard
     end
 
-    def stop
+    def stop(keep:)
       return nil unless @recording
 
       @recording = false
-      video_base64 = @driver.stop_recording_screen
-      VideoHelper.ensure_video_dir
-      output = File.join(VideoHelper::VIDEO_DIR, "#{@test_name}.mp4")
-      File.write(output, Base64.decode64(video_base64), mode: 'wb')
-      output
+      video = @driver.stop_recording_screen
+      return discard unless keep && VideoHelper.enabled? && video && !video.empty?
+
+      path = File.join(@dir, 'video.mp4')
+      File.binwrite(path, video.unpack1('m'))
+      path
     rescue StandardError => e
-      warn "[video] Appium recording failed to stop: #{e.message}"
+      VideoHelper.disable!("recording failed to stop: #{e.message}")
+      discard
+    end
+
+    def cleanup
+      FileUtils.rm_rf(@dir) if @dir
       nil
+    rescue StandardError => e
+      VideoHelper.disable!("could not remove the video: #{e.message}")
     end
 
     private
 
-    def sanitize(name)
-      name.gsub(/[^a-zA-Z0-9_-]/, '_')[0..80]
+    def discard
+      cleanup
+      nil
     end
   end
-
 <%- end -%>
-  # --- Null Recorder: Fallback when recording unavailable ---
 
+  # Used when recording is off or unavailable.
   class NullRecorder
-    def start(_test_name) = nil
+    def start
+      nil
+    end
+
+    def stop(**)
+      nil
+    end
 
-    def stop = nil
+    def cleanup
+      nil
+    end
   end
 end