Module: RSpecTracer

Extended by:
Configuration
Defined in:
lib/rspec_tracer.rb,
lib/rspec_tracer/cli.rb,
lib/rspec_tracer/engine.rb,
lib/rspec_tracer/filter.rb,
lib/rspec_tracer/logger.rb,
lib/rspec_tracer/example.rb,
lib/rspec_tracer/version.rb,
lib/rspec_tracer/line_stub.rb,
lib/rspec_tracer/cli/doctor.rb,
lib/rspec_tracer/cli/explain.rb,
lib/rspec_tracer/source_file.rb,
lib/rspec_tracer/rails/preset.rb,
lib/rspec_tracer/remote_cache.rb,
lib/rspec_tracer/configuration.rb,
lib/rspec_tracer/rails/railtie.rb,
lib/rspec_tracer/tracker/input.rb,
lib/rspec_tracer/cli/cache_info.rb,
lib/rspec_tracer/reporters/base.rb,
lib/rspec_tracer/rspec/metadata.rb,
lib/rspec_tracer/storage/schema.rb,
lib/rspec_tracer/time_formatter.rb,
lib/rspec_tracer/tracker/filter.rb,
lib/rspec_tracer/cli/cache_clear.rb,
lib/rspec_tracer/cli/report_open.rb,
lib/rspec_tracer/storage/backend.rb,
lib/rspec_tracer/storage/snapshot.rb,
lib/rspec_tracer/tracker/io_hooks.rb,
lib/rspec_tracer/rspec/runner_hook.rb,
lib/rspec_tracer/reporters/registry.rb,
lib/rspec_tracer/rspec/installation.rb,
lib/rspec_tracer/rails/i18n_tracking.rb,
lib/rspec_tracer/rails/notifications.rb,
lib/rspec_tracer/rspec/reporter_hook.rb,
lib/rspec_tracer/tracker/env_matcher.rb,
lib/rspec_tracer/tracker/file_digest.rb,
lib/rspec_tracer/tracker/io_hooks/io.rb,
lib/rspec_tracer/remote_cache/archive.rb,
lib/rspec_tracer/remote_cache/backend.rb,
lib/rspec_tracer/rspec/parallel_tests.rb,
lib/rspec_tracer/storage/json_backend.rb,
lib/rspec_tracer/tracker/env_snapshot.rb,
lib/rspec_tracer/storage/lazy_snapshot.rb,
lib/rspec_tracer/tracker/io_hooks/file.rb,
lib/rspec_tracer/tracker/io_hooks/json.rb,
lib/rspec_tracer/tracker/io_hooks/yaml.rb,
lib/rspec_tracer/remote_cache/validator.rb,
lib/rspec_tracer/storage/sqlite_backend.rb,
lib/rspec_tracer/tracker/declared_globs.rb,
lib/rspec_tracer/remote_cache/s3_backend.rb,
lib/rspec_tracer/remote_cache/user_tasks.rb,
lib/rspec_tracer/reporters/html_reporter.rb,
lib/rspec_tracer/reporters/json_reporter.rb,
lib/rspec_tracer/storage/serializer/json.rb,
lib/rspec_tracer/tracker/io_hooks/kernel.rb,
lib/rspec_tracer/tracker/coverage_adapter.rb,
lib/rspec_tracer/tracker/dependency_graph.rb,
lib/rspec_tracer/tracker/example_registry.rb,
lib/rspec_tracer/remote_cache/git_ancestry.rb,
lib/rspec_tracer/reporters/payload_builder.rb,
lib/rspec_tracer/tracker/new_file_detector.rb,
lib/rspec_tracer/remote_cache/redis_backend.rb,
lib/rspec_tracer/storage/serializer/msgpack.rb,
lib/rspec_tracer/reporters/terminal_reporter.rb,
lib/rspec_tracer/tracker/loaded_files_tracker.rb,
lib/rspec_tracer/remote_cache/local_fs_backend.rb,
lib/rspec_tracer/reporters/coverage_json_reporter.rb,
lib/rspec_tracer/tracker/whole_suite_invalidators.rb

Overview

Top-level entry point. Drives the lifecycle:

RSpecTracer.start
  -> RSpec::Installation.install!  (prepend RunnerHook + ReporterHook)
  -> setup_coverage                (::Coverage.start unless SimpleCov owns it)
  -> setup_rails                   (detect ::Rails::VERSION)
  -> Engine.new.setup              (observers + cache load + filter decisions)

at_exit_behavior (installed via `at_exit` elsewhere in the boot
flow) runs the finalize stack: Engine#finalize writes the 13-file
snapshot via Storage::JsonBackend, Reporters::CoverageJsonReporter
writes coverage.json (single owner, replacing the 1.x
CoverageReporter + CoverageWriter pair retired in 2.0),
ParallelTests#finalize! merges per-worker caches on the last worker.

Defined Under Namespace

Modules: CLI, Configuration, Example, LineStub, RSpec, Rails, RemoteCache, Reporters, SourceFile, Storage, TimeFormatter, Tracker Classes: ArrayFilter, BlockFilter, Engine, Filter, Logger, RegexFilter, StringFilter

Constant Summary collapse

VERSION =

The currently installed gem version, in ‘MAJOR.MINOR.PATCH` form. Bumped per release; CI’s release workflow asserts the tag matches this constant before pushing to RubyGems.

'2.0.0.pre.1'

Constants included from Configuration

Configuration::ALLOWED_CONFIGURER, Configuration::DEFAULT_CACHE_DIR, Configuration::DEFAULT_CACHE_RETENTION_LOCAL_COUNT, Configuration::DEFAULT_CACHE_SIZE_WARN_PER_FILE_MB, Configuration::DEFAULT_CACHE_SIZE_WARN_TOTAL_MB, Configuration::DEFAULT_COVERAGE_DIR, Configuration::DEFAULT_LOCK_FILE, Configuration::DEFAULT_REPORT_DIR, Configuration::DEFAULT_STORAGE_BACKEND, Configuration::LOG_LEVEL, Configuration::STORAGE_BACKEND_NAMES, Configuration::STORAGE_BACKEND_OPT_KEYS, Configuration::STORAGE_BACKEND_SERIALIZERS

Class Attribute Summary collapse

Class Method Summary collapse

Methods included from Configuration

configure, method_missing, respond_to_missing?

Class Attribute Details

.duplicate_examples ⇒ 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.

Internal attribute.



57
58
59
 
# File 'lib/rspec_tracer.rb', line 57

def duplicate_examples
  @duplicate_examples
end

.no_examples ⇒ 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.

Internal attribute.



57
58
59
 
# File 'lib/rspec_tracer.rb', line 57

def no_examples
  @no_examples
end

.pid ⇒ 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.

Internal attribute.



57
58
59
 
# File 'lib/rspec_tracer.rb', line 57

def pid
  @pid
end

.running ⇒ 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.

Internal attribute.



57
58
59
 
# File 'lib/rspec_tracer.rb', line 57

def running
  @running
end

Class Method Details

.at_exit_behavior ⇒ 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.

Internal method on the tracer pipeline.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/rspec_tracer.rb', line 116

def at_exit_behavior
  return unless RSpecTracer.pid == Process.pid && RSpecTracer.running

  ::Kernel.exit(1) if duplicate_examples

  run_exit_tasks
ensure
  if RSpecTracer::RSpec::ParallelTests.active? &&
      RSpecTracer::RSpec::ParallelTests.last_process?
    RSpecTracer::RSpec::ParallelTests.remove_lock_file!
  end

  RSpecTracer.running = false
end

.engine ⇒ RSpecTracer::Engine?

The current Engine instance, or nil if start hasn’t been called yet.

Returns:



135
136
137
 
# File 'lib/rspec_tracer.rb', line 135

def engine
  @engine if defined?(@engine)
end

.parallel_tests? ⇒ Boolean

True if ‘parallel_tests` is in use (detected via `ParallelTests.active?` at start time). Affects cache + report directory scoping (per-worker dirs) and finalize-time merging.

Returns:

  • (Boolean) 


155
156
157
 
# File 'lib/rspec_tracer.rb', line 155

def parallel_tests?
  defined?(@parallel_tests) && @parallel_tests == true
end

.rails? ⇒ Boolean

True if Rails is loaded in this process (detected via ‘defined?(::Rails::VERSION)` at start time). Memoized; subsequent Rails activations within the same run are not re-detected. Drives the auto-installation of Rails-side observers (template + AR notification subscribers).

Returns:

  • (Boolean) 


166
167
168
 
# File 'lib/rspec_tracer.rb', line 166

def rails?
  defined?(@rails) && @rails == true
end

.simplecov? ⇒ Boolean

True if SimpleCov was loaded AND running at the time start was invoked. Determines whether rspec-tracer owns ‘::Coverage.start` itself (false) or defers to SimpleCov’s coverage lifecycle (true).

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/rspec_tracer.rb', line 145

def simplecov?
  defined?(@simplecov) && @simplecov == true
end

.start ⇒ void

This method returns an undefined value.

Boot the tracer. Idempotent — safe to call multiple times in a single process (subsequent calls return without re-installing hooks). Drives the lifecycle:

* Installs the RSpec runner / reporter prepend chain.
* Starts `::Coverage` unless SimpleCov already owns it.
* Detects Rails (memoized in `RSpecTracer.rails?`).
* Builds the {RSpecTracer::Engine} and installs observers.

Must be called BEFORE any application code loads so the boot set captured by ‘Coverage.peek_result` is empty. With SimpleCov, call `SimpleCov.start` first; rspec-tracer warns at boot when SimpleCov is loaded but not started.



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

def start
  return if defined?(@started) && @started

  RSpecTracer.running = false
  RSpecTracer.pid = Process.pid
  @run_started_at = ::Time.now.utc
  @run_monotonic_start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
  @started = true

  RSpecTracer.logger.debug "Started RSpec tracer (pid: #{RSpecTracer.pid})"

  warn_on_simplecov_load_order_mistake

  @parallel_tests = RSpecTracer::RSpec::ParallelTests.active?
  RSpecTracer::RSpec::ParallelTests.setup! if parallel_tests?
  initial_setup
end

.warn_on_simplecov_load_order_mistake ⇒ Object

SimpleCov load-order is part of the documented contract - SimpleCov.start MUST run before RSpecTracer.start when both are used together (see README §SimpleCov interop). When the user has SimpleCov loaded but not started, we’d silently call ::Coverage.start ourselves and SimpleCov’s later setup would bolt onto a Coverage already in flight, with the user’s add_filter calls applied after rspec-tracer started consuming data. Surface the load-order mistake at start time so the user gets a one-line warning instead of mysteriously-broken coverage output.



102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/rspec_tracer.rb', line 102

def warn_on_simplecov_load_order_mistake
  return unless defined?(::SimpleCov)
  return if ::SimpleCov.respond_to?(:running) && ::SimpleCov.running

  RSpecTracer.logger.warn(
    'SimpleCov is loaded but not started. ' \
    'Call SimpleCov.start before RSpecTracer.start so the ' \
    'tracer respects SimpleCov\'s filter chain. See README ' \
    'section "Working with SimpleCov".'
  )
end