ruby_raider 3.8.0 → 3.10.0

data/lib/generators/infrastructure/templates/azure_pipelines.tt

@@ -12,7 +12,9 @@ pool:
 
 variables:
   HEADLESS: 'true'
-  # Add RAIDER_TOKEN (secret) and RAIDER_ENDPOINT as pipeline variables.
+  # Where ffmpeg for failure videos is cached between runs.
+  RAIDER_CACHE_DIR: $(Pipeline.Workspace)/.cache/raider
+  # Add RAIDER_TOKEN (secret) and RAIDER_ENDPOINT (your Raider Hideout URL) as pipeline variables.
 
 jobs:
   - job: tests
@@ -21,6 +23,15 @@ jobs:
         inputs: { versionSpec: '3.4' }
       - script: bundle install
         displayName: Install gems
+      - task: Cache@2
+        displayName: Cache ffmpeg for failure videos
+        inputs:
+          key: 'raider-ffmpeg-<%= RubyRaider::Ffmpeg::MANIFEST[:version] %> | "$(Agent.OS)" | Gemfile.lock'
+          path: $(RAIDER_CACHE_DIR)
+      # Video is optional: a failed download is visible here but never fails the build.
+      - script: bundle exec raider u video install
+        displayName: Install ffmpeg for failure videos
+        continueOnError: true
       - script: <%- if cucumber? -%>bundle exec raider-reporter exec -- bundle exec cucumber features/ --format pretty<%- else -%>bundle exec raider-reporter exec -- bundle exec rspec spec/ --format documentation<%- end %>
         displayName: Run tests
         env:
@@ -31,7 +42,7 @@ jobs:
         condition: always()
         inputs: { targetPath: raider-results, artifact: raider-results-$(System.JobPositionInPhase)-$(System.JobAttempt) }
   - job: raider_comment
-    dependsOn: tests
+    dependsOn: [tests, raider_gate]
     condition: and(always(), eq(variables['Build.Reason'], 'PullRequest'))
     steps:
       - task: UseRubyVersion@0
@@ -43,3 +54,16 @@ jobs:
           RAIDER_TOKEN: $(RAIDER_TOKEN)
           RAIDER_ENDPOINT: $(RAIDER_ENDPOINT)
           SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+  - job: raider_gate
+    dependsOn: tests
+    condition: and(always(), eq(variables['RAIDER_GATE'], '1'))
+    steps:
+      - task: UseRubyVersion@0
+        inputs: { versionSpec: '3.4' }
+      - script: bundle install
+      - script: bundle exec raider-reporter gate
+        displayName: Wait for the Raider quality gate
+        env:
+          RAIDER_TOKEN: $(RAIDER_TOKEN)
+          RAIDER_ENDPOINT: $(RAIDER_ENDPOINT)
+          SYSTEM_ACCESSTOKEN: $(System.AccessToken)

data/lib/generators/infrastructure/templates/github.tt

@@ -33,8 +33,20 @@ jobs:
         with:
           chrome-version: stable
 
+      - name: Cache ffmpeg for failure videos
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/raider
+          key: raider-ffmpeg-<%= RubyRaider::Ffmpeg::MANIFEST[:version] %>-${{ runner.os }}-${{ hashFiles('**/Gemfile.lock') }}
+
+      - name: Install ffmpeg for failure videos
+        run: bundle exec raider u video install
+        # Video is optional: a failed download is visible here but never fails the build.
+        continue-on-error: true
+
       - name: Run tests
         run: <%- if framework == 'cucumber' -%>bundle exec raider-reporter exec -- bundle exec cucumber features --format pretty<%- else -%>bundle exec raider-reporter exec -- bundle exec rspec spec --format documentation<%- end %>
+        # RAIDER_ENDPOINT: your Raider Hideout URL (repository variable); RAIDER_TOKEN: a project token (secret).
         env:
           HEADLESS: true
           RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
@@ -50,7 +62,7 @@ jobs:
           if-no-files-found: ignore
 
   raider-comment:
-    needs: [build]
+    needs: [build, raider-gate]
     if: always() && github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     permissions:
@@ -67,3 +79,21 @@ jobs:
           RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
           RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  raider-gate:
+    needs: [build]
+    if: always() && vars.RAIDER_GATE == '1'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: 3.4.0, bundler-cache: true }
+      - name: Wait for the Raider quality gate
+        run: bundle exec raider-reporter gate
+        env:
+          RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
+          RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/lib/generators/infrastructure/templates/github_appium.tt

@@ -44,17 +44,33 @@ jobs:
           appium &
           sleep 5
 
+      - name: Cache ffmpeg for failure videos
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/raider
+          key: raider-ffmpeg-<%= RubyRaider::Ffmpeg::MANIFEST[:version] %>-${{ runner.os }}-${{ hashFiles('**/Gemfile.lock') }}
+
+      - name: Install ffmpeg for failure videos
+        run: bundle exec raider u video install
+        # Video is optional: a failed download is visible here but never fails the build.
+        continue-on-error: true
+
       - name: Run tests
 <%- if cucumber? -%>
         run: bundle exec raider-reporter exec -- bundle exec cucumber features/ --format pretty
 <%- else -%>
         run: bundle exec raider-reporter exec -- bundle exec rspec spec/ --format documentation
 <%- end -%>
+        # RAIDER_ENDPOINT: your Raider Hideout URL (repository variable); RAIDER_TOKEN: a project token (secret).
         env:
           APP_PATH: ${{ github.workspace }}/apps/RaiderTestApp.app
           RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
           RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
           RAIDER_QUARANTINE: "1"
+<%- if cross_platform? -%>
+          RAIDER_SHARD_INDEX: "1"
+          RAIDER_SHARD_TOTAL: "2"
+<%- end -%>
 
       - name: Upload Raider results
         uses: actions/upload-artifact@v4
@@ -97,6 +113,17 @@ jobs:
           appium &
           sleep 5
 
+      - name: Cache ffmpeg for failure videos
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/raider
+          key: raider-ffmpeg-<%= RubyRaider::Ffmpeg::MANIFEST[:version] %>-${{ runner.os }}-${{ hashFiles('**/Gemfile.lock') }}
+
+      - name: Install ffmpeg for failure videos
+        run: bundle exec raider u video install
+        # Video is optional: a failed download is visible here but never fails the build.
+        continue-on-error: true
+
       - name: Run Android Emulator and Tests
         uses: reactivecircus/android-emulator-runner@v2
         with:
@@ -115,6 +142,10 @@ jobs:
           RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
           RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
           RAIDER_QUARANTINE: "1"
+<%- if cross_platform? -%>
+          RAIDER_SHARD_INDEX: "2"
+          RAIDER_SHARD_TOTAL: "2"
+<%- end -%>
 
       - name: Upload Raider results
         uses: actions/upload-artifact@v4
@@ -126,7 +157,7 @@ jobs:
 <%- end -%>
 
   raider-comment:
-    needs: [<%= [('ios-tests' if ios? || cross_platform?), ('android-tests' if android? || cross_platform?)].compact.join(', ') %>]
+    needs: [<%= [('ios-tests' if ios? || cross_platform?), ('android-tests' if android? || cross_platform?)].compact.join(', ') %>, raider-gate]
     if: always() && github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     permissions:
@@ -143,3 +174,21 @@ jobs:
           RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
           RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  raider-gate:
+    needs: [<%= [('ios-tests' if ios? || cross_platform?), ('android-tests' if android? || cross_platform?)].compact.join(', ') %>]
+    if: always() && vars.RAIDER_GATE == '1'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: 3.4.0, bundler-cache: true }
+      - name: Wait for the Raider quality gate
+        run: bundle exec raider-reporter gate
+        env:
+          RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
+          RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/lib/generators/invoke_generators.rb

@@ -1,3 +1,4 @@
+require 'thor'
 require_relative 'infrastructure/github_generator'
 require_relative 'infrastructure/azure_generator'
 require_relative 'automation/automation_generator'
@@ -7,11 +8,15 @@ require_relative 'helper_generator'
 require_relative 'rspec/rspec_generator'
 
 module InvokeGenerators
-  class InvalidParameters < ArgumentError; end
+  FRAMEWORKS = %w[rspec cucumber].freeze
+  AUTOMATIONS = %w[selenium watir ios android cross_platform].freeze
 
   module_function
 
   def generate_framework(structure = {})
+    structure = normalise_options(structure)
+    validate_option(:framework, structure[:framework], FRAMEWORKS)
+    validate_option(:automation, structure[:automation], AUTOMATIONS)
     validate_ci(structure[:ci])
     generators = %w[Automation Common Helpers]
     framework = structure[:framework]
@@ -30,10 +35,23 @@ module InvokeGenerators
     print_mobile_azure_notice(structure)
   end
 
+  def normalise_options(structure)
+    structure.merge(
+      framework: structure[:framework].to_s.downcase,
+      automation: structure[:automation].to_s.downcase
+    )
+  end
+
+  def validate_option(key, value, allowed)
+    return if allowed.include?(value.to_s)
+
+    raise Thor::Error, "Invalid #{key} #{value.to_s.inspect}. Allowed values: #{allowed.join(', ')}"
+  end
+
   def validate_ci(provider)
     return if [nil, '', 'github', 'azure'].include?(provider&.to_s)
 
-    raise InvalidParameters, 'ci must be github or azure'
+    raise Thor::Error, 'ci must be github or azure'
   end
 
   def print_mobile_azure_notice(structure)

data/lib/generators/rspec/rspec_generator.rb

@@ -20,5 +20,4 @@ class RspecGenerator < Generator
 
     template('accessibility_spec.tt', "#{name}/spec/accessibility_spec.rb")
   end
-
 end

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

@@ -13,7 +13,7 @@ gem 'parallel_split_test'
 gem 'parallel_tests'
 gem 'rake'
 gem 'reek'
-gem 'raider_reporter', '~> 0.8'
+gem 'raider_reporter', '~> 0.10'
 <%- if rspec? -%>
 gem 'rspec-retry'
 <%- end -%>

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

@@ -1,4 +1,7 @@
 raider-results
 <%- if rspec? -%>
 spec/examples.txt
+<%- end -%>
+<%- if cucumber? -%>
+rerun.txt
 <%- end -%>

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

@@ -1 +1,6 @@
 platform: :ios
+
+video:
+  enabled: true
+  fps: 5
+  max_width: 1280

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

@@ -13,4 +13,9 @@ browser_arguments:
     - search-engine-choice-country
   firefox:
     - acceptInsecureCerts
-    - no-sandbox
+    - no-sandbox
+
+video:
+  enabled: true
+  fps: 5
+  max_width: 1280

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

@@ -93,11 +93,13 @@ Every run writes machine-readable results to `raider-results/` (including `run.j
 `features/support/env.rb` requires `raider_reporter/cucumber`, so no extra Cucumber formatter flag is needed.
 <%- end -%>
 
-To upload runs to Raider, set these environment variables before running the suite:
+To upload runs to Raider, set these environment variables before running the suite.
+`RAIDER_TOKEN` and `RAIDER_ENDPOINT` come from your Raider Hideout server (its setup page, or `bin/rails hideout:setup` /
+`hideout:token`):
 
 ```bash
 export RAIDER_TOKEN=your-token
-export RAIDER_ENDPOINT=https://your-raider-endpoint
+export RAIDER_ENDPOINT=https://hideout.example.com
 ```
 
 <%- if rspec? -%>
@@ -108,6 +110,62 @@ Without `RAIDER_TOKEN`, nothing is uploaded and the suite output is unchanged. F
 report and to Raider. See the [raider_reporter README](https://github.com/RaiderHQ/raider_reporter) for details.
 <%- end -%>
 
+### Video replay
+
+Every test is recorded, and the video is kept only for failing tests<%= rspec? ? ' (on the last retry attempt)' : '' %>. It is attached
+to the report as `video` and saved under `raider-results/attachments/`, next to the failure screenshot.
+<%- if mobile? -%>
+Appium records the device screen and the video is attached as `video.mp4`.
+<%- else -%>
+The video is a `video.webm` built from page screenshots with ffmpeg.
+<%- end -%>
+
+<%- if single_platform? -%>
+- Turn video off for one run with `VIDEO=off bundle exec <%= rspec? ? 'rspec' : 'cucumber' %>`, or for the project with
+  `raider u video off`, which creates `config/config.yml` with a `video:` section (`raider u video on` turns it back
+  on).
+<%- else -%>
+- Video is on by default: `video:` in `config/config.yml` (`enabled: true`, `fps: 5`, `max_width: 1280`).
+- Turn it off for one run with `VIDEO=off bundle exec <%= rspec? ? 'rspec' : 'cucumber' %>`, or for the project with
+  `raider u video off` (`raider u video on` turns it back on).
+<%- end -%>
+<%- unless mobile? -%>
+- ffmpeg is downloaded on first use, checked against a pinned SHA-256 and cached in `~/.cache/raider`
+  (`%LOCALAPPDATA%\raider` on Windows). `raider u video install` downloads it ahead of time (CI does this before the
+  tests and caches the folder), and `raider u video status` prints the binary in use.
+- `RAIDER_FFMPEG_PATH` uses your own ffmpeg (it needs libvpx) instead of the download, and `RAIDER_CACHE_DIR` moves
+  the cache.
+<%- if azure? -%>
+- `azure-pipelines.yml` sets `RAIDER_CACHE_DIR` to `$(Pipeline.Workspace)/.cache/raider`, the folder its `Cache@2`
+  step keeps between runs.
+<%- end -%>
+- The RaiderHQ `ffmpeg-7.1` release that the download comes from is not published yet. Until it is, set
+  `RAIDER_FFMPEG_PATH` to get videos; without it the suite runs as usual and prints one `[video]` line.
+- If ffmpeg is missing or recording fails, the suite still runs and its exit code is unchanged; you get one `[video]`
+  line on stderr and no video.
+- Known limits: a frame is taken after each page load, click and text change, plus one at the end of a failing test,
+  so changes the page makes on its own between actions show up in the next frame. There is one recorded driver per
+  process.
+<%- else -%>
+- Appium's screen recording needs `ffmpeg` on the Appium server host's `PATH` (this machine only when Appium runs
+  here): always for iOS (XCUITest), and for Android when a recording is longer than 180 s. Without it, recording
+  fails with one `[video]` line and the tests run as usual.
+<%- if cross_platform? -%>
+- Each test records for at most 1800 s on iOS and 180 s on Android, so Android needs no ffmpeg on the Appium host.
+<%- elsif ios? -%>
+- Each test records for at most 1800 s.
+<%- else -%>
+- Each test records for at most 180 s, so the Appium host needs no ffmpeg; longer tests keep only their first 180 s.
+<%- end -%>
+  Set `time_limit` (seconds) under `video:` in `config/config.yml`<%= single_platform? ? ' (create it if it is missing)' : '' %> to change it; on Android, more
+  than 180 s needs ffmpeg on the Appium host.
+- `raider u video install` and `raider u video status` manage the ffmpeg that web projects use, cached in
+  `~/.cache/raider` (override with `RAIDER_FFMPEG_PATH` or `RAIDER_CACHE_DIR`); they do not install ffmpeg on the
+  Appium host. The RaiderHQ `ffmpeg-7.1` release it comes from is not published yet.
+- If recording fails, the suite still runs and its exit code is unchanged; you get one `[video]` line on stderr and
+  no video.
+<%- end -%>
+
 <%- unless azure? && mobile? -%>
 ### Quarantine
 
@@ -115,6 +173,26 @@ CI runs the suite through `bundle exec raider-reporter exec -- …` with `RAIDER
 Raider still run and are still reported (as `quarantined`), and a build whose only failures are quarantined stays green.
 Local runs keep quarantine off. To turn it off in CI, remove `RAIDER_QUARANTINE` from the pipeline.
 
+<%- end -%>
+<%- unless azure? && mobile? -%>
+### Quality gate
+
+The `<%= azure? ? 'raider_gate' : 'raider-gate' %>` CI job runs `bundle exec raider-reporter gate` after the tests and
+fails the pipeline when the Raider quality gate fails. It is off until you turn it on:
+
+- set the CI variable `RAIDER_GATE=1` (<%= azure? ? 'a pipeline variable' : 'a repository variable under Settings → Secrets and variables → Actions → Variables' %>);
+- turn on rules under the project's Gate page in Raider: a minimum pass rate, no new failures against the default
+  branch, no new flaky tests;
+- optionally require the `raider/gate` check in branch protection.
+
+`raider-reporter gate` exits 1 when the gate fails, naming the failed rules, and 2 when it gets no verdict (timeout,
+Raider unreachable, token rejected, build not found). `RAIDER_GATE_TIMEOUT` sets how long it waits, in seconds
+(default 600). The job stays off by default because a project without `RAIDER_TOKEN`, or a pull request from a fork,
+would exit 2 on every run.
+
+Parallel test jobs that upload to one build must each set `RAIDER_SHARD_TOTAL` (the number of jobs) and
+`RAIDER_SHARD_INDEX` (1 to that number), so the gate waits for all of them instead of judging the first one to finish.
+
 <%- end -%>
 <%- if azure? && mobile? -%>
 ## CI

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

@@ -3,6 +3,7 @@
 require 'active_support/core_ext/string/inflections'
 require 'yaml'
 require 'watir'
+require_relative 'video_helper'
 
 module BrowserHelper
 
@@ -23,6 +24,9 @@ module BrowserHelper
     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:)
-    Watir::Browser.new(browser_name.to_sym, options: browser_options)
+    arguments = { options: browser_options }
+    listener = VideoHelper.listener
+    arguments[:listener] = listener if listener
+    Watir::Browser.new(browser_name.to_sym, **arguments)
   end
 end

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

@@ -4,6 +4,7 @@ require 'yaml'
 <%- if selenium_based? -%>
 require 'active_support/inflector'
 require 'selenium-webdriver'
+require_relative 'video_helper'
 <%- else -%>
 require 'appium_lib'
 <%- end -%>

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

@@ -1,7 +1,10 @@
   def create_driver(*opts)
     @config = YAML.load_file('config/config.yml')
     browser = @config['browser']
-    driver = Selenium::WebDriver.for(browser.to_sym, options: create_webdriver_options(*opts))
+    arguments = { options: create_webdriver_options(*opts) }
+    listener = VideoHelper.listener
+    arguments[:listener] = listener if listener
+    driver = Selenium::WebDriver.for(browser.to_sym, **arguments)
     driver.manage.timeouts.implicit_wait = @config.fetch('timeout', 10)
     driver
   end

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

@@ -12,6 +12,7 @@ require_relative 'browser_helper'
 <%- else -%>
 require_relative 'driver_helper'
 <%- end -%>
+require_relative 'video_helper'
 
 module SpecHelper
   RSpec.configure do |config|
@@ -45,10 +46,14 @@ module SpecHelper
         browser.window.maximize
       end
     <%- end -%>
+      @video_recorder = VideoHelper.recorder_for(<%= watir? ? 'browser' : 'driver' %>)
+      @video_recorder.start
     end
 
     config.after(:each) do |example|
       example_name = example.description
+      keep_video = example.exception ? VideoHelper.final_attempt?(example) : false
+      video_path = @video_recorder&.stop(keep: keep_video)
       if example.exception
         @_exception = example.exception
         Dir.mktmpdir do |temp_folder|
@@ -57,6 +62,9 @@ module SpecHelper
           RaiderReporter.attach('screenshot', screenshot_path, type: :png)
         end
       end
+      RaiderReporter.attach('video', video_path, type: <%= mobile? ? ':mp4' : ':webm' %>) if video_path
+    ensure
+      @video_recorder&.cleanup
       <%= partial('quit_driver', strip: true) %>
     end
   end