Module: RSpecTracer::Example

Defined in:
lib/rspec_tracer/example.rb

Overview

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

  • metadata changes (‘skip:`, tags, `tracks: { … }`) - the spec-file digest still triggers the re-run and status history is kept

  • the example body or its hooks (‘before`, `let`) are edited - again, the file digest 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 - issue #210.)

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 + `explain` 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.

Helpers are ‘def self.x` + `private_class_method` so mutant attributes mutations through the singleton call path.

Class Method Summary collapse

Class Method Details

.from(example) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds the identity payload for one RSpec example. The MD5 is taken over the stability-contract subset (see ‘digest_identity` for the named-vs-unnamed split); `line_number` / `rerun_*` ride along in the returned Hash for the reporters but never enter the digest. See the module comment for the full stability contract.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/rspec_tracer/example.rb', line 76

def self.from(example)
  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 { |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