raider_reporter 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c1a8baed9855a5cba10100e57b9052184f6f748b7f015d630541d52905031c6
-  data.tar.gz: cc40652b897de2d3832a3d5da58d8bdb6f8e3a6873b11da927b68fd5a0478e24
+  metadata.gz: 61be0da46b6e8038ccb7da397ce371e20e398792aaa42aff9e93e2e765efd73b
+  data.tar.gz: 9d2859ced0b58e73ccd0f8d90fece82b3d8f379bca46ef958edb8089e81ae30e
 SHA512:
-  metadata.gz: e16586146bc9d569b5cd827c5533e6aae6cdef3bec2bc4ae3d6390c230a193ad56be6cc8fd01d11e90e933522a7f2f2ae54613450acb5a95daa609364634af1e
-  data.tar.gz: 134a1d1de73ff5b93c00740996ffea7cc8cde10f7be727bbb2ab8320b3158b710ac2df413d3e68ce334bff3fc7b3d40cd5cf2150fcc4cb6cd21d9b0e79521554
+  metadata.gz: a805ca67f914f9413cb95913b2015c7a56020564bf709a45aadd96c25f183a374927fd572b6dab80cf2969adca7b2d6305edd04b617d0414f1af2caba108ddc4
+  data.tar.gz: 1f9ba4407c3677d5166ec09aced32f3d2c43ac4a599468eda510f3e7327ce417d6eea25af8de47ea308bacde60e45b9c8ba36414434bd0bd0d938bb2ecdd1bfc

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 — 2026-10-11
+
+- Add a Cucumber reporter (Cucumber >= 9, < 12; not a gem dependency). `require "raider_reporter/cucumber"` from `features/support/` registers it in plugin mode (recommended, works with any `--format` and no `--out`); `--format RaiderReporter::Cucumber::Formatter --out <file>` also works. Using both registers one listener
+- Identity: `file_path` is project-relative (`features/login.feature`), `full_name` is `"<Feature>: <Scenario>"` (outline rows add `(<Examples name>, row <n>)`; when several Examples tables share a label, each is numbered: `(Examples 1, row 1)`, `(Examples 2, row 1)`), `identifier` is `<file>:<line>`
+- Report the failing step (or Before/After hook) with its location in the failure message; ambiguous maps to failed, undefined to pending
+- Retries: only the final attempt is kept, with `attempts` set and earlier attachments dropped
+- Attachments: `RaiderReporter.attach` and Cucumber's `attach(path, media_type)` with an existing file path are captured; inline data and `log` messages are ignored
+- Dry runs (`cucumber --dry-run`) write and upload nothing; `parallel_tests` shards write `run-<n>.json`
+- No breaking changes: RSpec behaviour is unchanged
+
+## 0.3.0 — 2026-10-11
+
+- Report pull request identity: `run.ci.repository`, `run.git.default_branch` and `run.git.pr` (number, base/head branch, head SHA) on `pull_request` and `pull_request_target` events. Requires a Raider server that accepts `git.pr`
+- Add `raider-reporter comment`: posts (and updates) one results comment on the pull request and sets the `raider/tests` commit status; fail-open, always exits 0, skips fork PRs
+- Print the `Raider report: <url>` line to stderr instead of stdout, so stdout-parsing tools (such as `--format json`) stay clean
+- Report the PR head commit's SHA and message on pull request events instead of the merge commit's
+- Harden the GitHub client: only a bot-authored comment starting with the marker is updated, any number of trailing slashes in `GITHUB_API_URL` are accepted, and the token is redacted from error messages
+
 ## 0.2.0 — 2026-10-11
 
 - Report the CI build key, attempt and job so runs of one build are grouped (GitHub Actions)

data/README.md

@@ -1,6 +1,6 @@
 # raider_reporter
 
-Raider-schema test reporting for RSpec. `raider_reporter` is an RSpec formatter that records every example's result, failure details, screenshots and videos, writes them to a local `run.json` (schema v1), and can optionally upload the run to a Raider server. It replaces Allure for Ruby Raider projects.
+Raider-schema test reporting for RSpec and Cucumber. `raider_reporter` is an RSpec formatter and a Cucumber reporter that records every example's result, failure details, screenshots and videos, writes them to a local `run.json` (schema v1), and can optionally upload the run to a Raider server. It replaces Allure for Ruby Raider projects.
 
 It has no runtime dependencies and requires Ruby 3.2 or newer.
 
@@ -26,7 +26,80 @@ Enable the formatter in `.rspec`:
 --format RaiderReporter::RSpec::Formatter
 ```
 
-Run `bundle exec rspec` as usual. Results land in `raider-results/run.json`. A dry run (`rspec --dry-run`) writes and uploads nothing.
+Run `bundle exec rspec` as usual. (For Cucumber, see [Cucumber](#cucumber).) Results land in `raider-results/run.json`. A dry run (`rspec --dry-run`) writes and uploads nothing.
+
+## Cucumber
+
+Requirements: Cucumber 9, 10 or 11 in your own Gemfile (`gem "cucumber"`). It is not a dependency of this gem; requiring `raider_reporter/cucumber` without Cucumber raises a `LoadError` that says so. Cucumber 9.2.1 on Ruby 4 also needs `gem "logger"` in your Gemfile, because Cucumber requires it without declaring it.
+
+### Plugin mode (recommended)
+
+Require the reporter from a file under `features/support/`, for example `features/support/raider.rb`:
+
+```ruby
+require "raider_reporter/cucumber"
+```
+
+Then run Cucumber with any normal formatter and no `--out`:
+
+```
+# cucumber.yml
+default: --format pretty
+```
+
+The require registers one listener on Cucumber's event bus, so it sits next to `pretty`, `progress` or any other formatter. Results land in `raider-results/run.json`, and a dry run (`cucumber --dry-run`) writes and uploads nothing. Plugin mode registers once per Ruby process, because `require` is cached: a second in-process `Cucumber::Cli::Main` run in the same process does not register again.
+
+### Formatter mode
+
+You can also name the formatter explicitly:
+
+```
+cucumber --format pretty --format RaiderReporter::Cucumber::Formatter --out raider-results/cucumber.log
+```
+
+`--out` is required here. Cucumber rejects a second formatter on the same output stream ("All but one formatter must use --out", also in 9.2.1), and this formatter writes nothing to its stream, so give it any file path (it is never created). If both modes are active, only one listener is registered.
+
+### How tests are identified
+
+- `file_path` is relative to the project root (`features/login.feature`), even when Cucumber is given `./features/login.feature` or an absolute path.
+- `full_name` is `"<Feature name>: <Scenario name>"`. Scenario Outline rows are `"<Feature name>: <Scenario name> (<Examples name or 'Examples'>, row <n>)"`, where `n` is the 1-based data row of that Examples table. When two or more Examples tables of one outline share a label (for example two unnamed ones), every table with that label is numbered by its position among them, `(Examples 1, row 1)`, `(Examples 2, row 1)`, so each row keeps a distinct name; tables with a unique label are unchanged.
+- `identifier` is `"<file_path>:<line>"`: the scenario line, or the Examples row line for outline rows.
+- `tags` are the feature, scenario and Examples tags, merged, sorted, unique, without `@`.
+
+Statuses: passed, failed and ambiguous (reported as failed), pending and undefined (reported as pending), skipped.
+
+### Failures
+
+A failed test reports the step that failed, not the whole scenario:
+
+```
+When I fail on purpose (features/login.feature:9)
+
+expected 5, got 4
+```
+
+A failing `Before` or `After` hook is named `Before hook` or `After hook` in place of the step, so an `After` hook that raises after every step passed is still a failed test. Messages are capped at 10,000 characters and backtraces at 50 lines.
+
+### Retries
+
+With `--retry n`, only the final attempt of each scenario is reported, and `attempts` is the number of attempts. Each attempt starts with fresh attachments; attachments from earlier attempts are dropped.
+
+### Attachments
+
+Both of these are captured while a scenario runs:
+
+```ruby
+After do |scenario|
+  attach(path, "image/png") if scenario.failed?        # Cucumber's own attach, with an existing file path (a Pathname works too)
+  RaiderReporter.attach("screenshot", path, type: :png) # or the Raider helper, as in RSpec
+end
+```
+
+Cucumber's `attach` is captured only when given the path of an existing file. Inline data (`attach("some text", "text/plain")`) and `log` messages are ignored.
+
+### Parallel runs with Cucumber
+
+`parallel_tests` works with no configuration for Cucumber too: each process writes `run-<n>.json`. See [Parallel runs](#parallel-runs).
 
 ## Attaching screenshots and videos
 
@@ -84,7 +157,7 @@ If both a token and an endpoint are set, the run (plus attachments) is uploaded
 RAIDER_TOKEN=... RAIDER_ENDPOINT=https://your-raider-server bundle exec rspec
 ```
 
-On success the formatter prints `Raider report: <url>`, 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.
+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.
 
 An upload carries at most 45 MB of attachments and at most 1000 attachment files. Attachments past that budget are left out of the upload (in order, with one warning) but stay in the local `raider-results/`.
 
@@ -92,6 +165,36 @@ Reporting is fail-open: no error inside the gem, network failure, timeout or non
 
 The hosted Raider service is not public yet; uploads go to a Raider server whose address you provide in `RAIDER_ENDPOINT`.
 
+## Pull request comments
+
+On pull requests, `raider-reporter comment` posts one comment with the build's results (and sets a `raider/tests` commit status on the PR head commit). Run it in a job that runs after your test jobs, so every shard has uploaded. Use the workflow's `GITHUB_TOKEN` (or a GitHub App token): a personal access token posts as a user, so the step adds a new comment on every run instead of updating the existing one.
+
+```yaml
+  raider-comment:
+    needs: [test]   # every test job id
+    if: always() && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with: { ruby-version: "3.4", bundler-cache: true }
+      - name: Comment Raider results on the pull request
+        run: bundle exec raider-reporter comment
+        env:
+          RAIDER_TOKEN: ${{ secrets.RAIDER_TOKEN }}
+          RAIDER_ENDPOINT: ${{ vars.RAIDER_ENDPOINT }}
+          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.
+- 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.
+
 ## Parallel runs
 
 When a suite is split across several processes or CI jobs, each one uploads its own run. Raider groups runs of the same CI build, so the shards show up together as one build. Each run records its shard (`index`, `total` and a `label`) and, on GitHub Actions, a build key made from the repository, run id and run attempt. A re-run attempt of a workflow is a separate build.
@@ -153,6 +256,7 @@ Tip: run `rm -rf raider-results` before a parallel run. Each process only cleans
 ## Examples
 
 - `examples/rspec_basic` is a runnable RSpec project with a passing, a failing (with an attachment) and a skipped example. Run it with `cd examples/rspec_basic && bundle install && bundle exec rspec`; the failure is deliberate.
+- `examples/cucumber_basic` is the same for Cucumber (plugin mode): a passing scenario, a failing one with an attachment, and an outline. Run it with `cd examples/cucumber_basic && bundle install && bundle exec cucumber`; the failure is deliberate.
 - `examples/github_actions.yml` shows the workflow steps for CI.
 
 ## Schema
@@ -161,7 +265,7 @@ Tip: run `rm -rf raider-results` before a parallel run. Each process only cleans
 
 ## Contributing
 
-Bug reports and pull requests are welcome at https://github.com/RaiderHQ/raider_reporter. Run `bundle install && bundle exec rake` to run the specs.
+Bug reports and pull requests are welcome at https://github.com/RaiderHQ/raider_reporter. Run `bundle install && bundle exec rake` to run the specs. To test against another Cucumber, set `CUCUMBER_VERSION` (for example `CUCUMBER_VERSION="~> 9.0" bundle update cucumber && bundle exec rspec`).
 
 ## License
 

data/exe/raider-reporter

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "raider_reporter"
+require "raider_reporter/cli"
+
+exit RaiderReporter::CLI.new(ARGV).run

data/lib/raider_reporter/ci_detector.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require "open3"
+require "raider_reporter/github_event"
 
 module RaiderReporter
   class CiDetector
-    def initialize(env: ENV, git: method(:git_command))
+    PR_EVENTS = %w[pull_request pull_request_target].freeze
+
+    def initialize(env: ENV, git: method(:git_command), event_reader: nil)
       @env = env
       @git = git
+      @event_reader = event_reader || -> { GithubEvent.load(@env) }
     end
 
     def ci
@@ -20,17 +24,69 @@ module RaiderReporter
       repo = @env["GITHUB_REPOSITORY"]
       build_key = ("github_actions:#{repo}:#{run_id}:#{attempt}" if repo && run_id)
       { "provider" => "github_actions", "build_url" => build_url, "build_id" => run_id,
-        "attempt" => attempt, "job" => @env["GITHUB_JOB"], "build_key" => build_key }.compact
+        "attempt" => attempt, "job" => @env["GITHUB_JOB"], "build_key" => build_key,
+        "repository" => (repo unless repo.to_s.empty?) }.compact
     end
 
     def git
-      info = { "branch" => branch, "commit_sha" => sha, "commit_message" => @git.call("log", "-1", "--pretty=%s") }
+      pr = pull_request
+      info = { "branch" => branch, "commit_sha" => pr ? pr["head_sha"] : sha, "commit_message" => commit_message(pr),
+               "default_branch" => default_branch, "pr" => pr }
       info = info.compact
       info.empty? ? nil : info
     end
 
     private
 
+    def event
+      return @event if defined?(@event)
+
+      loaded = begin
+        @event_reader.call
+      rescue StandardError
+        nil
+      end
+      @event = loaded.is_a?(Hash) ? loaded : nil
+    end
+
+    def default_branch
+      value = event&.dig("repository", "default_branch")
+      value.is_a?(String) && !value.empty? ? value : nil
+    rescue StandardError
+      nil
+    end
+
+    def pull_request
+      return nil unless event && PR_EVENTS.include?(@env["GITHUB_EVENT_NAME"])
+
+      pr = event["pull_request"]
+      return nil unless pr.is_a?(Hash)
+
+      number = pr["number"] || event["number"]
+      base = pr.dig("base", "ref")
+      head = pr.dig("head", "ref")
+      sha = pr.dig("head", "sha")
+      return nil unless number.is_a?(Integer) && number >= 1
+      return nil unless [base, head, sha].all? { |v| v.is_a?(String) && !v.empty? }
+
+      { "number" => number, "base_branch" => base, "head_branch" => head, "head_sha" => sha }
+    rescue StandardError
+      nil
+    end
+
+    # On a PR, GitHub checks out a synthetic merge commit; its message is not the author's.
+    def commit_message(pr)
+      if pr && merge_commit?
+        message = @git.call("log", "-1", "--format=%s", "HEAD^2")
+        return message unless message.to_s.empty?
+      end
+      @git.call("log", "-1", "--pretty=%s")
+    end
+
+    def merge_commit?
+      @git.call("rev-list", "--parents", "-n", "1", "HEAD").to_s.split.size == 3
+    end
+
     def branch
       head_ref = @env["GITHUB_HEAD_REF"].to_s
       return head_ref unless head_ref.empty?

data/lib/raider_reporter/cli.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "raider_reporter"
+
+module RaiderReporter
+  # `raider-reporter comment`: posts the build summary as a PR comment and sets a commit status.
+  # Fail-open: #run always returns 0, notices go to stderr, nothing goes to stdout.
+  class CLI
+    MARKER = "<!-- raider-reporter:build-comment -->"
+    CONTEXT = "raider/tests"
+    REQUIRED_ENV = %w[GITHUB_TOKEN GITHUB_REPOSITORY GITHUB_EVENT_PATH RAIDER_TOKEN RAIDER_ENDPOINT].freeze
+    STATUS_STATES = { "passed" => "success", "failed" => "failure", "incomplete" => "pending" }.freeze
+    FALLBACK_DESCRIPTIONS = {
+      "passed" => "Raider: tests passed",
+      "failed" => "Raider: tests failed",
+      "incomplete" => "Raider: build incomplete"
+    }.freeze
+    DEFAULT_API_URL = "https://api.github.com"
+    USAGE = <<~TEXT
+      Usage: raider-reporter comment
+
+      Posts (or updates) the Raider build summary as a comment on the current pull request
+      and sets the "#{CONTEXT}" commit status. Intended for GitHub Actions; always exits 0.
+
+      Environment: #{REQUIRED_ENV.join(', ')} (GITHUB_API_URL optional).
+    TEXT
+
+    def initialize(argv, env: ENV, out: $stdout, err: $stderr)
+      @argv = argv
+      @env = env
+      @out = out
+      @err = err
+    end
+
+    def run
+      command = @argv.first
+      if command == "comment" && !@argv.include?("--help") && !@argv.include?("-h")
+        comment
+      else
+        @err.puts(USAGE)
+      end
+      0
+    rescue StandardError => e
+      notice("comment failed: #{e.class}: #{e.message}")
+      0
+    end
+
+    private
+
+    def comment
+      missing = REQUIRED_ENV.select { |name| @env[name].to_s.strip.empty? }
+      return notice("skipped: missing #{missing.join(', ')}") unless missing.empty?
+
+      event = GithubEvent.load(@env)
+      detector = CiDetector.new(env: @env, event_reader: -> { event })
+      pr = detector.git&.dig("pr")
+      return notice("skipped: not a pull request event") unless pr
+
+      build_key = detector.ci&.dig("build_key")
+      return notice("skipped: could not determine the build key") unless build_key
+
+      publish(pr, build_key)
+    rescue Comment::GithubClient::Forbidden
+      notice("skipped: token cannot write to this PR")
+    rescue StandardError => e
+      notice("comment failed: #{e.class}: #{e.message}")
+    end
+
+    def publish(pr, build_key)
+      summaries = Comment::SummaryClient.new(endpoint: @env["RAIDER_ENDPOINT"], token: @env["RAIDER_TOKEN"])
+      summary = summaries.fetch(build_key)
+      return notice("summary unavailable: #{summaries.last_error}") unless summary
+
+      github = Comment::GithubClient.new(token: @env["GITHUB_TOKEN"], repository: @env["GITHUB_REPOSITORY"],
+                                         api_url: api_url)
+      html_url = github.upsert_comment(pr["number"], summary.markdown, MARKER)
+      github.set_status(pr["head_sha"], state: STATUS_STATES.fetch(summary.state, "pending"),
+                                        target_url: summary.url, description: description(summary),
+                                        context: CONTEXT)
+      notice("PR comment updated: #{html_url}")
+    end
+
+    def api_url
+      url = @env["GITHUB_API_URL"].to_s.strip
+      url.empty? ? DEFAULT_API_URL : url
+    end
+
+    # "**Raider: failed** - 2 failed, 148 passed, 3 skipped (1m 12s)" -> "2 failed, 148 passed, 3 skipped".
+    # Falls back to a fixed text per state when the Markdown carries no headline counts.
+    def description(summary)
+      counts = headline_counts(summary.markdown)
+      text = counts || FALLBACK_DESCRIPTIONS.fetch(summary.state, FALLBACK_DESCRIPTIONS["incomplete"])
+      text[0, Comment::GithubClient::DESCRIPTION_LIMIT]
+    end
+
+    def headline_counts(markdown)
+      line = markdown.to_s.lines.find { |l| l.include?("Raider:") }
+      return nil unless line
+
+      counts = line.scan(/\b\d+ (?:failed|passed|skipped|pending)\b/)
+      counts.empty? ? nil : counts.join(", ")
+    end
+
+    def notice(message)
+      @err.puts("[raider_reporter] #{message}")
+      nil
+    end
+  end
+end

data/lib/raider_reporter/collector.rb

@@ -55,8 +55,18 @@ module RaiderReporter
     end
 
     def finish_test(**fields)
+      add_result(build_test(**fields))
+    end
+
+    # Closes the current test and returns its result without recording it, so a
+    # framework that retries can hold one result per test and replace it per attempt.
+    def build_test(**fields)
       result = TestResult.new(**fields, attachments: @pending_attachments || [])
       @pending_attachments = nil
+      result
+    end
+
+    def add_result(result)
       @results << result
       result
     end

data/lib/raider_reporter/comment/github_client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RaiderReporter
+  module Comment
+    # Minimal GitHub REST client: upsert one marked PR comment and set a commit status.
+    class GithubClient
+      class Error < StandardError; end
+      # 403/404: the token cannot write here (e.g. a fork's read-only token).
+      class Forbidden < Error; end
+
+      MAX_PAGES = 10
+      PER_PAGE = 100
+      DESCRIPTION_LIMIT = 140
+
+      def initialize(token:, repository:, api_url: "https://api.github.com", timeout: 30)
+        @token = token
+        @repository = repository
+        @api_url = api_url.to_s.strip.sub(%r{/+\z}, "")
+        @timeout = timeout
+      end
+
+      def upsert_comment(pr_number, body, marker)
+        existing = find_comment(pr_number, marker)
+        response = if existing
+                     request(:patch, "/repos/#{@repository}/issues/comments/#{existing['id']}", body: body)
+                   else
+                     request(:post, "/repos/#{@repository}/issues/#{pr_number}/comments", body: body)
+                   end
+        html_url = response.is_a?(Hash) ? response["html_url"] : nil
+        raise Error, "GitHub response had no html_url" if html_url.to_s.empty?
+
+        html_url
+      end
+
+      def set_status(sha, state:, target_url:, description:, context:)
+        return nil if sha.to_s.strip.empty?
+
+        payload = { state: state, target_url: target_url, context: context,
+                    description: description.to_s[0, DESCRIPTION_LIMIT] }
+        request(:post, "/repos/#{@repository}/statuses/#{sha}", payload: payload)
+        nil
+      end
+
+      private
+
+      def find_comment(pr_number, marker)
+        (1..MAX_PAGES).each do |page|
+          comments = request(:get, "/repos/#{@repository}/issues/#{pr_number}/comments?per_page=#{PER_PAGE}&page=#{page}")
+          raise Error, "unexpected comments response" unless comments.is_a?(Array)
+
+          found = comments.find { |c| ours?(c, marker) }
+          return found if found
+          return nil if comments.size < PER_PAGE
+        end
+        nil
+      end
+
+      # Only our own (bot-authored) marked comment is ever edited.
+      def ours?(comment, marker)
+        comment.is_a?(Hash) && comment["body"].to_s.start_with?(marker) &&
+          comment.dig("user", "type") == "Bot"
+      end
+
+      def redact(text)
+        @token.to_s.empty? ? text.to_s : text.to_s.gsub(@token.to_s, "[REDACTED]")
+      end
+
+      def request(verb, path, body: nil, payload: nil)
+        uri = URI.parse(@api_url + path)
+        raise Error, "GITHUB_API_URL must start with http:// or https://" unless uri.is_a?(URI::HTTP)
+
+        req = build_request(verb, uri, payload || ({ body: body } if body))
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: @timeout, read_timeout: @timeout,
+                                                       write_timeout: @timeout) { |http| http.request(req) }
+        handle(response)
+      rescue Error
+        raise
+      rescue StandardError => e
+        raise Error, redact("#{e.class}: #{e.message}")
+      end
+
+      def build_request(verb, uri, json)
+        klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch }.fetch(verb)
+        req = klass.new(uri)
+        req["Authorization"] = "Bearer #{@token}"
+        req["Accept"] = "application/vnd.github+json"
+        req["X-GitHub-Api-Version"] = "2022-11-28"
+        req["User-Agent"] = "raider_reporter/#{VERSION}"
+        if json
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(json)
+        end
+        req
+      end
+
+      def handle(response)
+        code = response.code.to_i
+        raise Forbidden, "HTTP #{code}" if [403, 404].include?(code)
+        raise Error, redact("HTTP #{code}: #{response.body.to_s[0, 200]}") unless (200..299).cover?(code)
+
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        raise Error, "GitHub returned invalid JSON"
+      end
+    end
+  end
+end

data/lib/raider_reporter/comment/summary_client.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "cgi/escape"
+
+module RaiderReporter
+  module Comment
+    # Fetches the rendered build summary from the Raider API. Never raises:
+    # failures return nil and set #last_error to a printable reason.
+    class SummaryClient
+      Summary = Data.define(:state, :markdown, :url)
+
+      attr_reader :last_error
+
+      def initialize(endpoint:, token:, timeout: 30)
+        @endpoint = endpoint
+        @token = token
+        @timeout = timeout
+        @last_error = nil
+      end
+
+      def fetch(build_key)
+        @last_error = nil
+        uri = summary_uri(build_key)
+        request = Net::HTTP::Get.new(uri)
+        request["Authorization"] = "Bearer #{@token}"
+        request["Accept"] = "application/json"
+        request["User-Agent"] = "raider_reporter/#{VERSION}"
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: @timeout, read_timeout: @timeout,
+                                                       write_timeout: @timeout) { |http| http.request(request) }
+        parse(response)
+      rescue StandardError => e
+        fail_with("#{e.class}: #{e.message}")
+      end
+
+      private
+
+      def summary_uri(build_key)
+        uri = URI.parse("#{@endpoint.to_s.strip.chomp('/')}/api/v1/builds/summary?build_key=#{CGI.escape(build_key.to_s)}")
+        raise ArgumentError, "endpoint must start with http:// or https://" unless uri.is_a?(URI::HTTP)
+
+        uri
+      end
+
+      def parse(response)
+        case response.code.to_i
+        when 200..299 then build_summary(response.body)
+        when 401 then fail_with("HTTP 401: unauthorized (check RAIDER_TOKEN)")
+        when 404 then fail_with("HTTP 404: build not found for this project")
+        else fail_with("HTTP #{response.code}: #{response.body.to_s[0, 200]}")
+        end
+      end
+
+      def build_summary(text)
+        data = JSON.parse(text.to_s)
+        unless data.is_a?(Hash) && %w[state markdown url].all? { |k| data[k].is_a?(String) }
+          return fail_with("invalid summary response")
+        end
+
+        Summary.new(state: data["state"], markdown: data["markdown"], url: data["url"])
+      rescue JSON::ParserError
+        fail_with("invalid summary response (not JSON)")
+      end
+
+      def fail_with(reason)
+        @last_error = @token.to_s.empty? ? reason : reason.gsub(@token.to_s, "[REDACTED]")
+        nil
+      end
+    end
+  end
+end

data/lib/raider_reporter/cucumber/formatter.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "cucumber"
+require "cucumber/formatter/ast_lookup"
+require "raider_reporter"
+require "raider_reporter/text"
+
+module RaiderReporter
+  module Cucumber
+    # Translates Cucumber events into Collector calls. Every handler is guarded:
+    # a reporting bug must never fail or crash the user's run. The formatter
+    # writes nothing to its IO; the report goes to RaiderReporter's own writers.
+    #
+    # Inside this namespace `Cucumber` means RaiderReporter::Cucumber, so the
+    # gem's constants are always written ::Cucumber.
+    class Formatter
+      STATUSES = {
+        passed: "passed", failed: "failed", ambiguous: "failed",
+        pending: "pending", undefined: "pending", skipped: "skipped"
+      }.freeze
+
+      # Passed to the World's `attach`; reports an existing file as an attachment.
+      module AttachCapture
+        # Takes whatever Cucumber passes (file, media_type, filename, and any
+        # argument a later release adds) and forwards it untouched.
+        ruby2_keywords def attach(*args, &block)
+          result = super
+          Formatter.record_attachment(args[0], args[1])
+          result
+        end
+      end
+
+      @claimed = []
+
+      class << self
+        # One listener per run, whether it arrives as a --format or as a plugin.
+        # Cucumber copies the configuration for --out, but the event bus is shared.
+        def claim(config)
+          bus = config.event_bus
+          return false if @claimed.any? { |claimed| claimed.equal?(bus) }
+
+          @claimed << bus
+          true
+        end
+
+        # Inline text, IO objects and missing paths are ignored: only a file that
+        # exists can be copied. Never raises into the user's step.
+        def record_attachment(file, media_type)
+          # `log` is attach with this media type; a logged message is not a file.
+          return if media_type.to_s.start_with?("text/x.cucumber.log")
+
+          file = file.to_path if file.respond_to?(:to_path)
+          return unless file.is_a?(String) && RaiderReporter.collector&.in_test? && File.file?(file)
+
+          RaiderReporter.attach(File.basename(file), file, type: media_type)
+        rescue StandardError => e
+          RaiderReporter.warn("#{e.class}: #{e.message}")
+        end
+
+        # Called when the run ends, so the list does not outlive the run.
+        def release(config)
+          bus = config.event_bus
+          @claimed.reject! { |claimed| claimed.equal?(bus) }
+          RaiderReporter.dry_run = false
+        end
+
+        # Cucumber hands steps a World, not the formatter, so `attach` is observed
+        # by prepending to ProtoWorld. Installed once, at the first formatter.
+        # Event-bus alternatives were checked in cucumber 9.2.1, 10.2.0 and 11.1.1:
+        # there is no :attach_called event before 11, and even there (and in the
+        # :envelope attachment message) a file path has already been read into
+        # bytes with no name, so the basename the report needs is only available
+        # in ProtoWorld#attach, which exists unchanged in all three versions.
+        def capture_attach
+          return if @capturing
+
+          ::Cucumber::Glue::ProtoWorld.prepend(AttachCapture)
+          @capturing = true
+        end
+      end
+
+      def initialize(config)
+        @buffer = {}
+        @attempts = Hash.new(0)
+        @attempt = nil
+        guard { setup(config) if self.class.claim(config) }
+      end
+
+      private
+
+      def setup(config)
+        @config = config
+        @ast = ::Cucumber::Formatter::AstLookup.new(config)
+        @collector = RaiderReporter.start_collector!
+        RaiderReporter.dry_run = config.dry_run?
+        config.on_event(:test_run_started) { |_event| guard { @collector.start_run } }
+        config.on_event(:test_case_started) { |event| guard { case_started(event.test_case) } }
+        config.on_event(:test_step_finished) { |event| guard { step_finished(event.test_step, event.result) } }
+        config.on_event(:test_case_finished) { |event| guard { case_finished(event.test_case, event.result) } }
+        config.on_event(:test_run_finished) { |_event| guard { run_finished } }
+        # Last, and on its own: a broken attach hook may only lose attachments.
+        safely(nil) { self.class.capture_attach }
+      end
+
+      # Every attempt starts with an empty attachment list.
+      def case_started(test_case)
+        @collector.start_test
+        @attempt = { test_case: test_case }
+      end
+
+      # The first non-passed step explains why the scenario did not pass.
+      def step_finished(test_step, result)
+        return unless @attempt
+        return if @attempt[:problem] || result.passed?
+
+        @attempt[:problem] = { step: test_step, result: result }
+      end
+
+      def case_finished(test_case, result)
+        problem = @attempt && @attempt[:problem]
+        @attempt = nil
+        status = STATUSES.fetch(result.to_sym, "pending")
+        # Always buffer: a lookup problem may lose detail, never the scenario.
+        failure = status == "failed" ? safely(nil) { failure_for(problem, result, test_case) } : nil
+        fields = identity_for(test_case)
+        key = "#{test_case.location}|#{test_case.name}"
+        @attempts[key] += 1
+        # The newest attempt replaces the older one, taking its attachments with it.
+        @buffer[key] = @collector.build_test(
+          **fields, status: status, duration_ms: duration_ms(result), attempts: @attempts[key], failure: failure
+        )
+      end
+
+      def run_finished
+        @buffer.each_value { |result| @collector.add_result(result) }
+        @buffer.clear
+        RaiderReporter.finish!($stderr)
+      ensure
+        self.class.release(@config)
+      end
+
+      def identity_for(test_case)
+        file_path = relative_path(test_case.location.file)
+        line_number = test_case.location.lines.max
+        {
+          file_path: file_path,
+          line_number: line_number,
+          full_name: Text.utf8(full_name(test_case)),
+          identifier: "#{file_path}:#{line_number}",
+          tags: test_case.tags.map { |tag| tag.name.to_s.delete_prefix("@") }.uniq.sort
+        }
+      end
+
+      def full_name(test_case)
+        safely(test_case.name) do
+          feature = @ast.gherkin_document(test_case.location.file)&.feature
+          name = scenario_name(@ast.scenario_source(test_case))
+          next test_case.name unless name
+
+          feature ? "#{feature.name}: #{name}" : name
+        end
+      end
+
+      # nil when the scenario cannot be located in the AST.
+      def scenario_name(source)
+        case source&.type
+        when :ScenarioOutline
+          examples = source.examples
+          row = examples.table_body.index { |candidate| candidate.location.line == source.row.location.line }
+          row && "#{source.scenario_outline.name} (#{examples_label(source)}, row #{row + 1})"
+        when :Scenario
+          source.scenario.name
+        end
+      end
+
+      # "Examples" or the table's name. When several tables of one outline share a
+      # label (two unnamed ones, say), each gets its 1-based position among them,
+      # so rows of different tables never collide on full_name.
+      def examples_label(source)
+        tables = source.scenario_outline.examples
+        label = examples_name(source.examples)
+        same = tables.select { |table| examples_name(table) == label }
+        return label if same.size < 2
+
+        "#{label} #{same.index { |table| table.equal?(source.examples) || table.location.line == source.examples.location.line } + 1}"
+      end
+
+      def examples_name(table)
+        table.name.to_s.strip.empty? ? "Examples" : table.name.strip
+      end
+
+      # step_info is { step:, result: } for the first non-passed step, if any.
+      def failure_for(step_info, result, test_case)
+        exception = result.respond_to?(:exception) ? result.exception : nil
+        exception ||= step_info && step_info[:result].respond_to?(:exception) ? step_info[:result].exception : nil
+        return nil unless exception
+
+        Failure.new(
+          message: Text.utf8("#{step_label(step_info, test_case)}\n\n#{exception.message}")[0, Text::MAX_MESSAGE],
+          exception_class: Text.utf8(exception.class.name),
+          backtrace: (exception.backtrace || []).first(Text::MAX_BACKTRACE).map { |line| Text.utf8(line) }
+        )
+      end
+
+      def step_label(step_info, test_case)
+        return "Step" unless step_info
+
+        test_step = step_info[:step]
+        location = "(#{relative_path(test_step.location.file)}:#{test_step.location.lines.min})"
+        if test_step.hook?
+          "#{hook_kind(test_step, test_case)} hook #{location}"
+        else
+          "#{step_keyword(test_step)}#{test_step.text} #{location}"
+        end
+      end
+
+      def step_keyword(test_step)
+        safely("") { @ast.step_source(test_step).step.keyword.to_s }
+      end
+
+      # A hook with a real step before it runs after the scenario started.
+      def hook_kind(test_step, test_case)
+        steps = test_case.test_steps
+        index = steps.index { |candidate| candidate.equal?(test_step) }
+        index && steps.first(index).any? { |candidate| !candidate.hook? } ? "After" : "Before"
+      end
+
+      def duration_ms(result)
+        (result.duration.nanoseconds / 1_000_000.0).round
+      rescue StandardError
+        0
+      end
+
+      def relative_path(path)
+        absolute = Pathname.new(File.expand_path(path.to_s, Dir.pwd))
+        relative = absolute.relative_path_from(Pathname.new(Dir.pwd)).to_s
+        relative.start_with?("..") ? path.to_s.delete_prefix("./") : relative
+      rescue ArgumentError
+        # Windows: a path on another drive has no relative form.
+        path.to_s.delete_prefix("./")
+      end
+
+      def safely(fallback)
+        yield
+      rescue StandardError => e
+        RaiderReporter.warn("#{e.class}: #{e.message}")
+        fallback
+      end
+
+      def guard
+        yield
+      rescue StandardError => e
+        RaiderReporter.warn("#{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/raider_reporter/cucumber.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+begin
+  require "cucumber"
+rescue LoadError => e
+  raise unless e.path == "cucumber"
+
+  raise LoadError, "raider_reporter/cucumber needs the cucumber gem (>= 9, < 12) in your Gemfile"
+end
+require "raider_reporter"
+require_relative "cucumber/formatter"
+
+module RaiderReporter
+  module Cucumber
+    # Plugin mode: requiring this file from features/support registers the
+    # listener through Cucumber's InstallPlugin hook, so no --format is needed
+    # (and none of the "one formatter per stream" juggling). Outside a Cucumber
+    # run there is no step-definition registry and this is a no-op.
+    def self.install_plugin
+      # Cucumber's public InstallPlugin DSL method, called on a throwaway object
+      # (it is only an instance method of Dsl; main is extended with it).
+      Object.new.extend(::Cucumber::Glue::Dsl).InstallPlugin(name: "raider_reporter") do |config, *|
+        RaiderReporter::Cucumber::Formatter.new(config)
+      end
+      true
+    rescue StandardError => e
+      # Outside a run there is no registry (Dsl has no rb_language) and nothing to
+      # report. Inside one, losing the listener must not be silent.
+      RaiderReporter.warn("could not register the Cucumber plugin: #{e.class}: #{e.message}") if run_active?
+      false
+    end
+
+    def self.run_active?
+      !::Cucumber::Glue::Dsl.instance_variable_get(:@rb_language).nil?
+    end
+    private_class_method :run_active?
+  end
+end
+
+RaiderReporter::Cucumber.install_plugin

data/lib/raider_reporter/github_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RaiderReporter
+  # Reads the webhook payload GitHub Actions leaves at GITHUB_EVENT_PATH.
+  module GithubEvent
+    # Returns the parsed event Hash, or nil when missing, unreadable or invalid.
+    def self.load(env = ENV)
+      path = env["GITHUB_EVENT_PATH"].to_s
+      return nil if path.empty?
+
+      data = JSON.parse(File.read(path))
+      data.is_a?(Hash) ? data : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/raider_reporter/rspec/formatter.rb

@@ -2,6 +2,7 @@
 
 require "rspec/core"
 require "raider_reporter"
+require "raider_reporter/text"
 
 module RaiderReporter
   module RSpec
@@ -13,8 +14,8 @@ module RaiderReporter
                                          :example_failed, :example_pending, :close
 
       NON_TAG_KEYS = %i[pending skip].freeze
-      MAX_MESSAGE = 10_000
-      MAX_BACKTRACE = 50
+      MAX_MESSAGE = Text::MAX_MESSAGE
+      MAX_BACKTRACE = Text::MAX_BACKTRACE
 
       def initialize(output)
         @output = output
@@ -45,7 +46,7 @@ module RaiderReporter
       end
 
       def close(_notification)
-        guard { RaiderReporter.finish!(@output) }
+        guard { RaiderReporter.finish! }
       end
 
       private
@@ -77,14 +78,8 @@ module RaiderReporter
         )
       end
 
-      # JSON generation raises on invalid UTF-8, which would lose the whole run.
       def utf8(value)
-        str = value.to_s
-        if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(str.encoding)
-          str.dup.force_encoding(Encoding::UTF_8).scrub("?")
-        else
-          str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
-        end
+        Text.utf8(value)
       end
 
       def guard

data/lib/raider_reporter/text.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RaiderReporter
+  # Text limits and cleaning shared by the framework formatters.
+  module Text
+    MAX_MESSAGE = 10_000
+    MAX_BACKTRACE = 50
+
+    # JSON generation raises on invalid UTF-8, which would lose the whole run.
+    def self.utf8(value)
+      str = value.to_s
+      if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(str.encoding)
+        str.dup.force_encoding(Encoding::UTF_8).scrub("?")
+      else
+        str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
+      end
+    end
+  end
+end

data/lib/raider_reporter/version.rb

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

data/lib/raider_reporter.rb

@@ -3,6 +3,7 @@
 require "time"
 require "rbconfig"
 require_relative "raider_reporter/version"
+require_relative "raider_reporter/text"
 require_relative "raider_reporter/models"
 require_relative "raider_reporter/payload"
 require_relative "raider_reporter/configuration"
@@ -12,6 +13,8 @@ require_relative "raider_reporter/writers/local"
 require_relative "raider_reporter/ci_detector"
 require_relative "raider_reporter/shard_detector"
 require_relative "raider_reporter/writers/uploader"
+require_relative "raider_reporter/comment/summary_client"
+require_relative "raider_reporter/comment/github_client"
 
 module RaiderReporter
   class << self
@@ -25,13 +28,18 @@ module RaiderReporter
       yield configuration
     end
 
+    # Set by the Cucumber formatter when the run is a --dry-run.
+    attr_writer :dry_run
+
     def reset!
+      @dry_run = false
       @collector&.cleanup
       @configuration = nil
       @collector = nil
     end
 
     def start_collector!
+      @dry_run = false
       @collector = Collector.new(
         max_attachment_bytes: configuration.max_attachment_bytes,
         warn: ->(message) { warn(message) }
@@ -66,7 +74,7 @@ module RaiderReporter
       $stderr.puts("[raider_reporter] #{message}")
     end
 
-    def finish!(output = $stdout)
+    def finish!(output = $stderr)
       return nil if dry_run?
 
       detector = CiDetector.new
@@ -102,8 +110,10 @@ module RaiderReporter
       "Raider report uploaded"
     end
 
-    # `rspec --dry-run` reports every example as passed without running it.
+    # `rspec --dry-run` and `cucumber --dry-run` report every example as passed without running it.
     def dry_run?
+      return true if @dry_run
+
       defined?(::RSpec.configuration) && ::RSpec.configuration.respond_to?(:dry_run?) &&
         ::RSpec.configuration.dry_run?
     end

metadata

@@ -1,35 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: raider_reporter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Augustin Gottlieb
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: RSpec formatter that records results, screenshots and videos in the Raider
-  schema, writes them locally, and optionally uploads them to a Raider server.
+description: RSpec and Cucumber formatters that record results, screenshots and videos
+  in the Raider schema, write them locally, and optionally upload them to a Raider
+  server.
 email:
 - 33221555+aguspe@users.noreply.github.com
-executables: []
+executables:
+- raider-reporter
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/raider-reporter
 - lib/raider_reporter.rb
 - lib/raider_reporter/ci_detector.rb
+- lib/raider_reporter/cli.rb
 - lib/raider_reporter/collector.rb
+- lib/raider_reporter/comment/github_client.rb
+- lib/raider_reporter/comment/summary_client.rb
 - lib/raider_reporter/configuration.rb
 - lib/raider_reporter/content_types.rb
+- lib/raider_reporter/cucumber.rb
+- lib/raider_reporter/cucumber/formatter.rb
+- lib/raider_reporter/github_event.rb
 - lib/raider_reporter/models.rb
 - lib/raider_reporter/payload.rb
 - lib/raider_reporter/rspec.rb
 - lib/raider_reporter/rspec/formatter.rb
 - lib/raider_reporter/shard_detector.rb
+- lib/raider_reporter/text.rb
 - lib/raider_reporter/version.rb
 - lib/raider_reporter/writers/local.rb
 - lib/raider_reporter/writers/uploader.rb
@@ -56,5 +66,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: 'Test reporting for Ruby Raider: local run.json and Raider uploads'
+summary: RSpec and Cucumber formatters that write Raider reports locally and upload
+  them to Raider
 test_files: []