raider_reporter 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f4191162d0ff126c9b45a552005131bc1c93b9c2c4abf97d8ae347bd8f9d21d
-  data.tar.gz: f1537e8415dee111fd49a2005e88282a34b2f0279ba74945aacab16034531f80
+  metadata.gz: f5caf918bfe636da31412f0d9befd2122cdb81c1c207ec594b5e60f11a9aa930
+  data.tar.gz: 96b844a743d018f47b54cbb80c3552ab2a76e2be6b247095099efa2457f07a3a
 SHA512:
-  metadata.gz: 7763eb9aecea9e4c65d6727bf02be613720eb994bbd763f1755d23073f852faf5bcb4ca5986954a1327b80ce3a2d67b1a147f33c64cede3ab5318304897542a2
-  data.tar.gz: f06d92ce870157d73411f53ad368ecd6a01ce23294df319d49e7028f3d29d15677a8087c39c116a3d939fb58c6c0d5681aab286490e3fe94890771597438a540
+  metadata.gz: 0c030e57458d0a854dd9d52fef8086301b52d62cfa181e689c5a30f88cc6b6feb108510c767183d3abb3cac7ed0deeb1037e0ed7b9b4a80357e95c1ca805bf06
+  data.tar.gz: '0382b224926f9a6595f66355102afd825ced75a0e107bdf65c37c8cb7af8d5a93cfef66ef8a5f7952bb63351c9c9f16c226afd28ca5c46112daf29240da29343'

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.12.0 — 2026-11-01
+
+- Raider traces: the content type `application/vnd.raider.trace+zip` (`type: :trace`) gets its own size cap, `config.max_trace_bytes` (default 25 MB). The 5 MB `max_attachment_bytes` and the 50 MB `max_video_bytes` still apply to everything else. A trace over its cap is skipped with a warning
+- `RaiderReporter.attach(name, path, type:, attempt:)` takes an optional `attempt`, written to the attachment's entry in `run.json` and in the upload when given
+- Uploads send screenshots and other files first, then traces, then videos, in the room left in the budget. A trace that does not fit is skipped and later, smaller ones are still tried
+- The local HTML report shows a trace as a download link ("Trace (open in Raider Desktop)", with the attempt when known)
+- `.zip` files resolve to `application/zip`
+- No breaking changes
+
 ## 0.11.0 — 2026-10-29
 
 - Live events: when `RAIDER_EVENTS_DIR` is set, the RSpec formatter and the Cucumber formatter/plugin append NDJSON lines (`plan`, `started`, `finished`, `done`, each with `"v":1`) to `<dir>/worker-<n>.ndjson`, where `n` is the shard index (1 without a shard). Cucumber writes `started` and `finished` once per attempt under `--retry`. The Raider desktop app tails them during a run. The files are created owner-only (0600) and a symlinked file is refused. With the variable unset, nothing changes. A write error switches the stream off after one warning and never fails the suite

data/README.md

@@ -101,7 +101,7 @@ Cucumber's `attach` is captured only when given the path of an existing file. In
 
 `parallel_tests` works with no configuration for Cucumber too: each process writes `run-<n>.json`. See [Parallel runs](#parallel-runs).
 
-## Attaching screenshots and videos
+## Attaching screenshots, videos and traces
 
 Call `RaiderReporter.attach` while an example is running, for example from an `after` hook:
 
@@ -120,11 +120,13 @@ end
 
 `attach` copies the file right away, so the attachment keeps the bytes the file had at that moment even if the same path is overwritten by a later example. Using a path per example (as above) still makes the files on disk easier to find.
 
-`attach` returns `true` on success. It returns `false` and prints a `[raider_reporter]` warning, never raising, if it is called outside a running example (for instance when the formatter is not loaded), if the file does not exist, or if the file is larger than its size cap: 5 MB (`max_attachment_bytes`), or 50 MB for videos (`video/*`, `max_video_bytes`).
+`attach` returns `true` on success. It returns `false` and prints a `[raider_reporter]` warning, never raising, if it is called outside a running example (for instance when the formatter is not loaded), if the file does not exist, or if the file is larger than its size cap: 5 MB (`max_attachment_bytes`), 50 MB for videos (`video/*`, `max_video_bytes`), or 25 MB for traces (`max_trace_bytes`).
 
 Videos (`.webm`, `.mp4`) are attached the same way, for example `RaiderReporter.attach("video", path, type: :webm)`. In the local HTML report they play inline, with a download link.
 
-When a run is uploaded, screenshots and other non-video attachments are sent first; videos then fill the room left in the upload budget. A video that does not fit is skipped and later, smaller videos are still tried. The local `raider-results/attachments/` folder keeps every attachment that passed its size cap.
+Raider traces (`trace.zip`, content type `application/vnd.raider.trace+zip`, written by ruby_raider projects for failing tests) are attached with `RaiderReporter.attach("trace", path, type: :trace, attempt: 2)`. `attempt` is optional on any attachment. When given, it is written to the attachment's entry in `run.json` and in the upload, so a viewer can tell the traces of different retries apart. In the local HTML report a trace is a download link; open it in Raider Desktop. The format is described in the [trace viewer design](https://github.com/RaiderHQ/raider_planning/blob/main/docs/superpowers/specs/2026-11-01-trace-viewer-design.md).
+
+When a run is uploaded, screenshots and other attachments are sent first, then traces, then videos, in the room left in the upload budget. A trace or video that does not fit is skipped and later, smaller ones are still tried. The local `raider-results/attachments/` folder keeps every attachment that passed its size cap.
 
 ## Live events
 
@@ -142,13 +144,14 @@ end
 | Option | Default | Description |
 | --- | --- | --- |
 | `token` | `ENV["RAIDER_TOKEN"]` | API token used for uploads. |
-| `endpoint` | `ENV["RAIDER_ENDPOINT"]` | Base URL of the Raider server to upload to. |
+| `endpoint` | `ENV["RAIDER_ENDPOINT"]` | Base URL of your Raider Hideout server (what its setup page or bin/rails hideout:setup prints as RAIDER_ENDPOINT). |
 | `output_dir` | `"raider-results"` | Directory for local output. |
 | `clean_output_dir` | `true` | Remove the previous `run.json` and `attachments/` directory (`run-<n>.json` and `attachments-<n>/` when sharded) inside `output_dir` before writing. Nothing else in `output_dir` is touched, except a raider_reporter-written `index.html`. |
 | `html_report` | `true` | Write `index.html`, the local HTML report, into `output_dir` after each run. See [Local report](#local-report). |
 | `quarantine` | `true` when `ENV["RAIDER_QUARANTINE"]` is `1` or `true` | Fetch the quarantine list at run start and report matching failures as `quarantined`. Needs `token` and `endpoint`. See [Quarantine](#quarantine). |
 | `max_attachment_bytes` | `5 MB` | Largest non-video attachment `attach` accepts. |
 | `max_video_bytes` | `50 MB` | Largest `video/*` attachment `attach` accepts. |
+| `max_trace_bytes` | `25 MB` | Largest Raider trace (`application/vnd.raider.trace+zip`) `attach` accepts. |
 | `exec_summary_path` | `ENV["RAIDER_EXEC_SUMMARY"]` | File where the run writes its failure counts (framework failures, quarantined, errors outside tests) for `raider-reporter exec` to read when it decides the exit code. `exec` sets it for the command it runs; leave it unset otherwise. Nothing is written when it is unset. See [Quarantine](#quarantine). |
 | `environment` | `{}` | Free-form key/values stored with the run (browser, suite name, and so on). Values are JSON values: strings, booleans or numbers. |
 
@@ -180,7 +183,7 @@ Set `config.html_report = false` to turn it off. An `index.html` that raider_rep
 If both a token and an endpoint are set, the run (plus attachments) is uploaded when the suite finishes:
 
 ```
-RAIDER_TOKEN=... RAIDER_ENDPOINT=https://your-raider-server bundle exec rspec
+RAIDER_TOKEN=... RAIDER_ENDPOINT=https://hideout.example.com bundle exec rspec
 ```
 
 On success the formatter prints `Raider report: <url>` to stderr (so tools that parse RSpec's stdout, such as `--format json`, stay clean), using the build URL when the server returns one and the run URL otherwise (or `Raider report uploaded (run <id>)` if the response has no URL). If either value is missing, nothing is uploaded and the local files are still written.
@@ -189,7 +192,7 @@ An upload carries at most 45 MB of attachments and at most 1000 attachment files
 
 Reporting is fail-open: no error inside the gem, network failure, timeout or non-2xx response will raise or change RSpec's exit status. Each connect/write/read step of the upload times out after 30 seconds. Problems are printed as warnings prefixed with `[raider_reporter]`. An endpoint without `http://` or `https://` (for example `localhost:3000`) produces a warning and nothing is uploaded; a trailing slash is fine.
 
-The hosted Raider service is not public yet; uploads go to a Raider server whose address you provide in `RAIDER_ENDPOINT`.
+Raider Hideout is self-hosted: run your own server and set `RAIDER_ENDPOINT` to its URL. There is no hosted service.
 
 ## Quarantine
 
@@ -234,10 +237,10 @@ On pull requests, `raider-reporter comment` posts one comment with the build's r
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-- The comment is rendered by the Raider server (`GET /api/v1/builds/summary`); the gem only fetches the Markdown and posts it. The same comment is updated on every run instead of adding a new one.
+- The comment is rendered by the Raider Hideout server (`GET /api/v1/builds/summary`); the gem only fetches the Markdown and posts it. The same comment is updated on every run instead of adding a new one.
 - Pull requests from forks are skipped: GitHub gives their workflows a read-only token, so the command prints a notice and exits 0.
 - The command never fails your CI: it always exits 0 and prints notices to stderr, prefixed `[raider_reporter]`. It needs `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, `GITHUB_EVENT_PATH`, `RAIDER_TOKEN` and `RAIDER_ENDPOINT`; if one is missing, or the event is not a pull request, it does nothing.
-- It requires a Raider server that supports the summary endpoint and the `git.pr` field. Upgrade the server before using it.
+- It requires a Raider Hideout server that supports the summary endpoint and the `git.pr` field. Upgrade the server before using it.
 
 ## Quality gate
 
@@ -317,7 +320,7 @@ jobs:
 - **Artifact names:** pipeline artifacts cannot be overwritten within a run, so the name includes the job position and attempt. A fixed name would fail when you re-run failed jobs or use `strategy: parallel`.
 - **Azure Repos only:** the PR comment works for repositories hosted in Azure Repos. A GitHub-hosted repository built by Azure Pipelines still uploads results, but `comment` prints `skipped: not an Azure Repos pull request`.
 - **Parallel jobs:** `strategy: parallel: N` shards are detected automatically and grouped into one build, like GitHub matrix jobs.
-- The command never fails your pipeline: it always exits 0 and prints notices to stderr, prefixed `[raider_reporter]`. It needs `SYSTEM_ACCESSTOKEN`, `RAIDER_TOKEN` and `RAIDER_ENDPOINT`, and requires a Raider server that supports the summary endpoint.
+- The command never fails your pipeline: it always exits 0 and prints notices to stderr, prefixed `[raider_reporter]`. It needs `SYSTEM_ACCESSTOKEN`, `RAIDER_TOKEN` and `RAIDER_ENDPOINT`, and requires a Raider Hideout server that supports the summary endpoint.
 
 ## Parallel runs
 

data/lib/raider_reporter/collector.rb

@@ -4,15 +4,18 @@ require "securerandom"
 require "tmpdir"
 require "fileutils"
 require "set"
+require_relative "content_types"
 
 module RaiderReporter
   # Accumulates one suite run. Framework formatters call it; writers read the Run it returns.
   class Collector
     def initialize(max_attachment_bytes:, warn:, max_video_bytes: Configuration::DEFAULT_MAX_VIDEO_BYTES,
+                   max_trace_bytes: Configuration::DEFAULT_MAX_TRACE_BYTES,
                    clock: -> { Time.now.utc }, uuid: -> { SecureRandom.uuid },
                    quarantine: -> { Quarantine::EMPTY })
       @max_attachment_bytes = max_attachment_bytes
       @max_video_bytes = max_video_bytes
+      @max_trace_bytes = max_trace_bytes
       @warn = warn
       @clock = clock
       @uuid = uuid
@@ -120,12 +123,19 @@ module RaiderReporter
         @warn.call("attachment #{path} no longer exists; skipped")
         return false
       end
-      limit = attachment.content_type.to_s.start_with?("video/") ? @max_video_bytes : @max_attachment_bytes
+      limit = limit_for(attachment.content_type)
       if File.size(path) > limit
         @warn.call("attachment #{path} is larger than #{limit} bytes; skipped")
         return false
       end
       true
     end
+
+    def limit_for(content_type)
+      return @max_trace_bytes if ContentTypes.trace?(content_type)
+      return @max_video_bytes if ContentTypes.video?(content_type)
+
+      @max_attachment_bytes
+    end
   end
 end

data/lib/raider_reporter/configuration.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 require "raider_reporter/azure_env"
+require "raider_reporter/content_types"
 
 module RaiderReporter
   class Configuration
     TRUTHY = %w[1 true].freeze
     DEFAULT_MAX_VIDEO_BYTES = 50 * 1024 * 1024
+    DEFAULT_MAX_TRACE_BYTES = 25 * 1024 * 1024
 
     attr_accessor :token, :endpoint, :output_dir, :clean_output_dir, :html_report, :environment, :max_attachment_bytes,
-                  :max_video_bytes, :quarantine, :exec_summary_path
+                  :max_video_bytes, :max_trace_bytes, :quarantine, :exec_summary_path
 
     def initialize(env = ENV)
       @token = AzureEnv.value(env, "RAIDER_TOKEN")
@@ -19,10 +21,19 @@ module RaiderReporter
       @environment = {}
       @max_attachment_bytes = 5 * 1024 * 1024
       @max_video_bytes = DEFAULT_MAX_VIDEO_BYTES
+      @max_trace_bytes = DEFAULT_MAX_TRACE_BYTES
       @quarantine = TRUTHY.include?(AzureEnv.value(env, "RAIDER_QUARANTINE").to_s.downcase)
       @exec_summary_path = AzureEnv.value(env, "RAIDER_EXEC_SUMMARY")
     end
 
+    # The size cap for one attachment of this content type.
+    def attachment_limit(content_type)
+      return max_trace_bytes if ContentTypes.trace?(content_type)
+      return max_video_bytes if ContentTypes.video?(content_type)
+
+      max_attachment_bytes
+    end
+
     def upload?
       present?(token) && present?(endpoint)
     end

data/lib/raider_reporter/content_types.rb

@@ -2,18 +2,26 @@
 
 module RaiderReporter
   module ContentTypes
+    TRACE = "application/vnd.raider.trace+zip"
+
     BY_EXTENSION = {
       ".png" => "image/png", ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".gif" => "image/gif",
       ".webp" => "image/webp", ".mp4" => "video/mp4", ".webm" => "video/webm", ".mov" => "video/quicktime",
-      ".txt" => "text/plain", ".log" => "text/plain", ".html" => "text/html", ".json" => "application/json"
+      ".txt" => "text/plain", ".log" => "text/plain", ".html" => "text/html", ".json" => "application/json",
+      ".zip" => "application/zip"
     }.freeze
     BY_SYMBOL = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", mp4: "video/mp4",
-                  webm: "video/webm", text: "text/plain", html: "text/html", json: "application/json" }.freeze
+                  webm: "video/webm", text: "text/plain", html: "text/html", json: "application/json",
+                  trace: TRACE }.freeze
 
     MIME = %r{\A[\w.+-]+/[\w.+-]+\z}
 
     module_function
 
+    def trace?(content_type) = content_type.to_s == TRACE
+
+    def video?(content_type) = content_type.to_s.start_with?("video/")
+
     def resolve(type, path)
       if type.is_a?(String)
         return type if type.match?(MIME)

data/lib/raider_reporter/models.rb

@@ -9,7 +9,12 @@ module RaiderReporter
       super
     end
   end
-  Attachment = Data.define(:name, :source_path, :content_type)
+  # attempt: which try of the test produced it, when the caller knows (traces); nil otherwise.
+  Attachment = Data.define(:name, :source_path, :content_type, :attempt) do
+    def initialize(name:, source_path:, content_type:, attempt: nil)
+      super
+    end
+  end
   TestResult = Data.define(
     :identifier, :full_name, :file_path, :line_number, :status,
     :duration_ms, :attempts, :tags, :failure, :attachments

data/lib/raider_reporter/payload.rb

@@ -88,7 +88,10 @@ module RaiderReporter
 
     def attachment_hash(entry, mode)
       ref = mode == :local ? { "path" => entry[:path] } : { "part" => entry[:part] }
-      { "name" => entry[:attachment].name, "content_type" => entry[:attachment].content_type }.merge(ref)
+      attachment = entry[:attachment]
+      hash = { "name" => attachment.name, "content_type" => attachment.content_type }.merge(ref)
+      hash["attempt"] = attachment.attempt if attachment.attempt
+      hash
     end
   end
 end

data/lib/raider_reporter/quarantine.rb

@@ -11,7 +11,7 @@ module RaiderReporter
   NUL = "\u0000"
   NUL_REPLACEMENT = "\u{FFFD}"
 
-  # The server's test identity: raider_saas TestCase.key_for over the payload's
+  # The server's test identity: Raider Hideout's TestCase.key_for over the payload's
   # file_path and full_name, after ingest replaced NUL in each of them.
   def self.test_key(file_path, full_name)
     parts = [file_path, full_name].map { |part| part.to_s.tr(NUL, NUL_REPLACEMENT) }

data/lib/raider_reporter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RaiderReporter
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/raider_reporter/writers/html.rb

@@ -4,6 +4,7 @@ require "erb"
 require "fileutils"
 require "json"
 require "time"
+require_relative "../content_types"
 
 module RaiderReporter
   module Writers
@@ -229,6 +230,8 @@ module RaiderReporter
             %(<a href="#{href}"><img loading="lazy" src="#{href}" alt="#{h(attachment['name'])}"></a>)
           elsif content_type.start_with?("video/")
             %(<video controls preload="metadata" src="#{href}"></video><a href="#{href}" download>#{h(attachment['name'])}</a>)
+          elsif ContentTypes.trace?(content_type)
+            %(<a href="#{href}" download>#{h(trace_label(attachment['attempt']))}</a>)
           else
             %(<a href="#{href}">#{h(attachment['name'])}</a>)
           end
@@ -236,6 +239,10 @@ module RaiderReporter
         items.empty? ? "" : %(<div class="a">#{items.join(' ')}</div>)
       end
 
+      def trace_label(attempt)
+        attempt.is_a?(Integer) ? "Trace, attempt #{attempt} (open in Raider Desktop)" : "Trace (open in Raider Desktop)"
+      end
+
       # Relative paths inside the results folder only, each segment URL-encoded.
       def safe_href(path)
         path = path.to_s

data/lib/raider_reporter/writers/uploader.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "uri"
 require "json"
 require "securerandom"
+require_relative "../content_types"
 
 module RaiderReporter
   module Writers
@@ -48,8 +49,9 @@ module RaiderReporter
 
       private
 
-      # Keeps the attachments that fit the byte and count budget, non-video
-      # attachments first and videos in whatever room is left, and rebuilds the
+      # Keeps the attachments that fit the byte and count budget: screenshots,
+      # logs and other files first, then traces, then videos in whatever room
+      # is left. It rebuilds the
       # payload without the rest, so part names stay contiguous. Survivors keep
       # their original order. The local run.json is written from the original
       # payload and keeps all.
@@ -68,11 +70,13 @@ module RaiderReporter
         end))
       end
 
-      # Identity-keyed set of the attachments to upload. Non-videos come first
-      # and stop at the first byte overflow; videos then fill the room left,
-      # a video that does not fit is skipped and later ones are still tried.
+      # Identity-keyed set of the attachments to upload. Other files come first
+      # and stop at the first byte overflow; traces and then videos fill the
+      # room left, and one that does not fit is skipped while later ones are
+      # still tried.
       def budgeted(entries)
-        videos, others = entries.partition { |entry| video?(entry[:attachment]) }
+        traces, rest = entries.partition { |entry| ContentTypes.trace?(entry[:attachment].content_type) }
+        videos, others = rest.partition { |entry| ContentTypes.video?(entry[:attachment].content_type) }
         keep = {}.compare_by_identity
         bytes = 0
         others.each do |entry|
@@ -81,7 +85,7 @@ module RaiderReporter
 
           keep[entry[:attachment]] = true
         end
-        videos.each do |entry|
+        (traces + videos).each do |entry|
           break if keep.size >= MAX_UPLOAD_ATTACHMENTS
 
           size = size_of(entry)
@@ -93,10 +97,6 @@ module RaiderReporter
         keep
       end
 
-      def video?(attachment)
-        attachment.content_type.to_s.start_with?("video/")
-      end
-
       def size_of(entry)
         File.size?(entry[:attachment].source_path).to_i
       end

data/lib/raider_reporter.rb

@@ -56,6 +56,7 @@ module RaiderReporter
       @collector = Collector.new(
         max_attachment_bytes: configuration.max_attachment_bytes,
         max_video_bytes: configuration.max_video_bytes,
+        max_trace_bytes: configuration.max_trace_bytes,
         warn: ->(message) { warn(message) },
         quarantine: -> { quarantined_keys }
       )
@@ -66,7 +67,8 @@ module RaiderReporter
       @quarantined_keys ||= Quarantine.load(configuration, warn: ->(message) { warn(message) })
     end
 
-    def attach(name, path, type: nil)
+    # attempt: the try of the test that produced the file, for attachments kept per attempt (traces).
+    def attach(name, path, type: nil, attempt: nil)
       unless collector&.in_test?
         warn("attach(#{name.inspect}) called outside a running example; ignored")
         return false
@@ -77,14 +79,14 @@ module RaiderReporter
       end
 
       content_type = ContentTypes.resolve(type, path)
-      limit = attachment_limit(content_type)
+      limit = configuration.attachment_limit(content_type)
       if File.size(path.to_s) > limit
         warn("attach(#{name.inspect}): file #{path} is larger than #{limit} bytes; ignored")
         return false
       end
 
       collector.attach(Attachment.new(name: name.to_s, source_path: collector.stage(path.to_s),
-                                      content_type: content_type))
+                                      content_type: content_type, attempt: attempt))
     rescue StandardError => e
       warn("attach(#{name.inspect}) failed: #{e.class}: #{e.message}")
       false
@@ -126,10 +128,6 @@ module RaiderReporter
 
     private
 
-    def attachment_limit(content_type)
-      content_type.start_with?("video/") ? configuration.max_video_bytes : configuration.max_attachment_bytes
-    end
-
     # First, so a later reporting problem cannot lose it. A failure here only means
     # no summary, and exec then keeps the command's exit code.
     def write_exec_summary

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raider_reporter
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Augustin Gottlieb