rspec-tracer 1.2.2 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f6c19e285b64650bd4f02c5820fed75c10806ebb97900e17607b84532dfb483
-  data.tar.gz: a4e17229c1efa3d43e1cc850b908cb9bbcb16fb6f217098348675ce2a798c993
+  metadata.gz: 5a5c7bccaf770c4b630f3aafbe2965e7a88eebf912d4e5f331eb6001613e0559
+  data.tar.gz: cd2c8bb4ea28fa5c70807e8ca7e9249e16a7313f9e17662e3b76d20cc26a91ab
 SHA512:
-  metadata.gz: 25571686f98b2c1939a0497f3c34a7f0508d856ba94ac2aabd6f293815a4e61ad8cb2b56d8a22c4ff211692a6609c1f8671d6b55f35d2123301d15bf8d70649b
-  data.tar.gz: 1c86b20818bc6f18bc5a3faf69f6a7b7908b1ab6006a1301341883edb46f3d180db3cd6308978f9d12dbd6f9b427dcd478c3addc7888f78faa64dc1b325897ce
+  metadata.gz: 2a5889f5a017183e40e63b56c10b6abf2309dff7b18ca941c2f36552e947b508ca3ac144290143a44b2bf78c7f76569eba96d1d580f69eb9a2d2a138e3c004ba
+  data.tar.gz: 79ff93be56d9f9bee3c397b0d78ef0cb4114b5c746879d9afcbf6372d2eb55a8950b75f772372c78aaea3852a12a0750a1098758cf343c41c9caa86b485ac054

data/CHANGELOG.md

@@ -1,3 +1,128 @@
+## [1.2.4] - 2026-05-17
+
+### Fixed
+
+- **`example_id` was unstable across runs — a long-standing bug since
+  v1.0.0.** `RSpecTracer::Example.from` built the MD5 identity hash
+  over a payload that included `example_group.name` (RSpec's
+  generated class name, which carries a load-order-dependent `_2` /
+  `_3` suffix when two spec files share a `describe` name) and the
+  example's `line_number`. The same example got a different id
+  depending on rspec's file load order — silently thrashing the
+  cache and breaking the always-re-run guarantees for failed,
+  pending, and flaky examples. A no-op blank-line edit above the
+  example flipped the id with the same effect.
+
+  The digest now uses a stable subset: the describe block's
+  *description* string (the user-supplied text, not RSpec's
+  generated class name), the example's `description`,
+  `full_description`, `shared_group` inclusion locations with the
+  trailing `:LINE` stripped, and `file_name`. `line_number` /
+  `rerun_file_name` / `rerun_line_number` still ride along in the
+  returned Hash for the HTML and JSON reporters' location columns,
+  but no longer enter the digest. Contract: **rename = new identity;
+  restructure = same identity.**
+
+  Unnamed examples (`it { }`, `specify { }`, `example { }`) needed
+  an extra step. RSpec's pre-run `description` for an unnamed
+  example is the line-bearing `"example at <path>:<line>"`
+  fallback, which would have re-leaked the line number straight
+  into the digest. The digest substitutes a line-independent
+  positional discriminator: the example's ordinal among the
+  *unnamed* examples of its group. Stability is preserved across
+  blank-line edits and across adding or renaming *named* siblings;
+  reordering the unnamed examples re-keys them (the documented
+  trade-off — give the example an explicit description for a fully
+  reorder-stable id).
+
+  **Upgrade note**: the cache file format is unchanged, so a v1.2.3
+  cache loads cleanly through v1.2.4 code. But every cached
+  `example_id` was computed against the old payload and the new
+  lookups will not match them, so the first run after upgrade
+  treats every example as `:no_cache` and re-runs the full suite.
+  Warm caches resume from the second run onward.
+
+  Surfaced by 2.0.0.pre.1 field testing against third-party Rails
+  apps. Fixed upstream in
+  [#209](https://github.com/avmnu-sng/rspec-tracer/pull/209) and
+  [#211](https://github.com/avmnu-sng/rspec-tracer/pull/211).
+
+- **`RSpecTracer.start` crashed when the user pre-started
+  `::Coverage`.** Users opting into branch coverage typically call
+  `Coverage.start(lines: true, branches: true)` before loading
+  rspec-tracer. The tracer's `setup_coverage` then called bare
+  `::Coverage.start` with no `running?` guard, raising
+  `RuntimeError: coverage measurement is already setup` and taking
+  the tracer down at boot.
+
+  Add a `Coverage.running?` predicate guard before the start call,
+  plus a defensive `RuntimeError` rescue with a `logger.warn` for
+  the case where the predicate returns false but `start` still
+  raises. Graceful degradation: coverage measurement is skipped
+  with a visible warn, the rest of the tracer pipeline continues.
+
+  Partial port of upstream
+  [#207](https://github.com/avmnu-sng/rspec-tracer/pull/207); the
+  `coverage_modes` config DSL half is 2.0-only.
+
+- **`remote_cache` success paths were silent at default log level.**
+  `RemoteCache::Cache#download` and `#upload` returned without
+  emitting anything after the underlying AWS calls succeeded, so a
+  successful `rake rspec_tracer:remote_cache:download` produced
+  zero output. Users couldn't tell from CI logs whether the cache
+  was actually restored or whether the run was cold.
+
+  Emit a single `RSpecTracer.logger.info` line on each operation's
+  success path: `"rspec-tracer remote_cache: restored cache from
+  <sha>"` on download, `"rspec-tracer remote_cache: uploaded cache
+  to <ref>"` on upload.
+
+  Partial port of upstream
+  [#201](https://github.com/avmnu-sng/rspec-tracer/pull/201); the
+  cross-branch-fallback qualifier is specific to 2.0's multi-tier
+  cache model and not applicable here.
+
+### Changed
+
+- **`rspec-tracer.gemspec` now declares `rubygems_mfa_required`** so
+  RubyGems enforces MFA on every publish. Packaging metadata only;
+  no behaviour change for users of the gem. Mirrors upstream
+  [#214](https://github.com/avmnu-sng/rspec-tracer/pull/214).
+
+- **`.github/workflows/release.yml` tag-trigger pattern tightened
+  to the strict `'v[0-9]+.[0-9]+.[0-9]+'` form** (1.x is
+  final-release only). The previous loose `'v*.*.*'` form would
+  have matched 4-segment shapes like `v2.0.0.rc.1` accidentally
+  because `*` greedy-matches dots; the strict per-segment digit
+  class rejects any non-digit. Documentation block above the
+  pattern explains the GHA filter-pattern flavor for future
+  maintainers. Workflow-only; no user-visible change.
+
+## [1.2.3] - 2026-05-06
+
+### Fixed
+
+- **Parallel-tests purge race when a sibling worker is still mid-flush**
+  — the elected worker trusted only `parallel_tests`'s pid-file barrier
+  (`ParallelTests.wait_for_other_processes_to_finish`), which under
+  specific scheduling/I/O timing on GHA Linux x86_64 can return while a
+  sibling's `parallel_tests_N/` dir hasn't fully flushed. The elected
+  then merged + purged, racing the in-progress sibling. Symptoms:
+  intermittent leftover `parallel_tests_N/` dir post-purge AND/OR
+  silently dropped peer caches in the merge.
+
+  Backport of upstream PR
+  [#168](https://github.com/avmnu-sng/rspec-tracer/pull/168). Adds a
+  filesystem barrier layered on top of the pid-file wait. Each worker
+  writes a `.rspec_tracer_boot` marker at `RSpecTracer.start` time and
+  a `.rspec_tracer_done` marker as the first step of its at_exit tasks;
+  the elected worker waits for every booted peer's `.done` to
+  materialize before proceeding to merge + purge. Two independent
+  signals (pid file + filesystem) must agree before the elected worker
+  declares the peer set stable. Bounded at 5 s with a graceful warn for
+  crashed peers — their dirs are purged regardless of completion state,
+  and the merge accepts whatever's on disk.
+
 ## [1.2.2] - 2026-05-04
 
 ### Fixed

data/lib/rspec_tracer/example.rb

@@ -1,19 +1,122 @@
 # frozen_string_literal: true
 
 module RSpecTracer
+  # Builds the identity-hash payload (`:example_id`-keyed Hash) that
+  # RSpec::RunnerHook attaches to every example pre-run.
+  #
+  # == Identity stability contract
+  #
+  # `example_id` is the MD5 of a stable subset of the payload:
+  # `example_group` (the describe block's *description* string),
+  # `description`, `full_description`, `shared_group` (inclusion
+  # locations with the trailing line number stripped), and
+  # `file_name`. The contract, in one line: *rename = new identity;
+  # restructure = same identity.*
+  #
+  # Identity is PRESERVED when:
+  # - blank lines or comments are added/removed around the example
+  # - examples are reordered within a describe block (named
+  #   examples only - see "Unnamed examples" below)
+  # - a sibling describe / example in the same file is renamed
+  # - the example body or its hooks (`before`, `let`) are edited -
+  #   the file digest still triggers the re-run
+  #
+  # Identity CHANGES (one cold "No cache" run) when:
+  # - the file is renamed or moved
+  # - the `describe` / `it` / shared-example name is changed
+  # - the example moves to a different describe block
+  #
+  # == Unnamed examples (`it { }`, `specify { }`, `example { }`)
+  #
+  # An example with no description string has no stable name to hash,
+  # and identity must be computed pre-run (for the filter decision),
+  # before RSpec generates a matcher-derived description. The only
+  # line-independent signal RSpec exposes pre-run is position, so an
+  # unnamed example's identity is derived from its ordinal among the
+  # *unnamed* examples of its group. (RSpec's `description` for an
+  # unnamed example is the line-bearing `"example at <path>:<line>"`
+  # fallback, which would otherwise leak the line number straight
+  # back into the digest.)
+  #
+  # For unnamed examples the contract above is amended: identity is
+  # still PRESERVED across blank-line / comment edits, sibling
+  # renames, and adding or removing *named* siblings - but it CHANGES
+  # when the unnamed examples are reordered, or one is inserted or
+  # removed ahead of it. Give an example an explicit description
+  # (`it 'does X' do`) for a fully reorder-stable identity.
+  #
+  # `line_number` / `rerun_file_name` / `rerun_line_number` stay in
+  # the returned Hash for the reporter location columns, but are
+  # DELIBERATELY EXCLUDED from the digest - a no-op edit that shifts
+  # line numbers must not invalidate the cache. `example_group` uses
+  # `example_group.description` (the user's string) rather than
+  # `example_group.name`: RSpec's generated class name carries a
+  # load-order-dependent `_2` / `_3` suffix when two files share a
+  # describe name, which would otherwise flip the id across runs.
   module Example
     module_function
 
+    # Identity-keyed cache of `<example_group> => Array<unnamed sibling>`
+    # populated lazily by `unnamed_description`. A group with N unnamed
+    # examples computes the sibling list once per group rather than N
+    # times. Memory is bounded by the live example_group set, which
+    # RSpec retains for the run lifetime anyway.
+    @unnamed_siblings_cache = {}.compare_by_identity
+
     def from(example)
-      data = {
-        example_group: example.example_group.name,
+      location = example_location(example)
+      identity = {
+        example_group: example.example_group.description,
         description: example.description,
         full_description: example.full_description,
         shared_group: example.metadata[:shared_group_inclusion_backtrace]
-          .map(&:formatted_inclusion_location)
-      }.merge(example_location(example))
+          .map { |frame| frame.formatted_inclusion_location.sub(/:\d+\z/, '') },
+        file_name: location[:file_name]
+      }
+
+      identity
+        .merge(location)
+        .merge(example_id: Digest::MD5.hexdigest(digest_identity(example, identity).to_json))
+    end
+
+    # The Hash actually fed to the MD5. For a named example this is
+    # `identity` unchanged. For an unnamed example RSpec's
+    # `description` is the line-bearing `"example at <path>:<line>"`
+    # fallback, so `description` is swapped for a line-independent
+    # positional discriminator before hashing. The returned/stored
+    # payload still carries RSpec's `description` / `full_description`
+    # untouched - only the digest input differs.
+    def digest_identity(example, identity)
+      return identity unless unnamed?(example)
+
+      identity.merge(description: unnamed_description(example))
+    end
+
+    # True when the example has no explicit description string. RSpec's
+    # raw `metadata[:description]` is `""` for `it { }` / `specify { }`
+    # / `example { }`; the `description` *method* would instead return
+    # the line-bearing fallback, so the raw metadata value is what
+    # cleanly tells named from unnamed.
+    def unnamed?(example)
+      example.metadata[:description].to_s.strip.empty?
+    end
+
+    # Line-independent identity discriminator for an unnamed example:
+    # its 0-based ordinal among the *unnamed* examples of its group.
+    # Stable across blank-line edits and across adding or renaming
+    # *named* siblings; changes only when the unnamed examples are
+    # reordered or one is inserted/removed ahead of it. The string
+    # takes a Ruby-inspect-style `#<...>` form so that even if a user
+    # description literally matched, full_description would still
+    # differ between the unnamed example (`"<group> "`) and the named
+    # one (`"<group> #<...>"`), keeping digest collisions structurally
+    # impossible.
+    def unnamed_description(example)
+      group = example.example_group
+      unnamed_siblings = @unnamed_siblings_cache[group] ||=
+        group.examples.select { |sibling| unnamed?(sibling) }
 
-      data.merge(example_id: Digest::MD5.hexdigest(data.to_json))
+      "#<rspec-tracer unnamed example #{unnamed_siblings.index(example)}>"
     end
 
     def example_location(example)
@@ -53,6 +156,7 @@ module RSpecTracer
       RSpecTracer::SourceFile.file_name(file_path)
     end
 
-    private_class_method :example_location, :example_rerun_location, :location_file_name
+    private_class_method :digest_identity, :unnamed?, :unnamed_description,
+                         :example_location, :example_rerun_location, :location_file_name
   end
 end

data/lib/rspec_tracer/remote_cache/cache.rb

@@ -19,11 +19,13 @@ module RSpecTracer
 
         @aws.download_file(@cache_sha, 'last_run.json')
         @aws.download_dir(@cache_sha, last_run_id)
+        RSpecTracer.logger.info "rspec-tracer remote_cache: restored cache from #{@cache_sha}"
       end
 
       def upload
         @aws.upload_file(@repo.branch_ref, 'last_run.json')
         @aws.upload_dir(@repo.branch_ref, last_run_id)
+        RSpecTracer.logger.info "rspec-tracer remote_cache: uploaded cache to #{@repo.branch_ref}"
 
         file_name = File.join(RSpecTracer.cache_path, 'branch_refs.json')
 

data/lib/rspec_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RSpecTracer
-  VERSION = '1.2.2'
+  VERSION = '1.2.4'
 end

data/lib/rspec_tracer.rb

@@ -30,6 +30,17 @@ require_relative 'rspec_tracer/time_formatter'
 require_relative 'rspec_tracer/version'
 
 module RSpecTracer
+  # Filesystem barrier markers, layered on top of parallel_tests's
+  # pid-file wait to defend against the GHA-observed race where the
+  # gem's `wait_for_other_processes_to_finish` returns while a sibling
+  # worker hasn't fully flushed its `parallel_tests_N/` dir yet. Each
+  # worker writes BOOT at setup-time and DONE as the first step of its
+  # at_exit tasks; the elected worker waits for every booted peer's
+  # DONE marker (deadline-bounded) before proceeding to merge + purge.
+  PARALLEL_TESTS_BOOT_MARKER_FILENAME = '.rspec_tracer_boot'
+  PARALLEL_TESTS_DONE_MARKER_FILENAME = '.rspec_tracer_done'
+  PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS = 5
+
   class << self
     attr_accessor :running, :pid, :no_examples, :duplicate_examples
 
@@ -186,6 +197,29 @@ module RSpecTracer
       RSpecTracer.logger.error "Failed to load parallel tests (Error: #{e.message})"
     ensure
       track_parallel_tests_test_env_number
+      parallel_tests_touch_boot!
+    end
+
+    # Per-worker boot marker. Source-of-truth for "this worker booted
+    # past `RSpecTracer.start`", consumed by the elected worker's
+    # finalize-time peer enumeration. Idempotent; failures are warned
+    # and absorbed (boot-marker write must never block test execution).
+    def parallel_tests_touch_boot!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_BOOT_MARKER_FILENAME),
+        JSON.generate(
+          pid: Process.pid,
+          test_env_number: ENV.fetch('TEST_ENV_NUMBER', ''),
+          started_at: Time.now.utc.iso8601
+        )
+      )
+    rescue StandardError => e
+      RSpecTracer.logger.warn(
+        "RSpec tracer: failed to write boot marker (#{e.class}: #{e.message})"
+      )
     end
 
     def track_parallel_tests_test_env_number
@@ -225,8 +259,11 @@ module RSpecTracer
       return if simplecov?
 
       require 'coverage'
+      return if ::Coverage.running?
 
       ::Coverage.start
+    rescue RuntimeError => e
+      RSpecTracer.logger.warn "coverage measurement setup skipped: #{e.message}"
     end
 
     def setup_trace_point
@@ -315,6 +352,15 @@ module RSpecTracer
     end
 
     def run_parallel_tests_exit_tasks
+      # Every worker — elected or not — drops its `.done` marker as the
+      # first thing in finalize so the elected worker's
+      # `parallel_tests_wait_for_peer_done_markers!` can observe it.
+      # Non-elected workers stop here; the elected worker proceeds to
+      # the merge + purge sequence (gated by `parallel_tests_executed?`,
+      # which now layers the peer-done barrier on top of the existing
+      # pid-file wait).
+      parallel_tests_touch_done!
+
       return unless parallel_tests_executed?
 
       merge_parallel_tests_reports
@@ -324,6 +370,26 @@ module RSpecTracer
       purge_parallel_tests_reports
     end
 
+    # Per-worker done marker. Written by every worker (elected or not)
+    # as the first step of `run_parallel_tests_exit_tasks`. Pairs with
+    # the boot marker for the elected worker's peer-done barrier:
+    # presence of `.done` means "this worker has signalled completion
+    # of its own writes"; absence (with `.boot` present) means "still
+    # mid-flush or crashed". Idempotent; failures are warned + absorbed.
+    def parallel_tests_touch_done!
+      return unless parallel_tests?
+
+      FileUtils.mkdir_p(RSpecTracer.cache_path)
+      File.write(
+        File.join(RSpecTracer.cache_path, PARALLEL_TESTS_DONE_MARKER_FILENAME),
+        Time.now.utc.iso8601
+      )
+    rescue StandardError => e
+      RSpecTracer.logger.warn(
+        "RSpec tracer: failed to write done marker (#{e.class}: #{e.message})"
+      )
+    end
+
     def merge_parallel_tests_reports
       return unless parallel_tests_executed?
 
@@ -423,9 +489,64 @@ module RSpecTracer
 
       ParallelTests.wait_for_other_processes_to_finish
 
+      # Belt-and-suspenders barrier: pid-file said everyone's done, but
+      # the gem's `wait_for_other_processes_to_finish` has been observed
+      # on GHA Linux x86_64 to return while a sibling's `parallel_tests_N/`
+      # is still mid-flush. Cross-check via the `.boot`/`.done` filesystem
+      # markers before declaring the peer set stable. Idempotent: once
+      # all peers have flushed, subsequent calls just glob, find nothing
+      # missing, and return.
+      parallel_tests_wait_for_peer_done_markers!
+
       true
     end
 
+    # Block until every peer that wrote `.boot` has also written `.done`,
+    # or the deadline elapses. Polled at 50ms — fine enough to close the
+    # typical "barrier returned a tick early" case within a poll or two,
+    # coarse enough not to dominate CPU.
+    #
+    # On timeout we log a warn and proceed: a peer that never wrote
+    # `.done` either crashed (then its dir is orphan content; the
+    # subsequent purge cleans it) or is genuinely hung (the elected
+    # can't fix that — we choose merge correctness over indefinite wait).
+    def parallel_tests_wait_for_peer_done_markers!
+      base_dir = File.dirname(RSpecTracer.cache_path)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS
+
+      loop do
+        missing = parallel_tests_peer_dirs_missing_done(base_dir)
+        return if missing.empty?
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          RSpecTracer.logger.warn(
+            'RSpec tracer: peers booted without finishing within ' \
+            "#{PARALLEL_TESTS_PEER_DONE_DEADLINE_SECONDS}s: #{missing.inspect}; " \
+            'proceeding (peer dirs will be purged regardless of completion state)'
+          )
+          return
+        end
+
+        sleep 0.05
+      end
+    end
+
+    # Set difference of `.boot`-bearing peer dirs and `.done`-bearing
+    # peer dirs under `base_dir`. A returned entry means "this peer
+    # registered but has not signalled completion yet" — either still
+    # mid-flush or crashed.
+    def parallel_tests_peer_dirs_missing_done(base_dir)
+      boot_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_BOOT_MARKER_FILENAME)
+      done_dirs = parallel_tests_peer_dirs_with_marker(base_dir, PARALLEL_TESTS_DONE_MARKER_FILENAME)
+      boot_dirs - done_dirs
+    end
+
+    def parallel_tests_peer_dirs_with_marker(base_dir, marker_filename)
+      Dir.glob(File.join(base_dir, 'parallel_tests_*', marker_filename)).map do |path|
+        File.dirname(path)
+      end
+    end
+
     # Elects the worker that performs the per-run merge. Delegates to
     # `::ParallelTests.first_process?`, which returns true iff
     # `TEST_ENV_NUMBER.to_i <= 1` — i.e. for exactly one worker

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-tracer
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.4
 platform: ruby
 authors:
 - Abhimanyu Singh
@@ -111,9 +111,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/avmnu-sng/rspec-tracer
-  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.2.2
+  source_code_uri: https://github.com/avmnu-sng/rspec-tracer/tree/v1.2.4
   changelog_uri: https://github.com/avmnu-sng/rspec-tracer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/avmnu-sng/rspec-tracer/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib