From ad985d43260614a00267e35e81b9e4d1f789c0ef Mon Sep 17 00:00:00 2001 From: LuukvH Date: Mon, 16 Nov 2026 12:10:08 +0100 Subject: [PATCH 1/2] feat: Link annotations to the spec file at the failing line The annotation link that GitHub generates opens the commit view, which only shows files changed in that commit. Append a link to the spec file at the failing line in the tested revision to the annotation message. For pull_request events the pull request head commit is used instead of the temporary merge commit. Refs #92 --- README.md | 2 + lib/rspec/github/notification_decorator.rb | 31 ++++++++++- spec/rspec/github/formatter_spec.rb | 63 ++++++++++++++++++++++ 3 files changed, 94 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9e2603d..dadcb8a 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,8 @@ rspec --format RSpec::Github::Formatter --format progress rspec --format RSpec::Github::Formatter --format documentation ``` +When running in GitHub Actions, each annotation ends with a link to the spec file at the failing line in the tested commit (for pull requests, the head commit of the pull request). The annotation's own link goes to the commit view, which only shows files changed in that commit. + If you want to disable annotations for pending specs you can do that by adding `--tag ~skip` to your command: ```bash rspec --format RSpec::Github::Formatter --tag ~skip diff --git a/lib/rspec/github/notification_decorator.rb b/lib/rspec/github/notification_decorator.rb index f260308..198bdf4 100644 --- a/lib/rspec/github/notification_decorator.rb +++ b/lib/rspec/github/notification_decorator.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +require 'json' + module RSpec module Github class NotificationDecorator @@ -19,8 +21,19 @@ def line end def annotation - "#{example.full_description}\n\n#{message}" - .gsub(Regexp.union(ESCAPE_MAP.keys), ESCAPE_MAP) + [example.full_description, message, file_url].compact.join("\n\n") + .gsub(Regexp.union(ESCAPE_MAP.keys), ESCAPE_MAP) + end + + # Link to the spec file at the failing line in the tested revision. The annotation itself + # links to the commit view, which does not show files that were not changed in that commit. + def file_url + server_url = ENV.fetch('GITHUB_SERVER_URL', nil) + repository = ENV.fetch('GITHUB_REPOSITORY', nil) + sha = commit_sha + return if [server_url, repository, sha].any? { |value| value.nil? || value.empty? } + + "#{server_url}/#{repository}/blob/#{sha}/#{path}#L#{line}" end def path @@ -46,6 +59,20 @@ def raw_path example.location.split(':')[0] end + # On pull_request events GITHUB_SHA is a temporary merge commit, so prefer the PR head commit. + def commit_sha + pull_request_head_sha || ENV.fetch('GITHUB_SHA', nil) + end + + def pull_request_head_sha + event_path = ENV.fetch('GITHUB_EVENT_PATH', nil) + return unless event_path && File.file?(event_path) + + JSON.parse(File.read(event_path)).dig('pull_request', 'head', 'sha') + rescue JSON::ParserError + nil + end + def workspace File.realpath(ENV.fetch('GITHUB_WORKSPACE', '.')) end diff --git a/spec/rspec/github/formatter_spec.rb b/spec/rspec/github/formatter_spec.rb index 808e76b..441e571 100644 --- a/spec/rspec/github/formatter_spec.rb +++ b/spec/rspec/github/formatter_spec.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +require 'json' +require 'tempfile' require 'tmpdir' RSpec.describe RSpec::Github::Formatter do @@ -30,6 +32,18 @@ ) end + let(:github_env) { {} } + + around do |example| + keys = %w[GITHUB_SERVER_URL GITHUB_REPOSITORY GITHUB_SHA GITHUB_EVENT_PATH] + saved = keys.to_h { |key| [key, ENV.fetch(key, nil)] } + keys.each { |key| ENV.delete(key) } + github_env.each { |key, value| ENV[key] = value } + example.run + ensure + saved.each { |key, value| ENV[key] = value } + end + before do allow(File).to receive(:realpath).and_call_original allow(File).to receive(:realpath).with('./spec/models/user_spec.rb') @@ -61,6 +75,55 @@ MESSAGE end + context 'when running in GitHub Actions' do + let(:github_env) do + { + 'GITHUB_SERVER_URL' => 'https://github.com', + 'GITHUB_REPOSITORY' => 'octo/repo', + 'GITHUB_SHA' => 'abc123' + } + end + + it 'appends a link to the spec file at the failing line' do + is_expected.to eq <<~MESSAGE + + ::error file=spec/models/user_spec.rb,line=12::#{example.full_description}%0A%0A#{notification.message_lines.join('%0A')}%0A%0Ahttps://github.com/octo/repo/blob/abc123/spec/models/user_spec.rb#L12 + MESSAGE + end + + context 'on a pull_request event' do + let(:event_file) do + Tempfile.new(['event', '.json']).tap do |file| + file.write({ pull_request: { head: { sha: 'def456' } } }.to_json) + file.flush + end + end + let(:github_env) { super().merge('GITHUB_EVENT_PATH' => event_file.path) } + + after { event_file.close! } + + it 'links to the pull request head commit instead of the merge commit' do + is_expected.to include 'https://github.com/octo/repo/blob/def456/spec/models/user_spec.rb#L12' + end + end + + context 'with an event file without a pull request' do + let(:event_file) do + Tempfile.new(['event', '.json']).tap do |file| + file.write({ ref: 'refs/heads/master' }.to_json) + file.flush + end + end + let(:github_env) { super().merge('GITHUB_EVENT_PATH' => event_file.path) } + + after { event_file.close! } + + it 'links to GITHUB_SHA' do + is_expected.to include 'https://github.com/octo/repo/blob/abc123/spec/models/user_spec.rb#L12' + end + end + end + context 'relative_path to GITHUB_WORKSPACE' do around do |example| saved_github_workspace = ENV.fetch('GITHUB_WORKSPACE', nil) From 28b3b8644827197505abd08bb6ef419c87281d5d Mon Sep 17 00:00:00 2001 From: LuukvH Date: Mon, 16 Nov 2026 12:14:54 +0100 Subject: [PATCH 2/2] fix: Encode spec path and link to the tested commit Percent-encode each path segment so characters like # or spaces don't break the link, and always use GITHUB_SHA so the link points at the commit that was actually tested (the merge commit on pull_request events), keeping line numbers in sync with the annotation. --- README.md | 2 +- lib/rspec/github/notification_decorator.rb | 26 +++++--------- spec/rspec/github/formatter_spec.rb | 42 +++++----------------- 3 files changed, 19 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index dadcb8a..5b3c593 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ rspec --format RSpec::Github::Formatter --format progress rspec --format RSpec::Github::Formatter --format documentation ``` -When running in GitHub Actions, each annotation ends with a link to the spec file at the failing line in the tested commit (for pull requests, the head commit of the pull request). The annotation's own link goes to the commit view, which only shows files changed in that commit. +When running in GitHub Actions, each annotation ends with a link to the spec file at the failing line in the tested commit (`GITHUB_SHA`, which for pull requests is the merge commit GitHub tests). The annotation's own link goes to the commit view, which only shows files changed in that commit. If you want to disable annotations for pending specs you can do that by adding `--tag ~skip` to your command: ```bash diff --git a/lib/rspec/github/notification_decorator.rb b/lib/rspec/github/notification_decorator.rb index 198bdf4..7914e5f 100644 --- a/lib/rspec/github/notification_decorator.rb +++ b/lib/rspec/github/notification_decorator.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -require 'json' +require 'erb' module RSpec module Github @@ -25,15 +25,16 @@ def annotation .gsub(Regexp.union(ESCAPE_MAP.keys), ESCAPE_MAP) end - # Link to the spec file at the failing line in the tested revision. The annotation itself - # links to the commit view, which does not show files that were not changed in that commit. + # Link to the spec file at the failing line in the tested commit (GITHUB_SHA, which is the merge + # commit on pull_request events). The annotation itself links to the commit view, which does not + # show files that were not changed in that commit. def file_url server_url = ENV.fetch('GITHUB_SERVER_URL', nil) repository = ENV.fetch('GITHUB_REPOSITORY', nil) - sha = commit_sha + sha = ENV.fetch('GITHUB_SHA', nil) return if [server_url, repository, sha].any? { |value| value.nil? || value.empty? } - "#{server_url}/#{repository}/blob/#{sha}/#{path}#L#{line}" + "#{server_url}/#{repository}/blob/#{sha}/#{url_path}#L#{line}" end def path @@ -59,18 +60,9 @@ def raw_path example.location.split(':')[0] end - # On pull_request events GITHUB_SHA is a temporary merge commit, so prefer the PR head commit. - def commit_sha - pull_request_head_sha || ENV.fetch('GITHUB_SHA', nil) - end - - def pull_request_head_sha - event_path = ENV.fetch('GITHUB_EVENT_PATH', nil) - return unless event_path && File.file?(event_path) - - JSON.parse(File.read(event_path)).dig('pull_request', 'head', 'sha') - rescue JSON::ParserError - nil + # Percent-encode each path segment so characters like `#` or spaces don't break the URL. + def url_path + path.split('/').map { |segment| ERB::Util.url_encode(segment) }.join('/') end def workspace diff --git a/spec/rspec/github/formatter_spec.rb b/spec/rspec/github/formatter_spec.rb index 441e571..d09db5a 100644 --- a/spec/rspec/github/formatter_spec.rb +++ b/spec/rspec/github/formatter_spec.rb @@ -1,7 +1,5 @@ # frozen_string_literal: true -require 'json' -require 'tempfile' require 'tmpdir' RSpec.describe RSpec::Github::Formatter do @@ -35,7 +33,7 @@ let(:github_env) { {} } around do |example| - keys = %w[GITHUB_SERVER_URL GITHUB_REPOSITORY GITHUB_SHA GITHUB_EVENT_PATH] + keys = %w[GITHUB_SERVER_URL GITHUB_REPOSITORY GITHUB_SHA] saved = keys.to_h { |key| [key, ENV.fetch(key, nil)] } keys.each { |key| ENV.delete(key) } github_env.each { |key, value| ENV[key] = value } @@ -46,8 +44,9 @@ before do allow(File).to receive(:realpath).and_call_original - allow(File).to receive(:realpath).with('./spec/models/user_spec.rb') - .and_return(File.join(Dir.pwd, 'spec/models/user_spec.rb')) + raw_path = location.split(':').first + allow(File).to receive(:realpath).with(raw_path) + .and_return(File.expand_path(raw_path, Dir.pwd)) end describe '#example_failed' do @@ -91,35 +90,12 @@ MESSAGE end - context 'on a pull_request event' do - let(:event_file) do - Tempfile.new(['event', '.json']).tap do |file| - file.write({ pull_request: { head: { sha: 'def456' } } }.to_json) - file.flush - end - end - let(:github_env) { super().merge('GITHUB_EVENT_PATH' => event_file.path) } - - after { event_file.close! } - - it 'links to the pull request head commit instead of the merge commit' do - is_expected.to include 'https://github.com/octo/repo/blob/def456/spec/models/user_spec.rb#L12' - end - end - - context 'with an event file without a pull request' do - let(:event_file) do - Tempfile.new(['event', '.json']).tap do |file| - file.write({ ref: 'refs/heads/master' }.to_json) - file.flush - end - end - let(:github_env) { super().merge('GITHUB_EVENT_PATH' => event_file.path) } - - after { event_file.close! } + context 'when the path contains characters that are not URL safe' do + let(:location) { './spec/models/user#admin spec.rb:12' } - it 'links to GITHUB_SHA' do - is_expected.to include 'https://github.com/octo/repo/blob/abc123/spec/models/user_spec.rb#L12' + it 'percent-encodes the path in the link' do + # `%` is escaped once more as `%25` by the workflow command; GitHub unescapes it to `%23` / `%20`. + is_expected.to include 'https://github.com/octo/repo/blob/abc123/spec/models/user%2523admin%2520spec.rb#L12' end end end