Class: RSpecTracer::Reporters::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec_tracer/reporters/base.rb

Overview

Abstract base for every reporter rspec-tracer ships. Takes the finalized Storage::Snapshot + report_dir + run_metadata triplet (architectural decision (b), Option X - raw Snapshot, no projection struct) and exposes two lifecycle hooks:

- `generate` - subclass must implement; emits the reporter's
  output format (JSON file, terminal lines, HTML etc.)
- `no_op?` - true when the run had zero tracked examples; the
  Registry checks this before calling `generate` so empty runs
  don't litter the report_dir with empty artifacts.

‘initialize` accepts `**opts` so custom reporters can take constructor args via `config.add_reporter MyReporter, color: false`. The base class itself ignores opts; subclasses read what they need.

Errors during ‘generate` are NOT rescued here - the Registry wraps each reporter call in a per-reporter rescue + warn, so a buggy custom reporter never propagates a non-zero exit into the user’s test suite (graceful degradation, same contract as Storage backends per ARCHITECTURE.md).

Examples:

Registering a custom reporter

class MyReporter < RSpecTracer::Reporters::Base
  def generate
    File.write(File.join(report_dir, 'my.json'),
               JSON.pretty_generate(snapshot.to_h))
  end
end

RSpecTracer.configure do
  add_reporter MyReporter, my_option: true
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(snapshot:, report_dir:, run_metadata:, logger: nil, **options) ⇒ Base

Returns a new instance of Base.

Parameters:

  • snapshot (RSpecTracer::Storage::Snapshot) —

    the finalized per-run snapshot (‘nil` only on early-abort paths)

  • report_dir (String) —

    absolute path the reporter should write into (created by Engine.finalize before this fires)

  • run_metadata (Hash) —

    pid / run_time / started_at / cache_path / parallel_tests / rails flags

  • logger (#info, #warn, nil) (defaults to: nil) —

    tracer logger

  • options (Hash) —

    reporter-specific keyword args from ‘add_reporter MyReporter, **opts`



58
59
60
61
62
63
64
 
# File 'lib/rspec_tracer/reporters/base.rb', line 58

def initialize(snapshot:, report_dir:, run_metadata:, logger: nil, **options)
  @snapshot = snapshot
  @report_dir = report_dir
  @run_metadata = run_metadata || {}
  @logger = logger
  @options = options
end

Instance Attribute Details

#logger ⇒ RSpecTracer::Storage::Snapshot, ... (readonly)

Returns:

  • (RSpecTracer::Storage::Snapshot, nil) —

    finalized run snapshot.

  • (String) —

    absolute report directory.

  • (Hash) —

    run_metadata hash (pid / run_time / etc).

  • (#info, #warn, nil) —

    tracer logger.

  • (Hash) —

    reporter-specific options.



47
48
49
 
# File 'lib/rspec_tracer/reporters/base.rb', line 47

def logger
  @logger
end

#options ⇒ RSpecTracer::Storage::Snapshot, ... (readonly)

Returns:

  • (RSpecTracer::Storage::Snapshot, nil) —

    finalized run snapshot.

  • (String) —

    absolute report directory.

  • (Hash) —

    run_metadata hash (pid / run_time / etc).

  • (#info, #warn, nil) —

    tracer logger.

  • (Hash) —

    reporter-specific options.



47
48
49
 
# File 'lib/rspec_tracer/reporters/base.rb', line 47

def options
  @options
end

#report_dir ⇒ RSpecTracer::Storage::Snapshot, ... (readonly)

Returns:

  • (RSpecTracer::Storage::Snapshot, nil) —

    finalized run snapshot.

  • (String) —

    absolute report directory.

  • (Hash) —

    run_metadata hash (pid / run_time / etc).

  • (#info, #warn, nil) —

    tracer logger.

  • (Hash) —

    reporter-specific options.



47
48
49
 
# File 'lib/rspec_tracer/reporters/base.rb', line 47

def report_dir
  @report_dir
end

#run_metadata ⇒ RSpecTracer::Storage::Snapshot, ... (readonly)

Returns:

  • (RSpecTracer::Storage::Snapshot, nil) —

    finalized run snapshot.

  • (String) —

    absolute report directory.

  • (Hash) —

    run_metadata hash (pid / run_time / etc).

  • (#info, #warn, nil) —

    tracer logger.

  • (Hash) —

    reporter-specific options.



47
48
49
 
# File 'lib/rspec_tracer/reporters/base.rb', line 47

def run_metadata
  @run_metadata
end

#snapshot ⇒ RSpecTracer::Storage::Snapshot, ... (readonly)

Returns:

  • (RSpecTracer::Storage::Snapshot, nil) —

    finalized run snapshot.

  • (String) —

    absolute report directory.

  • (Hash) —

    run_metadata hash (pid / run_time / etc).

  • (#info, #warn, nil) —

    tracer logger.

  • (Hash) —

    reporter-specific options.



47
48
49
 
# File 'lib/rspec_tracer/reporters/base.rb', line 47

def snapshot
  @snapshot
end

Instance Method Details

#generate ⇒ void

This method returns an undefined value.

Subclass must implement. Called once per reporter per run by the Registry. Errors propagate to the Registry’s per-reporter rescue (graceful degradation: a buggy reporter never breaks the suite).

Raises:

  • (NotImplementedError) 


72
73
74
 
# File 'lib/rspec_tracer/reporters/base.rb', line 72

def generate
  raise NotImplementedError, "#{self.class}#generate must be implemented"
end

#no_op? ⇒ Boolean

Registry skips ‘generate` when this returns true so empty runs do not produce empty artifacts.

Returns:

  • (Boolean) 


80
81
82
83
84
 
# File 'lib/rspec_tracer/reporters/base.rb', line 80

def no_op?
  snapshot.nil? ||
    snapshot.all_examples.nil? ||
    snapshot.all_examples.empty?
end