ceedling 1.1.9 → 1.2.0

data/spec/support/integration/spec_integration_helper.rb

@@ -0,0 +1,285 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Shared rigging for the integration spec tier.
+#
+# Integration specs compose the real `lib/ceedling/preprocess/` object graph and run
+# the real GCC preprocessor, but exercise one subsystem -- includes extraction --
+# rather than a whole `ceedling` build. `gcc` is the only external dependency.
+#
+# The graph is real except for two thin stand-ins that keep the heavyweight framework
+# objects out: a Configurator stub that just returns the `DEFAULT_*_PREPROCESSOR_TOOL`
+# definitions and the mock prefix, and a ToolExecutor stub whose `exec` actually shells
+# the command it was handed through Open3. GCC genuinely runs; nothing else is faked.
+#
+# Written to plain `def ... end` throughout -- no endless method definitions, no
+# anonymous parameter forwarding -- so it loads on every Ruby in the CI matrix (3.0+).
+
+require 'open3'
+require 'tmpdir'
+require 'fileutils'
+
+require 'ceedling/constants'
+require 'ceedling/defaults'
+require 'ceedling/file_wrapper'
+require 'ceedling/yaml_wrapper'
+require 'ceedling/parsing_parcels'
+require 'ceedling/includes/includes'
+require 'ceedling/includes/include_factory'
+require 'ceedling/preprocess/preprocessinator'
+require 'ceedling/tool_executor'
+require 'ceedling/quote_include_isolator'
+require 'ceedling/preprocess/preprocessinator_includes_handler'
+require 'ceedling/preprocess/preprocessinator_bare_includes_extractor'
+require 'ceedling/preprocess/preprocessinator_line_marker_includes_extractor'
+
+module IntegrationSpecHelpers
+  # Absorbs any message (and any block) and returns itself. Stands in for the graph's
+  # logging/assembly collaborators that the includes path either never reaches or only
+  # calls for their side effects.
+  class NullObject
+    def method_missing(*_args, **_kwargs)
+      self
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+  end
+  NULL = NullObject.new
+
+  # The bare-includes tool with an option no preprocessor knows. GCC and Clang both stop
+  # on it before writing a make rule, as a broken tool definition or a killed process would.
+  FAILING_BARE_TOOL = DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL.merge(
+    arguments: ['--ceedling-unrecognized-option'] + DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL[:arguments]
+  ).freeze
+
+  # A Configurator with only what the includes path touches: the three preprocessor
+  # tool definitions and the CMock mock naming. Everything else would be a bug to reach.
+  # `bare_tool:` replaces the bare-includes tool, so an example can make that pass fail.
+  class StubConfigurator
+    def initialize(bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+      @bare_tool = bare_tool
+    end
+
+    def tools_test_bare_includes_preprocessor
+      @bare_tool
+    end
+
+    def tools_test_file_directives_only_preprocessor
+      DEFAULT_TEST_FILE_DIRECTIVES_ONLY_PREPROCESSOR_TOOL
+    end
+
+    def tools_test_file_full_preprocessor
+      DEFAULT_TEST_FILE_FULL_PREPROCESSOR_TOOL
+    end
+
+    def cmock_mock_prefix
+      'mock_'
+    end
+
+    def cmock_mock_path
+      'mocks'
+    end
+  end
+
+  # A ToolExecutor that assembles the command from the tool definition the same way the
+  # real one's `${n}` slot substitution does (an Array slot fans its argument out into
+  # one repeated flag per element), then runs it for real. Return shape matches what
+  # PreprocessinatorIncludesHandler and Preprocessinator read: `:output`, `:exit_code`,
+  # `:status`. Like SystemWrapper#shell_capture3, a command run with `:boom` false reports
+  # an exit code of 0 whatever happened, so failure handling meets the real contract.
+  class ShellingToolExecutor
+    def build_command_line(tool, extra_params, *args)
+      slots = {}
+      args.each_with_index { |value, i| slots[(i + 1).to_s] = value }
+
+      argv = [tool[:executable]] + Array(extra_params)
+      tool[:arguments].each do |arg|
+        slot = arg[/\$\{(\d+)\}/, 1]
+        if slot
+          Array(slots[slot]).each { |value| argv << arg.gsub("${#{slot}}", value.to_s) }
+        else
+          argv << arg
+        end
+      end
+
+      { line: argv.join(' '), options: { boom: true } }
+    end
+
+    def exec(command, _args = [])
+      stdout, stderr, status = Open3.capture3(command[:line])
+      exit_code = command[:options][:boom] ? status.exitstatus : 0
+      { output: stdout + stderr, exit_code: exit_code, status: status }
+    end
+
+    def failed?(shell_result)
+      ToolExecutor.allocate.failed?(shell_result)
+    end
+  end
+
+  # Minimal FilePathUtils: the includes path only asks it for a handful of scratch
+  # locations. Every returned directory is created on demand.
+  class ScratchFilePathUtils
+    def initialize(root)
+      @root = root
+    end
+
+    def form_test_preprocess_files_path(_test)
+      ensure_dir(File.join(@root, 'preprocess'))
+    end
+
+    def form_preprocessed_includes_list_filepath(filepath, test)
+      File.join(ensure_dir(File.join(@root, 'includes', test.to_s)), File.basename(filepath) + '.yml')
+    end
+
+    def form_preprocessed_file_raw_directives_only_filepath(filepath, test)
+      File.join(ensure_dir(File.join(@root, 'donly', 'raw', test.to_s)), File.basename(filepath))
+    end
+
+    def form_preprocessed_file_compacted_directives_only_filepath(filepath, test)
+      File.join(ensure_dir(File.join(@root, 'donly', test.to_s)), File.basename(filepath))
+    end
+
+    def form_preprocessed_file_fallback_expansion_filepath(filepath, test)
+      File.join(ensure_dir(File.join(@root, 'fallback_expansion', test.to_s)), File.basename(filepath))
+    end
+
+    private
+
+    def ensure_dir(dir)
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+  end
+
+  # Facade: `reconcile` lays out the same call sequence a real build's
+  # `stage_preprocess_*` does for one file -- optionally generate the directives-only
+  # output, then hand it to `Preprocessinator#preprocess_file_includes_common` -- and
+  # returns the reconciled, sanitized Include list. The spec renders those to Strings.
+  class IncludesExtractionHarness
+    def initialize(_work_dir, bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+      @root         = Dir.mktmpdir('ceedling-includes-harness-')
+      @cfg          = StubConfigurator.new( bare_tool: bare_tool )
+      @tool_exec    = ShellingToolExecutor.new
+      @fpu          = ScratchFilePathUtils.new(@root)
+      @file_wrapper = FileWrapper.new(loginator: NULL, verbosinator: NULL)
+      factory       = IncludeFactory.new(configurator: @cfg)
+      line_marker   = PreprocessinatorLineMarkerIncludesExtractor.new(
+        include_factory: factory, file_wrapper: @file_wrapper
+      )
+
+      @handler = PreprocessinatorIncludesHandler.new(
+        configurator:                                    @cfg,
+        preprocessinator_line_marker_includes_extractor: line_marker,
+        include_factory:                                 factory,
+        tool_executor:                                   @tool_exec,
+        file_wrapper:                                    @file_wrapper,
+        file_path_utils:                                 @fpu,
+        yaml_wrapper:                                    NULL,
+        parsing_parcels:                                 ParsingParcels.new,
+        quote_include_isolator:                          QuoteIncludeIsolator.new(file_wrapper: @file_wrapper, loginator: NULL),
+        loginator:                                       NULL,
+        reportinator:                                    NULL
+      )
+      @handler.setup
+
+      @preprocessinator = Preprocessinator.new(
+        preprocessinator_includes_handler: @handler,
+        preprocessinator_comment_stripper: NULL,
+        preprocessinator_file_assembler:   NULL,
+        preprocessinator_reconstructor:    NULL,
+        file_path_utils:                   @fpu,
+        file_wrapper:                      @file_wrapper,
+        tool_executor:                     @tool_exec,
+        plugin_manager:                    NULL,
+        configurator:                      @cfg,
+        loginator:                         NULL,
+        reportinator:                      NULL
+      )
+      @preprocessinator.setup
+    end
+
+    # `fallback: true` forces the text-scan path (skips directives-only generation).
+    def reconcile(file:, search_paths:, test: 'itest', defines: [], fallback: false)
+      donly = nil
+      unless fallback
+        donly = @preprocessinator.generate_directives_only_output(
+          filepath: file, test: test, flags: [],
+          include_paths: search_paths, vendor_paths: [], defines: defines
+        )
+      end
+
+      @preprocessinator.preprocess_file_includes_common(
+        test: test,
+        filepath: file,
+        directives_only_filepath: donly,
+        fallback: (fallback || donly.nil?),
+        flags: [],
+        include_paths: search_paths,
+        vendor_paths: [],
+        defines: defines
+      )
+    end
+  end
+
+  # --- Toolchain probes -----------------------------------------------------
+
+  # True when a `gcc` invocation of any kind succeeds. Mirrors the system tier's
+  # `tool_available?` rather than sharing it, so an integration spec need not load the
+  # whole system helper.
+  def gcc_available?
+    Open3.capture2e('gcc --version')[1].success?
+  rescue StandardError
+    false
+  end
+
+  # True when `gcc` honours `-fdirectives-only` without complaint. Older Apple Clang releases
+  # (the `gcc` alias on macOS) ignore the flag and warn, naming it -- exactly the
+  # condition under which Ceedling itself falls back to text scanning
+  # (Configurator#resolve_directives_only_preprocessing). Integration specs branch on
+  # this the same way.
+  def directives_only_supported?
+    out, status = Open3.capture2e('gcc -E -fdirectives-only -x c -', stdin_data: "\n")
+    status.success? && !out.match?(/warning[^\n]+-fdirectives-only/)
+  rescue StandardError
+    false
+  end
+
+  # --- Fixture trees ------------------------------------------------------
+
+  # Writes `files` (project-relative path => contents) into a fresh temp directory and
+  # yields its absolute path. Parent directories are created as needed. The tree is
+  # removed when the block returns.
+  def with_source_tree(files)
+    Dir.mktmpdir('ceedling-includes-integration-') do |dir|
+      files.each do |rel, contents|
+        path = File.join(dir, rel)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, contents)
+      end
+      yield dir
+    end
+  end
+
+  # Builds the real Preprocessinator graph wired to run GCC for real, and returns a
+  # small facade over it. See IncludesExtractionHarness#reconcile.
+  def build_includes_harness(work_dir, bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+    IncludesExtractionHarness.new(work_dir, bare_tool: bare_tool)
+  end
+end
+
+RSpec.configure do |config|
+  config.include IntegrationSpecHelpers
+end
+
+# `include_context "requires gcc"` skips a spec (or describe block) when no usable gcc
+# is on PATH -- the same shape the system tier uses for gdb/valgrind.
+RSpec.shared_context "requires gcc" do
+  before(:all) { @gcc_available = gcc_available? }
+  before { skip 'gcc is not installed or not in PATH' unless @gcc_available }
+end

data/spec/support/integration/test_includes_harness.rb

@@ -0,0 +1,259 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Rigging for a test file's #include extraction, stages 2 through 4, with GCC running
+# for real.
+#
+# The stage objects are real: TestContextExtractor's text scan (stage 2), TestSearchPaths
+# (stage 3), and TestIncludesExtractinator's three passes with their StandinHeaderinator, MockLocator,
+# FileFinder, and the Preprocessinator graph from spec_integration_helper.rb (stage 4).
+# Thin stand-ins replace only what would drag in a whole build: a configurator holding
+# one small project's settings, a dependency tracker that always reports stale, a
+# sequential batchinator, an include pathinator that orders a directory's headers, and
+# a file path utility rooted in the scratch tree.
+#
+# A harness works in the current directory, a project root holding `src/` and `test/`,
+# as a real build does.
+
+require 'spec_integration_helper'
+require 'ceedling/filename_extension'
+require 'ceedling/file_finder'
+require 'ceedling/file_finder_helper'
+require 'ceedling/test_context_extractor'
+require 'ceedling/test_invoker/test_invoker_types'
+require 'ceedling/test_invoker/test_search_paths'
+require 'ceedling/test_invoker/mock_locator'
+require 'ceedling/test_invoker/standin_headerinator'
+require 'ceedling/test_invoker/test_includes_extractinator'
+require 'ceedling/test_invoker/test_bare_includes_extractinator'
+require 'ceedling/test_invoker/test_includes_preprocessinator'
+require 'ceedling/test_invoker/test_includes_reconcilinator'
+
+module IntegrationSpecHelpers
+
+  # One small project: sources and headers under src/, tests under test/, mocks named
+  # with a `mock_` prefix
+  class TestIncludesConfigurator < StubConfigurator
+    attr_reader :test_build_preprocess_directives_only_available
+
+    def initialize(directives_only:, bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+      super( bare_tool: bare_tool )
+      @test_build_preprocess_directives_only_available = directives_only
+    end
+
+    def cmock_mock_path
+      'build/mocks'
+    end
+
+    def get_cmock_config
+      {}
+    end
+    def project_use_mocks
+      true
+    end
+    def project_use_partials
+      false
+    end
+    def project_use_test_preprocessor_tests
+      true
+    end
+    def test_build_preprocess_force_fallback
+      !@test_build_preprocess_directives_only_available
+    end
+    def project_build_root
+      'build'
+    end
+
+    def project_build_vendor_ceedling_path
+      'build/vendor'
+    end
+    def extension_header
+      FilenameExtension.new( '.h' )
+    end
+    def extension_source
+      FilenameExtension.new( '.c' )
+    end
+    def paths_test
+      ['test']
+    end
+    def paths_support
+      []
+    end
+    def paths_include
+      ['src']
+    end
+    def collection_paths_support
+      []
+    end
+    def collection_paths_include
+      Dir.glob( 'src/**/' ).map { |dir| dir.chomp( '/' ) }.sort
+    end
+    def collection_paths_libraries
+      []
+    end
+    def collection_paths_vendor
+      []
+    end
+    def collection_paths_test_toolchain_include
+      []
+    end
+    def collection_all_headers
+      Dir.glob( 'src/**/*.h' ).sort
+    end
+  end
+
+  # Scratch locations, plus where mocks and Partials sit, composed as FilePathUtils
+  # composes them
+  class TestIncludesFilePathUtils < ScratchFilePathUtils
+    def form_mock_header_filepath(subdir, filename)
+      File.join( 'build/mocks', subdir, filename.ext( '.h' ) )
+    end
+
+    def form_partial_header_filepath(subdir, filename)
+      File.join( 'build/partials', subdir, filename )
+    end
+
+    def form_mock_output_path(root, subdir)
+      subdir.nil? || subdir.empty? ? root : File.join( root, subdir )
+    end
+  end
+
+  # Headers in search order, as IncludePathinator#ordered_header_files gives them
+  class OrderedHeaders
+    def ordered_header_files(paths)
+      return paths.flat_map { |path| Dir.glob( File.join( path, '*.h' ) ).sort }.uniq
+    end
+
+    def lookup_test_directive_include_paths(_filepath)
+      []
+    end
+    def collect_test_include_paths
+      []
+    end
+  end
+
+  class StaleDependinator
+    def register(_target, **_options); end
+    def stale?(_target)
+      true
+    end
+    def mark_fresh(_target); end
+  end
+
+  class SequentialBatchinator
+    def exec(things:, **_options)
+      things.each { |key, value| yield key, value }
+    end
+  end
+
+  # Runs stages 2 through 4 for one test file and reports what the build would use
+  class TestIncludesHarness
+    attr_reader :context_extractor
+
+    def initialize(directives_only:, bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+      @cfg          = TestIncludesConfigurator.new( directives_only: directives_only, bare_tool: bare_tool )
+      @file_wrapper = FileWrapper.new( loginator: NULL, verbosinator: NULL )
+      @fpu          = TestIncludesFilePathUtils.new( 'build/scratch' )
+      @headers      = OrderedHeaders.new
+
+      @context_extractor = TestContextExtractor.new(
+        configurator: @cfg, parsing_parcels: ParsingParcels.new, include_factory: IncludeFactory.new( configurator: @cfg ),
+        partializer_config: NULL, file_path_utils: @fpu, file_wrapper: @file_wrapper, yaml_wrapper: NULL, loginator: NULL
+      )
+      @context_extractor.setup
+
+      @search_paths = TestSearchPaths.new( configurator: @cfg, include_pathinator: @headers, test_context_extractor: @context_extractor )
+      @locator      = MockLocator.new( configurator: @cfg, include_pathinator: @headers, file_finder: file_finder, file_path_utils: @fpu )
+      @extractinator = build_extractinator
+    end
+
+    # Stages 2 through 4 for `filepath`, preprocessing with `flags`. Returns the Testable
+    # the later stages would read.
+    def run(filepath, defines: [], flags: [])
+      testable = testable_for( filepath, defines, flags )
+      @context_extractor.collect_simple_context_from_file( filepath, nil, TestContextExtractor::Context::INCLUDES )
+
+      # Stage 2's tolerant mock search paths and stage 3's search paths
+      collection = @locator.header_collection( @search_paths.compose( filepath, testable.paths ) )
+      testable.mock_search_paths = @locator.directories(
+        @context_extractor.lookup_mock_header_includes_list( filepath ), mocks_root: testable.paths[:mocks], collection: collection, complain: :silent
+      )
+      testable.search_paths = @search_paths.compose( filepath, testable.paths, testable.mock_search_paths )
+
+      state = TestInvokerTypes::PipelineState.new( testables: { testable.name.to_sym => testable }, context: :test, options: [], lock: Mutex.new )
+      @extractinator.stage_collect_preprocessor_context( state )
+
+      return testable
+    end
+
+    # The #includes the rest of the build would use for `filepath`, as rendered strings
+    def includes(filepath)
+      @context_extractor.lookup_all_header_includes_list( filepath ).map( &:filename )
+    end
+
+    def mocks(filepath)
+      @context_extractor.lookup_mock_header_includes_list( filepath ).map( &:filename )
+    end
+
+    private
+
+    def file_finder
+      finder = FileFinder.new(
+        configurator: @cfg, file_finder_helper: FileFinderHelper.new( loginator: NULL ),
+        file_path_utils: @fpu, file_wrapper: @file_wrapper, yaml_wrapper: NULL
+      )
+      return finder
+    end
+
+    def build_extractinator
+      handler = PreprocessinatorIncludesHandler.new(
+        configurator: @cfg, include_factory: IncludeFactory.new( configurator: @cfg ),
+        preprocessinator_line_marker_includes_extractor: PreprocessinatorLineMarkerIncludesExtractor.new(
+          include_factory: IncludeFactory.new( configurator: @cfg ), file_wrapper: @file_wrapper
+        ),
+        tool_executor: ShellingToolExecutor.new, file_wrapper: @file_wrapper, file_path_utils: @fpu, yaml_wrapper: YamlWrapper.new( file_wrapper: @file_wrapper ),
+        parsing_parcels: ParsingParcels.new, quote_include_isolator: QuoteIncludeIsolator.new( file_wrapper: @file_wrapper, loginator: NULL ),
+        loginator: NULL, reportinator: NULL
+      )
+      handler.setup
+
+      preprocessinator = Preprocessinator.new(
+        preprocessinator_includes_handler: handler, preprocessinator_comment_stripper: NULL, preprocessinator_file_assembler: NULL,
+        preprocessinator_reconstructor: NULL, file_path_utils: @fpu, file_wrapper: @file_wrapper, tool_executor: ShellingToolExecutor.new,
+        plugin_manager: NULL, configurator: @cfg, loginator: NULL, reportinator: NULL
+      )
+      preprocessinator.setup
+
+      standins = StandinHeaderinator.new(
+        configurator: @cfg, loginator: NULL, reportinator: NULL, file_wrapper: @file_wrapper, file_path_utils: @fpu, mock_locator: @locator
+      )
+
+      common = { configurator: @cfg, loginator: NULL, reportinator: NULL, batchinator: SequentialBatchinator.new, preprocessinator: preprocessinator }
+      return TestIncludesExtractinator.new(
+        test_bare_includes_extractinator: TestBareIncludesExtractinator.new(
+          **common, file_path_utils: @fpu, dependinator: StaleDependinator.new, test_search_paths: @search_paths, standin_headerinator: standins
+        ),
+        test_includes_preprocessinator: TestIncludesPreprocessinator.new(
+          **common, file_path_utils: @fpu, file_wrapper: @file_wrapper, dependinator: StaleDependinator.new
+        ),
+        test_includes_reconcilinator: TestIncludesReconcilinator.new(
+          **common, test_context_extractor: @context_extractor, test_search_paths: @search_paths, mock_locator: @locator
+        )
+      )
+    end
+
+    def testable_for(filepath, defines, flags)
+      name = File.basename( filepath, '.c' )
+      return TestInvokerTypes::Testable.new(
+        name: name, filepath: filepath, paths: { mocks: File.join( 'build/mocks', name ) },
+        preprocess: { includes: [], directives_only: { filepath: nil }, fallback_expansion: { filepath: nil } },
+        preprocess_flags: flags, preprocess_defines: defines, search_paths: [], mock_search_paths: []
+      )
+    end
+  end
+
+end

data/spec/support/integration/tool_executor_integration_helper.rb

@@ -0,0 +1,55 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Shared rigging for ToolExecutor's integration spec tier.
+#
+# Wires the real ToolExecutor + ToolExecutorHelper + SystemWrapper + SystemUtils +
+# Loginator + Verbosinator + RubyExpandinator graph -- no stand-in for ToolExecutor
+# itself, unlike IntegrationSpecHelpers::ShellingToolExecutor (spec_integration_helper.rb),
+# which exists precisely because ToolExecutor was untested at that tier. This graph
+# genuinely shells out through SystemWrapper#shell_capture3 (Open3.capture3) for real.
+
+require 'rbconfig'
+
+require 'ceedling/tool_executor'
+require 'ceedling/tool_executor_helper'
+require 'ceedling/system_wrapper'
+require 'ceedling/system_utils'
+require 'ceedling/loginator'
+require 'ceedling/verbosinator'
+require 'ceedling/ruby_expandinator'
+
+module ToolExecutorIntegrationHelpers
+  # Builds the real collaborator graph. Verbosity stays at the default (NORMAL) so
+  # nothing here needs OBNOXIOUS-level logging silenced or asserted on.
+  def real_tool_executor
+    system_wrapper = SystemWrapper.new
+    verbosinator    = Verbosinator.new
+    loginator       = Loginator.new(verbosinator: verbosinator, system_wrapper: system_wrapper)
+    system_utils    = SystemUtils.new(system_wrapper: system_wrapper)
+    helper = ToolExecutorHelper.new(
+      loginator: loginator, system_utils: system_utils,
+      system_wrapper: system_wrapper, verbosinator: verbosinator
+    )
+    ToolExecutor.new(
+      tool_executor_helper: helper, loginator: loginator,
+      verbosinator: verbosinator, system_wrapper: system_wrapper,
+      ruby_expandinator: RubyExpandinator.new
+    )
+  end
+
+  # A tool definition whose executable is the same Ruby running this test suite --
+  # genuinely cross-platform-safe (available on every CI platform) unlike assuming
+  # gcc/POSIX shell builtins behave identically on Linux/Windows/macOS.
+  def ruby_tool_config(name: 'ruby_probe', arguments: [])
+    { name: name, executable: RbConfig.ruby, arguments: arguments }
+  end
+end
+
+RSpec.configure do |config|
+  config.include ToolExecutorIntegrationHelpers
+end

data/spec/support/spec_helper.rb

@@ -5,11 +5,52 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+# Coverage instrumentation must start before any Ceedling code below is required, or
+# Ruby's Coverage module never sees those files' lines at all. Active only when
+# CEEDLING_TEST_COVERAGE names this process's own suite exactly -- 'units' or
+# 'integration'. This file is ALSO required by the system-test suite's own outer rspec
+# process (spec_system_helper.rb requires it too), which barely touches lib/ceedling
+# directly itself (the real work happens in each system-test child subprocess,
+# instrumented separately by simplecov_boot.rb); a bare truthy check here would make
+# that process ALSO claim a resultset entry and silently overwrite real coverage with
+# its own near-empty coverage, since SimpleCov's multi-process merging replaces rather
+# than accumulates same-named entries. Picks up the shared .simplecov config (repo
+# root) via SimpleCov's own upward-directory-search autoload. The HTML reports are
+# generated once, explicitly, by `rake coverage:report` after every suite finishes,
+# rather than by this process's own exit.
+coverage_suite = ENV['CEEDLING_TEST_COVERAGE']
+if coverage_suite == 'units' || coverage_suite == 'integration'
+  require 'simplecov'
+  # .simplecov (already loaded by the require above, via SimpleCov's own
+  # autoload) is configuration only -- this explicit call is what actually
+  # begins tracking for this process.
+  SimpleCov.start
+  SimpleCov.command_name coverage_suite
+
+  # Units writes the canonical coverage/.resultset.json. Integration, like the
+  # system suite's per-process boots, writes its own raw resultset instead, so
+  # `rake coverage:report` can format a standalone integration report and still
+  # fold the same data into the combined one -- and so a units run and an
+  # integration run in the same coverage/ never merge into one file that both
+  # the "units" and "integration" reports would then wrongly draw from.
+  SimpleCov.coverage_dir(File.join('coverage', 'raw', 'integration')) if coverage_suite == 'integration'
+
+  SimpleCov.at_exit { SimpleCov.result }
+end
+
 require 'require_all'
 require 'constructor'
 
 RSpec.configure do |config|
   config.raise_errors_for_deprecations!
+
+  # This suite leans heavily on `double(...)` plus `allow`/`expect(...).to receive`, so
+  # without verification a spec can stub a method the real collaborator does not have.
+  # The spec then passes while describing an interface that does not exist, and keeps
+  # passing after a rename removes the real method.
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
 end
 
 here = File.dirname(__FILE__)