ruby_raider 4.0.0 → 4.0.1

data/README.md

@@ -31,57 +31,186 @@ Ruby Raider is a CLI gem for scaffolding and generating UI test automation frame
 
 ## Supported Frameworks
 
+Ruby Raider works on Mac OS, Linux and Windows.
+
 ### Web Testing
 
-| Test Framework | Selenium |
-|----------------|----------|
-| RSpec          | ✅       |
+Web projects use **Selenium and RSpec**. They get:
+
+- Locators people see on the page (`label:`, `text:`, `by_role(...)` and more), with strict matching
+- Automatic waiting for elements and actions: no implicit wait, no `sleep`
+- Retrying RSpec matchers
+- Login reuse, failure video, failure trace, network mocking and screenshot comparison
+- Optional accessibility tests (axe) and a choice of GitHub Actions or Azure Pipelines
 
-ruby_raider 4.0 generates Selenium projects with RSpec only. Projects generated by 3.x (Cucumber, Watir) keep working on the 3.x line through the `ruby_raider` pin in their Gemfile (`~> 3.15` or an older `~> 3.x` requirement); 4.0 does not read or convert them.
+See [What's Included](#whats-included) for each one.
 
-### Mobile Testing (Appium)
+### Mobile Testing
+
+Mobile projects use **Appium and RSpec**:
 
 | Test Framework | iOS | Android | Cross-Platform |
 |----------------|-----|---------|----------------|
 | RSpec          | ✅  | ✅      | ✅             |
 
-### Optional Add-on (Web Only)
+They get:
+
+- Appium locators: `accessibility_id:`, `id:`, `xpath:` and `class_name:`
+- Automatic waiting: `find_element` waits for a match, and `click`, `send_keys` and `clear` wait until the element is displayed and enabled
+- Retrying RSpec matchers
+- Gestures: `swipe`, `scroll` and `scroll_to`, on iOS and Android
+- Failure video from Appium's screen recording
+- Raider reporting and a GitHub Actions workflow that starts a simulator or emulator and Appium
+
+On native app screens, `find_element` returns the first match (strict matching is web only) and `submit` is not checked.
+
+To run the examples, download the example [app](https://github.com/RaiderHQ/raider_test_app) and start the server:
+
+```bash
+raider u start_appium
+```
+
+### Optional Add-ons
 
 | Add-on | Flag | Description |
 |--------|------|-------------|
-| Accessibility | `--accessibility` | Adds axe gem + example accessibility tests |
-| CI provider | `-p ci:azure` | Generates `azure-pipelines.yml` instead of the GitHub Actions workflow (default `ci:github`) |
-
-This works on all platforms (Mac OS, Linux and Windows).
+| Accessibility (web) | `--accessibility` | Adds the axe gem and example accessibility tests |
+| CI provider (web) | `-p ci:azure` | Generates `azure-pipelines.yml` instead of the GitHub Actions workflow (default `ci:github`) |
 
 ## What's Included
 
-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** — Generated 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
-- **Locators, waiting and assertions**: The runtime (`ruby_raider/runtime`), loaded by every generated project, adds waiting to Selenium and Appium themselves. Locators go beyond `id` and `css`: `label:`, `placeholder:`, `alt:`, `title:`, `text:`, `test_id:` and `by_role('button', name: 'Save')` find elements the way a person sees them, and `find_element` fails when a locator matches more than one. `find_element` and `find_elements` wait for a match, so there is no implicit wait and no `sleep`. Before an action the runtime waits until the element is ready: `click` waits until it is visible, enabled, not inert, stable and not covered; `send_keys` and `clear` until it is visible, enabled, editable and not inert; `submit` until it is visible, enabled and not inert (on native apps, displayed and enabled); `force: true` skips the checks for one call. `timeout`, `strict` and `actionability` in `config.yml` (or `RAIDER_TIMEOUT`, `RAIDER_STRICT`, `RAIDER_ACTIONABILITY`) set the rules. RSpec matchers (`have_text`, `have_value`, `have_attribute`, `have_css`, `have_xpath`, `be_visible`, `be_hidden`, `be_enabled`, `be_disabled`, `be_checked`, `have_count`, `have_title`, `have_url`, `have_element`) retry until the page matches, and a block expectation such as `expect { driver.find_element(id: 'status').text }.to eq('done')` retries with any value matcher
-- **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) log in once and restore the saved session for examples tagged `:logged_in`; `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, 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) — 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
-- **Network mocking** (Selenium) — Answer a request with your own response or block it, from the test: `mock_request('**/api/users', json: { users: [] })`, `mock_request(url, status: 500)` and `block_request('**/*.png')`, with `calls` to check what the page asked for. It uses WebDriver BiDi on Chrome, Edge and Firefox (Safari and `BIDI=off` raise `NetworkHelper::Unavailable`), handles CORS for cross-origin mocks, clears mocks after each test, and marks mocked requests in the trace
-- **Screenshot comparison** (Selenium) — `match_screenshot('home')` compares the page, or an element with `element:`, with a baseline in `screenshots/baselines/<browser>/`. The first run saves the baseline; later runs fail on a difference and attach the expected, actual and diff pictures to the report and the trace. `SCREENSHOTS=update` rewrites baselines, a missing baseline fails on CI, and tolerances (`threshold`, `max_diff_pixels`, `max_diff_ratio`) go in `config/config.yml` under `screenshots:`. Generate baselines where CI runs: a Retina laptop makes 2x pictures
-- **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
-- **Re-run failed tests** — RSpec keeps `spec/examples.txt` for `--only-failures`
-- **Parallel execution** — parallel_tests and parallel_split_test gems included
-- **Configurable browser** — Chrome/Firefox with customizable arguments, viewport, timeout, and headless mode
-- **Linting** — RuboCop and Reek configs included
-
-For Appium projects, download the example [app](https://github.com/RaiderHQ/raider_test_app) and start the server:
+Every generated project loads the Raider runtime (`ruby_raider/runtime`). It adds locators, waiting and assertions to Selenium and Appium themselves.
 
-```bash
-raider u start_appium
+### Locators
+
+Find elements the way a person sees them, on top of Selenium's `id:`, `css:`, `xpath:`, `name:`, `class:` and `link_text:`:
+
+| Key | Finds |
+|-----|-------|
+| `label:` | the field with that label, `aria-label` or `aria-labelledby` |
+| `placeholder:` | the field with that placeholder |
+| `alt:` | the element with that `alt` text |
+| `title:` | the element with that `title` |
+| `text:` | the innermost element whose text contains it |
+| `test_id:` | the element whose `data-testid` equals it |
+| `by_role(...)` | the element with that ARIA role and name |
+
+```ruby
+driver.find_element(label: 'Email')
+driver.find_element(label: ['Email', { exact: true }])   # whole text only
+driver.find_element(by_role('button', name: 'Save'))
+driver.find_element(by_role('heading', level: 1))
+```
+
+- Text keys match part of the text and ignore extra spaces. Pass `{ exact: true }` for the whole text.
+- `test_id:` reads another attribute with `Raider.test_id_attribute = 'data-qa'` or `RAIDER_TEST_ID_ATTRIBUTE`.
+- **Strict matching:** `find_element` fails with `Raider::AmbiguousMatch` when a locator matches more than one element. `find_elements` never does. Turn it off with `raider u strict off`.
+
+These keys are for web pages. Mobile projects use Appium's locators (see [Mobile Testing](#mobile-testing)).
+
+### Waiting and actionability
+
+- `find_element` and `find_elements` wait for a match. There is no implicit wait and no `sleep`.
+- Before an action, the runtime waits until the element is ready:
+
+| Action | Waits until the element is |
+|--------|----------------------------|
+| `click` | visible, enabled, not inert, stable and not covered |
+| `send_keys`, `clear` | visible, enabled, editable and not inert |
+| `submit` | visible, enabled and not inert |
+
+- `force: true` skips the checks for one call: `button.click(force: true)`.
+- Set the rules with `timeout`, `strict` and `actionability` in `config/config.yml`, or `RAIDER_TIMEOUT`, `RAIDER_STRICT` and `RAIDER_ACTIONABILITY`.
+
+### Assertions
+
+RSpec matchers retry until the page matches or `timeout` runs out:
+
+`have_text`, `have_value`, `have_attribute`, `have_css`, `have_xpath`, `have_element`, `have_count`, `have_title`, `have_url`, `be_visible`, `be_hidden`, `be_enabled`, `be_disabled`, `be_checked`
+
+```ruby
+expect { account_page.welcome_message }.to have_text('Welcome')
+expect { driver.find_element(id: 'status').text }.to eq('done')   # any value matcher retries in a block
 ```
 
+### Raider reporting
+
+Projects include [raider_reporter](https://github.com/RaiderHQ/raider_reporter).
+
+- Results go to `raider-results/`.
+- Runs upload to your Raider Hideout server when `RAIDER_TOKEN` and `RAIDER_ENDPOINT` are set.
+- CI runs the suite through `raider-reporter exec` with `RAIDER_QUARANTINE`, so quarantined tests do not fail the build.
+- Set the CI variable `RAIDER_GATE` to `1` to add a `raider-gate` job that fails CI when the Raider quality gate fails.
+
+### Failure video replay
+
+Each test is recorded. The video is kept only when the test fails and attached to the report as `video`.
+
+- **Web:** WebM built from page screenshots. ffmpeg is downloaded once, SHA-256 checked and cached in `~/.cache/raider`: an LGPL ffmpeg 7.1 build with libvpx for macOS (Apple silicon and Intel), Linux x64 and Windows x64, built by [`.github/workflows/ffmpeg.yml`](.github/workflows/ffmpeg.yml). On other platforms set `RAIDER_FFMPEG_PATH` to an ffmpeg with libvpx.
+- **Mobile:** Appium's own MP4. iOS needs `ffmpeg` on the Appium server host. Android stops at 180 s by default, so it needs no ffmpeg; a longer `video.time_limit` needs ffmpeg too.
+- Turn it off per run with `VIDEO=off`, or per project with `raider u video off`.
+
+### Failure trace replay (web)
+
+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
+- 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 opens in [Raider Desktop](https://ruby-raider.com) or on Hideout.
+
+- `TRACE=on` keeps passing tests too. `TRACE=off` captures nothing. `raider u trace on|off` sets it for the project.
+- 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.
+
+### Network mocking (web)
+
+Answer a request with your own response, or block it:
+
+```ruby
+mock_request('**/api/users', json: { users: [] })
+mock_request(url, status: 500)
+block_request('**/*.png')
+```
+
+- `mock_request` returns the mock; `mock.calls` lists the requests it answered.
+- Works through WebDriver BiDi on Chrome, Edge and Firefox. Safari and `BIDI=off` raise `NetworkHelper::Unavailable`.
+- Handles CORS for cross-origin mocks, clears mocks after each test, and marks mocked requests in the trace.
+
+### Screenshot comparison (web)
+
+```ruby
+match_screenshot('home')
+```
+
+- Compares the page, or one element with `element:`, with a baseline in `screenshots/baselines/<browser>/`.
+- The first run saves the baseline. Later runs fail on a difference and attach the expected, actual and diff pictures to the report and the trace.
+- `SCREENSHOTS=update` rewrites baselines. A missing baseline fails on CI.
+- Tolerances (`threshold`, `max_diff_pixels`, `max_diff_ratio`) go in `config/config.yml` under `screenshots:`.
+- Generate baselines where CI runs: a Retina laptop makes 2x pictures.
+
+### Login reuse (web)
+
+Example projects log in once and restore the saved session for examples tagged `:logged_in`.
+
+- `RAIDER_LOGIN_STATE=off|refresh` and `login_state: max_age:` control it.
+- The state stays in git-ignored `.raider/auth/`.
+- Skeletons (`examples:false`) get `SessionState#reuse` to wire your own login.
+
+### Also included
+
+- **Page Object Model:** base page and component classes with example pages
+- **Example tests:** working tests against the [Raider Test Store](https://raider-test-site.onrender.com/) (web) or the [Raider test app](https://github.com/RaiderHQ/raider_test_app) (mobile), or an empty skeleton with `examples:false` (see [Getting Started](#getting-started))
+- **CI:** GitHub Actions, or Azure Pipelines for web. It caches ffmpeg and comments results on pull requests
+- **Failure screenshots:** each failing test attaches a screenshot to the report
+- **Rake tasks:** default, smoke and regression, filtered by tag
+- **Retries:** RSpec retry, with the count set by `RETRY_COUNT`
+- **Re-run failed tests:** RSpec keeps `spec/examples.txt` for `--only-failures`
+- **Parallel execution:** `parallel_tests` and `parallel_split_test`
+- **Configurable browser:** Chrome or Firefox, with arguments, viewport, timeout and headless mode
+- **Linting:** RuboCop and Reek configs
+
 ## Getting Started
 
 Install the gem:
@@ -102,6 +231,12 @@ Or skip the menu with parameters:
 raider new [project_name] -p framework:rspec automation:selenium
 ```
 
+Create a mobile project (`automation:ios`, `automation:android` or `automation:cross_platform`):
+
+```bash
+raider new my_app -p framework:rspec automation:android
+```
+
 Add accessibility testing:
 
 ```bash

data/RELEASE.md

@@ -2,6 +2,13 @@
 
 ## Release Notes
 
+### 4.0.1
+
+- Failure video works for web projects without `RAIDER_FFMPEG_PATH`: the RaiderHQ `ffmpeg-7.1` release is published and `RubyRaider::Ffmpeg::MANIFEST` pins the SHA-256 of its four binaries (macOS arm64 and x64, Linux x64, Windows x64). The first failing test, or `raider u video install`, downloads the one for your platform, checks it and caches it in `~/.cache/raider` (`%LOCALAPPDATA%\raider` on Windows).
+- The binaries are FFmpeg 7.1.5 built from source by `.github/workflows/ffmpeg.yml` (`.github/ffmpeg/build.sh`): LGPL (no `--enable-gpl`, no `--enable-nonfree`), statically linked with libvpx 1.15.2 and zlib 1.3.1, with only the PNG input, scaling, VP8/VP9 encoding and WebM output that the video helper uses. The release carries the license texts, the source tarballs and the exact configure line. macOS binaries are ad-hoc signed, not notarized (`spctl` rejects them). Gatekeeper only checks files carrying the quarantine attribute, which a browser download gets and the gem's Net::HTTP download does not, so the gem's copy runs; a copy downloaded with a browser would be blocked.
+- On other platforms (Linux arm64, for example) `RAIDER_FFMPEG_PATH` is still the way to get web videos; the `[video]` line now says so.
+- Existing 4.0.0 projects need no change beyond `bundle update ruby_raider`.
+
 ### 4.0.0
 
 - Watir is removed: `automation:watir` is no longer a valid automation value.

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

@@ -746,17 +746,16 @@ The video is a `video.webm` built from page screenshots with ffmpeg.
   `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
+- ffmpeg 7.1 (an LGPL build with libvpx, from the RaiderHQ `ffmpeg-7.1` release) is downloaded on first use,
+  checked against a pinned SHA-256 and cached in `~/.cache/raider` (`%LOCALAPPDATA%\raider` on Windows). Builds exist
+  for macOS (Apple silicon and Intel), Linux x64 and Windows x64. `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.
+- `RAIDER_FFMPEG_PATH` uses your own ffmpeg (it needs libvpx) instead of the download, for example on Linux arm64,
+  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,
@@ -777,7 +776,7 @@ The video is a `video.webm` built from page screenshots with ffmpeg.
   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.
+  Appium host.
 - If recording fails, the suite still runs and its exit code is unchanged; you get one `[video]` line on stderr and
   no video.
 <%- end -%>

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

@@ -24,8 +24,7 @@ module VideoHelper
 <%- 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)'
+  NO_FFMPEG = 'no ffmpeg download for this platform (set RAIDER_FFMPEG_PATH to an ffmpeg with libvpx)'
 <%- end -%>
 
   @disabled = false

data/lib/ruby_raider/ffmpeg.rb

@@ -14,16 +14,31 @@ module RubyRaider
     MAX_REDIRECTS = 5
     # Seconds for the whole download, redirects included.
     DOWNLOAD_TIMEOUT = 300
+    # The binaries are 3-5 MB; a bigger body is not ours and must not fill the disk before the checksum.
+    MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024
 
-    # Checksums are filled in when the RaiderHQ `ffmpeg-7.1` release is cut.
+    # The RaiderHQ `ffmpeg-7.1` release: FFmpeg 7.1.5, LGPL, built by .github/workflows/ffmpeg.yml
+    # (.github/ffmpeg/build.sh), run 42440762165. Each SHA-256 pins the exact bytes of that release's asset.
     RELEASE_BASE = 'https://github.com/RaiderHQ/ruby_raider/releases/download/ffmpeg-7.1/ffmpeg-7.1-'
     MANIFEST = {
       version: '7.1',
       assets: {
-        'darwin-arm64' => { url: "#{RELEASE_BASE}darwin-arm64".freeze, sha256: nil }.freeze,
-        'darwin-x64' => { url: "#{RELEASE_BASE}darwin-x64".freeze, sha256: nil }.freeze,
-        'linux-x64' => { url: "#{RELEASE_BASE}linux-x64".freeze, sha256: nil }.freeze,
-        'windows-x64' => { url: "#{RELEASE_BASE}windows-x64.exe".freeze, sha256: nil }.freeze
+        'darwin-arm64' => {
+          url: "#{RELEASE_BASE}darwin-arm64".freeze,
+          sha256: 'e6c9240c133f22ced9f1e55fc2d0889991274e1b787c296583cb74f7242ef417'
+        }.freeze,
+        'darwin-x64' => {
+          url: "#{RELEASE_BASE}darwin-x64".freeze,
+          sha256: 'e649ff3c5abe05700a657a12d549ee27ac53e190cd1aaee7a113765d3189e91f'
+        }.freeze,
+        'linux-x64' => {
+          url: "#{RELEASE_BASE}linux-x64".freeze,
+          sha256: '108b685bbfba103c8f25c641fc4c21e5ea79acecd131f9ea964db959e894e7d4'
+        }.freeze,
+        'windows-x64' => {
+          url: "#{RELEASE_BASE}windows-x64.exe".freeze,
+          sha256: 'e27c4d32675e8715a6b3260c87ed3834f959275af0412f501ed5781d5324ac1a'
+        }.freeze
       }.freeze
     }.freeze
 
@@ -115,12 +130,8 @@ module RubyRaider
       def handle_response(response, destination, deadline, timeout)
         case response
         when Net::HTTPSuccess
-          File.open(destination, 'wb') do |file|
-            response.read_body do |chunk|
-              check_deadline(deadline, timeout)
-              file.write(chunk)
-            end
-          end
+          check_size(response['content-length'].to_i)
+          write_body(response, destination, deadline, timeout)
           nil
         when Net::HTTPRedirection
           response['location'] || raise(IOError, 'redirect without Location header')
@@ -129,6 +140,22 @@ module RubyRaider
         end
       end
 
+      def write_body(response, destination, deadline, timeout)
+        written = 0
+        File.open(destination, 'wb') do |file|
+          response.read_body do |chunk|
+            check_deadline(deadline, timeout)
+            written += chunk.bytesize
+            check_size(written)
+            file.write(chunk)
+          end
+        end
+      end
+
+      def check_size(bytes)
+        raise IOError, "download larger than #{MAX_DOWNLOAD_BYTES} bytes" if bytes > MAX_DOWNLOAD_BYTES
+      end
+
       def socket_timeouts(deadline, timeout)
         left = check_deadline(deadline, timeout)
         { open_timeout: [10, left].min, read_timeout: [60, left].min }

data/lib/version

@@ -1 +1 @@
-4.0.0
+4.0.1

data/sig/ruby_raider/ffmpeg.rbs

@@ -5,6 +5,7 @@ module RubyRaider
 
     MAX_REDIRECTS: Integer
     DOWNLOAD_TIMEOUT: Integer
+    MAX_DOWNLOAD_BYTES: Integer
     RELEASE_BASE: String
     MANIFEST: manifest
     PLATFORMS: Array[String]

data/spec/generators/video_helper_spec.rb

@@ -128,6 +128,19 @@ describe 'Generated VideoHelper' do
       expect(argv.each_cons(2).to_a).to include(['-vf', "scale='min(1280,iw)':-2"])
     end
 
+    # The pinned ffmpeg has only what this encode needs (.github/ffmpeg/build.sh), and
+    # .github/ffmpeg/check.sh proves it on every build: both must run the same arguments.
+    it 'runs the encode that .github/ffmpeg/check.sh proves on the pinned ffmpeg builds' do
+      recorder = VideoHelper.recorder_for(driver)
+      recorder.start
+      recorder.stop(keep: true)
+
+      check = File.read(File.expand_path('../../.github/ffmpeg/check.sh', __dir__)).gsub(/\\\n\s*/, '')
+      shell = argv[0..-2].map { |arg| arg.include?("'") ? %("#{arg}") : arg }
+      shell[shell.index('-i') + 1] = '"$work/list.txt"'
+      expect(check).to include(%("$binary" #{shell.join(' ')} "$work/video.webm"))
+    end
+
     context 'when the config sets other fps and max_width' do
       let(:video_config) { { 'enabled' => true, 'fps' => 10, 'max_width' => 640 } }
 
@@ -351,9 +364,14 @@ describe 'Generated VideoHelper' do
       end
     end
 
-    context 'when no ffmpeg can be obtained (no override, placeholder manifest)' do
+    context 'when no ffmpeg can be obtained (no override, no build for this platform)' do
       let(:env) { { 'RAIDER_FFMPEG_PATH' => nil } }
 
+      before do
+        require 'ruby_raider/ffmpeg'
+        stub_const('RubyRaider::Ffmpeg::MANIFEST', { version: '7.1', assets: {} })
+      end
+
       it 'decides once, at the first call: listener nil, NullRecorder, exactly one [video] line' do
         require 'ruby_raider/ffmpeg'
         allow(RubyRaider::Ffmpeg).to receive(:ensure!)
@@ -362,9 +380,8 @@ describe 'Generated VideoHelper' do
         expect(warnings.size).to eq(1)
         expect(VideoHelper.recorder_for(driver)).to be_a(VideoHelper::NullRecorder)
         expect(VideoHelper.listener).to be_nil
-        expect(warnings).to eq(['[video] no ffmpeg available for this platform yet (set RAIDER_FFMPEG_PATH, or run ' \
-                                '`raider u video install` once the ffmpeg release is published); ' \
-                                "recording disabled for this run\n"])
+        expect(warnings).to eq(['[video] no ffmpeg download for this platform (set RAIDER_FFMPEG_PATH to an ffmpeg ' \
+                                "with libvpx); recording disabled for this run\n"])
         expect(RubyRaider::Ffmpeg).not_to have_received(:ensure!)
         expect(shots).to be_empty
       end

data/spec/integration/content/readme_content_spec.rb

@@ -17,8 +17,13 @@ describe 'Generated Readme content' do
                                    'RAIDER_CACHE_DIR', 'raider-results/attachments/')
       end
 
-      it 'says that video needs RAIDER_FFMPEG_PATH until the ffmpeg release is published' do
-        expect(section).to include('ffmpeg-7.1', 'not published yet')
+      it 'names the ffmpeg-7.1 release and no longer says it is unpublished' do
+        expect(section).to include('ffmpeg-7.1') if web
+        expect(section).not_to include('not published yet')
+      end
+
+      it 'lists the platforms with an ffmpeg download for web projects' do
+        expect(section).to include('macOS (Apple silicon and Intel), Linux x64 and Windows x64') if web
       end
 
       it 'names the right video format and how to turn video off for this project' do

data/spec/integration/end_to_end_spec.rb

@@ -321,9 +321,9 @@ describe 'End-to-End Project Generation and Execution' do
     JSON.parse(File.read(File.join(project, 'raider-results', 'run.json')))['results']
   end
 
-  # Failure video replay against real browsers. Needs an ffmpeg with libvpx (RAIDER_FFMPEG_PATH), because the
-  # RaiderHQ ffmpeg release has no checksums yet. Skipped when it, or the browser, is missing. Firefox can be
-  # pointed at a specific binary with FIREFOX_BINARY.
+  # Failure video replay against real browsers. Needs an ffmpeg with libvpx (RAIDER_FFMPEG_PATH), so most examples
+  # never download the release binary; RAIDER_E2E_DOWNLOAD=1 adds one that does. Skipped when it, or the browser,
+  # is missing. Firefox can be pointed at a specific binary with FIREFOX_BINARY.
   context 'Failure video replay', :slow, :video do
     let(:ffmpeg_path) { ENV.fetch('RAIDER_FFMPEG_PATH', '') }
     let(:cache_dir) { Dir.mktmpdir('raider-cache') }
@@ -421,16 +421,28 @@ describe 'End-to-End Project Generation and Execution' do
       it 'runs unchanged with one [video] line and no download when no ffmpeg is usable', :aggregate_failures do
         off = run_in_project(project, command, env: video_env('VIDEO' => 'off'))
         FileUtils.rm_rf(File.join(project, 'raider-results'))
-        result = run_in_project(project, command, env: video_env('RAIDER_FFMPEG_PATH' => nil))
+        # A file where the cache dir should be: the download cannot even start, so nothing is fetched.
+        blocker = File.join(cache_dir, 'not-a-dir')
+        File.write(blocker, '')
+        result = run_in_project(project, command, env: video_env('RAIDER_FFMPEG_PATH' => nil, 'RAIDER_CACHE_DIR' => blocker))
 
         expect(result[:exit_code]).to eq(off[:exit_code]), "STDOUT: #{result[:stdout]}\nSTDERR: #{result[:stderr]}"
         video_lines = result[:stderr].lines.grep(/\[video\]/)
         expect(video_lines.size).to eq(1), "STDERR: #{result[:stderr]}"
-        # Decided at the first driver/recorder call, before any capture or fetch: the placeholder
-        # manifest has no checksum, so nothing is captured or downloaded.
-        expect(video_lines.first).to include('no ffmpeg available for this platform yet')
+        expect(video_lines.first).to include('ffmpeg download failed')
         expect(video_files(project)).to be_empty
-        expect(Dir.glob(File.join(cache_dir, '**', '*'))).to be_empty
+        expect(Dir.glob(File.join(cache_dir, '**', '*'))).to eq([blocker])
+      end
+
+      # Downloads the pinned ffmpeg-7.1 release asset for this platform into an empty cache.
+      it 'downloads the pinned ffmpeg into an empty cache and attaches the video', :aggregate_failures do
+        skip 'set RAIDER_E2E_DOWNLOAD=1 to download the ffmpeg-7.1 release asset' unless ENV['RAIDER_E2E_DOWNLOAD'] == '1'
+
+        result = run_in_project(project, command, env: video_env('RAIDER_FFMPEG_PATH' => nil))
+        expect(result[:exit_code]).to eq(1), "STDOUT: #{result[:stdout]}\nSTDERR: #{result[:stderr]}"
+        expect(result[:stderr]).not_to include('[video]')
+        expect(Dir.glob(File.join(cache_dir, 'ffmpeg', '7.1', 'ffmpeg{,.exe}')).size).to eq(1)
+        expect_video_for_failure_only(project, 'fails after driving the page', result)
       end
     end
   end

data/spec/utilities/ffmpeg_spec.rb

@@ -41,11 +41,51 @@ describe RubyRaider::Ffmpeg do
     expect(described_class.platform(host_os: 'linux-gnu', host_cpu: 'aarch64')).to be_nil
   end
 
-  it 'ships a placeholder manifest with https urls and nil checksums for all four platforms' do
-    assets = described_class::MANIFEST[:assets]
-    expect(assets.keys).to contain_exactly('darwin-arm64', 'darwin-x64', 'linux-x64', 'windows-x64')
-    expect(assets.values.map { |a| a[:url] }).to all(start_with('https://'))
-    expect(assets.values.map { |a| a[:sha256] }).to all(be_nil)
+  it 'pins a SHA-256 and the ffmpeg-7.1 release url for each of the four platforms', :aggregate_failures do
+    expect(described_class::MANIFEST[:version]).to eq('7.1')
+    base = 'https://github.com/RaiderHQ/ruby_raider/releases/download/ffmpeg-7.1/ffmpeg-7.1-'
+    expect(described_class::MANIFEST[:assets].transform_values { |a| a[:url] }).to eq(
+      'darwin-arm64' => "#{base}darwin-arm64", 'darwin-x64' => "#{base}darwin-x64",
+      'linux-x64' => "#{base}linux-x64", 'windows-x64' => "#{base}windows-x64.exe"
+    )
+    shas = described_class::MANIFEST[:assets].values.map { |a| a[:sha256] }
+    expect(shas).to all(match(/\A\h{64}\z/))
+    expect(shas.uniq.size).to eq(4)
+  end
+
+  describe 'the pinned checksums' do
+    let(:real) { described_class::MANIFEST }
+
+    it 'is obtainable on every supported platform without an override' do
+      described_class::PLATFORMS.each do |p|
+        expect(described_class.obtainable?(env: {}, platform: p)).to be(true)
+      end
+    end
+
+    it 'discards a download whose bytes do not match the pinned checksum', :aggregate_failures do
+      described_class::PLATFORMS.each do |p|
+        result = described_class.ensure!(env:, manifest: real, fetch:, warn: warner, platform: p)
+        expect(result).to be_nil
+      end
+      expect(calls).to eq(real[:assets].values.map { |a| a[:url] })
+      expect(warnings).to all(include('checksum mismatch'))
+      expect(Dir.glob(File.join(cache, '**', '*'))).to be_empty
+    end
+
+    # FFMPEG_ARTIFACTS=<dir> holding ffmpeg-7.1-<platform>[.exe] (the build workflow's artifacts
+    # or the release assets) proves those exact bytes pass verification and get cached.
+    it 'accepts the built binaries', unless: ENV.fetch('FFMPEG_ARTIFACTS', '').empty? do
+      described_class::PLATFORMS.each do |p|
+        name = File.basename(real[:assets][p][:url])
+        source = File.join(ENV.fetch('FFMPEG_ARTIFACTS'), name)
+        copy = ->(_url, dest) { FileUtils.cp(source, dest) }
+        own = { 'RAIDER_CACHE_DIR' => File.join(cache, p) }
+        path = described_class.ensure!(env: own, manifest: real, fetch: copy, warn: warner, platform: p)
+        expect(path).to eq(described_class.cached_path(env: own, manifest: real, platform: p))
+        expect(File.executable?(path)).to be(true)
+      end
+      expect(warnings).to be_empty
+    end
   end
 
   it 'derives the cache dir from RAIDER_CACHE_DIR or the home cache', :aggregate_failures do
@@ -254,6 +294,39 @@ describe RubyRaider::Ffmpeg do
     expect(warnings).to eq(['cached ffmpeg failed checksum; video disabled'])
   end
 
+  describe 'download size cap' do
+    let(:dest) { File.join(cache, 'download.part') }
+    let(:deadline) { Process.clock_gettime(Process::CLOCK_MONOTONIC) + 60 }
+
+    def ok_response(length, chunks)
+      response = Net::HTTPOK.new('1.1', '200', 'OK')
+      response['content-length'] = length.to_s if length
+      allow(response).to receive(:read_body) { |&block| chunks.each(&block) }
+      response
+    end
+
+    it 'refuses a Content-Length over the cap before writing anything', :aggregate_failures do
+      response = ok_response(described_class::MAX_DOWNLOAD_BYTES + 1, ['x'])
+      expect { described_class.send(:handle_response, response, dest, deadline, 60) }
+        .to raise_error(IOError, /larger than/)
+      expect(File).not_to exist(dest)
+    end
+
+    it 'stops writing once the body passes the cap, whatever Content-Length said' do
+      stub_const("#{described_class}::MAX_DOWNLOAD_BYTES", 10)
+      response = ok_response(nil, ['x' * 6, 'x' * 6, 'x' * 6])
+      expect { described_class.send(:handle_response, response, dest, deadline, 60) }
+        .to raise_error(IOError, /larger than/)
+      expect(File.size(dest)).to be <= 10
+    end
+
+    it 'writes a body within the cap' do
+      response = ok_response(4, %w[ab cd])
+      expect(described_class.send(:handle_response, response, dest, deadline, 60)).to be_nil
+      expect(File.read(dest)).to eq('abcd')
+    end
+  end
+
   describe 'DEFAULT_WARN' do
     it 'writes to $stderr even when $VERBOSE is nil' do
       original = $VERBOSE
@@ -281,8 +354,8 @@ describe RubyRaider::Ffmpeg do
       expect(described_class.obtainable?(env: {}, manifest:, platform: 'linux-x64')).to be(true)
     end
 
-    it 'is false with no override and a nil checksum (the placeholder manifest)' do
-      expect(described_class.obtainable?(env: {}, platform: 'darwin-arm64')).to be(false)
+    it 'is false with no override and a nil checksum' do
+      expect(described_class.obtainable?(env: {}, manifest: unpublished, platform: 'darwin-arm64')).to be(false)
     end
 
     it 'is false for an unknown platform or a non-executable override' do

data/spec/utilities/video_command_spec.rb

@@ -44,12 +44,25 @@ RSpec.describe UtilityCommands do
 
   describe 'video install' do
     it 'exits 1 and explains when the build is not published yet' do
+      require 'ruby_raider/ffmpeg'
+      unpublished = { version: '7.1', assets: { RubyRaider::Ffmpeg.platform.to_s => { url: 'https://example.test/x', sha256: nil } } }
+      stub_const('RubyRaider::Ffmpeg::MANIFEST', unpublished)
       out, err, status = run_cli('video', 'install')
       expect(status).to eq(1)
       expect(err).to include('[video]', 'ffmpeg build not published yet')
       expect(out).to eq('')
     end
 
+    it 'exits 1 and installs nothing when the download does not match the pinned checksum', :aggregate_failures do
+      require 'ruby_raider/ffmpeg'
+      allow(RubyRaider::Ffmpeg).to receive(:http_get) { |_url, dest| File.write(dest, 'not ffmpeg') }
+      out, err, status = run_cli('video', 'install')
+      expect(status).to eq(1)
+      expect(err).to include('[video]', 'checksum mismatch')
+      expect(out).to eq('')
+      expect(Dir.glob(File.join(cache, '**', '*'))).to be_empty
+    end
+
     it 'prints the path and exits 0 when ensure! succeeds' do
       require 'ruby_raider/ffmpeg'
       allow(RubyRaider::Ffmpeg).to receive(:ensure!).and_return('/tmp/ffmpeg')