ceedling 1.1.9 → 1.2.0

data/spec/integration/test_executable_manifest_spec.rb

@@ -0,0 +1,118 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# The manifest Windows reads beside a test executable, written to disk by a real FileWrapper.
+# Windows is stubbed so the file's on-disk shape is checked on every host. Whether Windows
+# honors it is checked only on a Windows host where Installer Detection is active.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'open3'
+require 'tmpdir'
+require 'ceedling/constants'
+require 'ceedling/file_wrapper'
+require 'ceedling/generators/generator'
+require 'ceedling/system_wrapper'
+require 'fileutils'
+
+describe 'Test executable manifest (integration)' do
+  let(:loginator)      { double( 'loginator' ).as_null_object }
+  let(:verbosinator)   { double( 'verbosinator' ).as_null_object }
+  let(:system_wrapper) { double( 'system_wrapper', windows?: true ) }
+
+  let(:generator) do
+    others = [
+      :configurator, :generator_helper, :generator_mocks, :generator_test_results,
+      :generator_test_results_backtrace, :generator_partials, :test_context_extractor,
+      :tool_executor, :file_finder, :file_path_utils, :reportinator, :plugin_manager,
+      :test_runner_manager
+    ].to_h { |name| [name, double( name.to_s ).as_null_object] }
+
+    Generator.new(
+      others.merge(
+        loginator:      loginator,
+        system_wrapper: system_wrapper,
+        file_wrapper:   FileWrapper.new( { loginator: loginator, verbosinator: verbosinator } )
+      )
+    )
+  end
+
+  it 'writes the manifest beside the test executable' do
+    Dir.mktmpdir do |dir|
+      executable = File.join( dir, 'test_setup_parser.exe' )
+      generator.generate_test_executable_manifest( executable: executable, test_filepath: 'test/test_setup_parser.c' )
+
+      manifest = File.join( dir, 'test_setup_parser.exe.manifest' )
+      expect( File.exist?( manifest ) ).to be(true)
+      expect( File.read( manifest ) ).to eq( TEST_EXECUTABLE_MANIFEST )
+    end
+  end
+
+  it 'leaves an unchanged manifest untouched across builds' do
+    Dir.mktmpdir do |dir|
+      executable = File.join( dir, 'test_a.exe' )
+      manifest   = "#{executable}.manifest"
+
+      generator.generate_test_executable_manifest( executable: executable, test_filepath: 'test/test_a.c' )
+      File.utime( Time.at( 0 ), Time.at( 0 ), manifest )
+      generator.generate_test_executable_manifest( executable: executable, test_filepath: 'test/test_a.c' )
+
+      expect( File.mtime( manifest ) ).to eq( Time.at( 0 ) )
+    end
+  end
+
+  # Installer Detection itself, on a Windows host where it is active. MinGW-w64 GCC links a
+  # default manifest that already requests the invoker's rights, and Windows ignores a
+  # manifest file beside an executable embedding one, so the default is displaced first.
+  context 'on Windows, an executable named like an installer' do
+    include_context 'requires gcc'
+    before { skip 'Installer Detection is a Windows behavior' unless SystemWrapper.windows? }
+
+    # Displaces GCC's default manifest object, which it links only when found on its search path
+    def build(dir, name)
+      File.write( File.join( dir, 'empty.c' ), "int ceedling_no_default_manifest;\n" )
+      File.write( File.join( dir, 'main.c' ), "int main(void) { return 0; }\n" )
+      run( "gcc -c #{File.join( dir, 'empty.c' )} -o #{File.join( dir, 'default-manifest.o' )}" )
+
+      executable = File.join( dir, "#{name}.exe" )
+      run( "gcc -B#{dir}/ #{File.join( dir, 'main.c' )} -o #{executable}" )
+      return executable
+    end
+
+    def run(command)
+      output, status = Open3.capture2e( command )
+      raise "#{command}\n#{output}" unless status.success?
+    end
+
+    def embeds_manifest?(executable)
+      return File.binread( executable ).include?( 'requestedExecutionLevel' )
+    end
+
+    # Windows refuses to start it (ERROR_ELEVATION_REQUIRED, 740), which Ruby raises
+    def starts?(executable)
+      _output, status = Open3.capture2e( executable )
+      return status.success?
+    rescue SystemCallError
+      return false
+    end
+
+    it 'runs only with the manifest beside it' do
+      Dir.mktmpdir do |dir|
+        # Windows caches its decision per executable, so each check runs its own copy
+        bare = build( dir, 'test_update_bare' )
+        skip 'this toolchain embeds a manifest despite the displaced default' if embeds_manifest?( bare )
+        skip 'Installer Detection is not active on this host' if starts?( bare )
+
+        manifested = File.join( dir, 'test_update_manifested.exe' )
+        FileUtils.cp( bare, manifested )
+        generator.generate_test_executable_manifest( executable: manifested, test_filepath: 'test/test_update.c' )
+
+        expect( starts?( manifested ) ).to be(true)
+      end
+    end
+  end
+end

data/spec/integration/test_includes_extractinator_spec.rb

@@ -0,0 +1,293 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# A test file's #include extraction, stages 2 through 4, with GCC running for real.
+#
+# Each example lays a small project on disk, runs the real text scan, search path
+# composition, and stage 4 against it, and checks which #includes and mocks the rest
+# of the build would use. What a test can include depends on GCC's own evaluation of
+# its #if branches and on what the second pass can find on the search path, which no
+# unit spec can show.
+#
+# Every scenario runs twice: with directives-only output, and in whole-run fallback,
+# where a plain expansion stands in for it. Fallback is forced, so it runs on every
+# toolchain; the directives-only runs skip on a toolchain without that support. The
+# expectations match, which is the best fallback can offer, not a promise it keeps for
+# every project.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'test_includes_harness'
+
+describe 'Test file #include extraction (integration)' do
+  include_context 'requires gcc'
+
+  before(:all) { @directives_only = directives_only_supported? }
+
+  # Runs stages 2 through 4 for test/<test> in a project laid out from `tree`, and yields
+  # the harness and the Testable. `directives_only: false` forces whole-run fallback.
+  def extract(tree, test, directives_only:, defines: [], flags: [], bare_tool: DEFAULT_TEST_BARE_INCLUDES_PREPROCESSOR_TOOL)
+    with_source_tree( tree ) do |dir|
+      Dir.chdir( dir ) do
+        harness  = IntegrationSpecHelpers::TestIncludesHarness.new( directives_only: directives_only, bare_tool: bare_tool )
+        testable = harness.run( "test/#{test}", defines: defines, flags: flags )
+        yield harness, testable
+      end
+    end
+  end
+
+  # Issue #1083, Case 1: only the branch that is on can build, and the other branches'
+  # headers don't exist
+  CASE_1_TREE = {
+    'src/Gpt.h'          => "void Gpt_StartTimer(void);\n",
+    'test/test_Case_01.c' => <<~C
+      #if defined(UNITTEST_HW_DEPENDANT_MOCK_NEEDED)
+        #if (TARGET_BOARD_HARDWARE == HW_TYPE_1)
+          #include "mock_Gpt_HwType1.h"
+        #else
+          #include "mock_Gpt_HwType2.h"
+        #endif
+      #else
+        #include "mock_Gpt.h"
+      #endif
+    C
+  }.freeze
+
+  # A branch can name its mock in letter case its header doesn't have
+  CASE_SLIP_TREE = {
+    'src/Gpt.h'                  => "void Gpt_StartTimer(void);\n",
+    'test/test_Case_01_legacy.c' => "#ifdef LEGACY_NAMES\n#include \"mock_gpt.h\"\n#else\n#include \"mock_Gpt.h\"\n#endif\n"
+  }.freeze
+
+  # Issue #1083, Case 2: the test picks its second mock with a macro its first mock's
+  # header defines
+  CASE_2_TREE = {
+    'src/MyModuleConfig.h' => <<~C,
+      #ifndef MY_MODULE_CONFIG_H
+      #define MY_MODULE_CONFIG_H
+      #define MODULE_1_ENABLED
+      int Module0_FunctionToCall(void);
+      #ifdef MODULE_1_ENABLED
+      #include "MyModulePart1.h"
+      #endif
+      #endif
+    C
+    'src/MyModulePart1.h' => "int Module1_FunctionToCall(void);\n",
+    'src/MyModulePart2.h' => "int Module2_FunctionToCall(void);\n",
+    'test/test_Case_02.c' => <<~C
+      #include "mock_MyModuleConfig.h"
+      #ifdef MODULE_1_ENABLED
+      #include "mock_MyModulePart1.h"
+      #endif
+      #ifdef MODULE_2_ENABLED
+      #include "mock_MyModulePart2.h"
+      #endif
+    C
+  }.freeze
+
+  { 'with directives-only output' => true, 'in fallback' => false }.each do |mode, directives_only|
+    context mode do
+      before(:each) do
+        skip 'gcc ignores -fdirectives-only on this toolchain' if directives_only && !@directives_only
+      end
+
+      let(:directives_only) { directives_only }
+
+      # Runs stages 2 through 4 in this context's mode
+      def extract_in_mode(tree, test, **options, &block)
+        extract( tree, test, directives_only: directives_only, **options, &block )
+      end
+
+      it 'mocks only the branch that is on, when the other branches have no headers' do
+        extract_in_mode( CASE_1_TREE, 'test_Case_01.c' ) do |harness, _testable|
+          expect(harness.mocks( 'test/test_Case_01.c' )).to eq( ['mock_Gpt.h'] )
+        end
+      end
+
+      # The real module must link, not a mock a branch that is off names
+      it 'keeps a real header and drops its mock in a branch that is off' do
+        tree = {
+          'src/Gpt.h'         => "void Gpt_StartTimer(void);\n",
+          'test/test_Mixed.c' => "#include \"Gpt.h\"\n#ifdef USE_GPT_MOCK\n#include \"mock_Gpt.h\"\n#endif\n"
+        }
+
+        extract_in_mode( tree, 'test_Mixed.c' ) do |harness, _testable|
+          expect(harness.includes( 'test/test_Mixed.c' )).to eq( ['Gpt.h'] )
+          expect(harness.mocks( 'test/test_Mixed.c' )).to eq( [] )
+        end
+      end
+
+      it 'says nothing of a mis-cased mock in a branch that is off' do
+        extract_in_mode( CASE_SLIP_TREE, 'test_Case_01_legacy.c' ) do |harness, _testable|
+          expect(harness.mocks( 'test/test_Case_01_legacy.c' )).to eq( ['mock_Gpt.h'] )
+        end
+      end
+
+      it 'stops on a mis-cased mock in a branch that is on, naming the header it found' do
+        expect { extract_in_mode( CASE_SLIP_TREE, 'test_Case_01_legacy.c', defines: ['LEGACY_NAMES'] ) { nil } }
+          .to raise_error( CeedlingException, /different capitalization was found: 'src\/Gpt\.h'/ )
+      end
+
+      it 'gives a mock that a macro names, with its header in a subdirectory, a search path' do
+        tree = {
+          'src/drivers/widget.h' => "int widget_read(void);\n",
+          'test/test_reader.c'   => "#define WIDGET_MOCK \"mock_widget.h\"\n#include WIDGET_MOCK\n"
+        }
+
+        extract_in_mode( tree, 'test_reader.c' ) do |harness, testable|
+          expect(harness.mocks( 'test/test_reader.c' )).to eq( ['mock_widget.h'] )
+          expect(testable.mock_search_paths).to eq( ['build/mocks/test_reader/drivers'] )
+        end
+      end
+
+      describe 'a mock chosen by a macro from a header' do
+        it 'is kept when the macro arrives through another mock' do
+          extract_in_mode( CASE_2_TREE, 'test_Case_02.c' ) do |harness, _testable|
+            expect(harness.mocks( 'test/test_Case_02.c' )).to eq( ['mock_MyModuleConfig.h', 'mock_MyModulePart1.h'] )
+          end
+        end
+
+        it 'is kept when the test includes the real header itself' do
+          tree = CASE_2_TREE.merge( 'test/test_Case_02.c' => "#include \"MyModuleConfig.h\"\n" + CASE_2_TREE['test/test_Case_02.c'] )
+
+          extract_in_mode( tree, 'test_Case_02.c' ) do |harness, _testable|
+            expect(harness.mocks( 'test/test_Case_02.c' )).to eq( ['mock_MyModuleConfig.h', 'mock_MyModulePart1.h'] )
+          end
+        end
+
+        # Issue #1083's Case 1 and Case 2 together: a branch that is off names a mock whose
+        # header doesn't exist
+        it 'is kept while a mock in a branch that is off, without a header, is dropped' do
+          tree = CASE_2_TREE.reject { |path, _| path == 'src/MyModulePart2.h' }
+
+          extract_in_mode( tree, 'test_Case_02.c' ) do |harness, _testable|
+            expect(harness.mocks( 'test/test_Case_02.c' )).to eq( ['mock_MyModuleConfig.h', 'mock_MyModulePart1.h'] )
+          end
+        end
+      end
+
+      # A computed #include of a mock can't be resolved this way: no stand-in exists for it
+      # before the second pass, so that pass fails on it
+      it 'keeps a real header that a macro from another header names' do
+        tree = {
+          'src/config.h'     => "#define BOARD_HEADER \"board.h\"\n",
+          'src/board.h'      => "int board_id(void);\n",
+          'test/test_board.c' => "#include \"config.h\"\n#include BOARD_HEADER\n"
+        }
+
+        extract_in_mode( tree, 'test_board.c' ) do |harness, _testable|
+          expect(harness.includes( 'test/test_board.c' )).to eq( ['config.h', 'board.h'] )
+        end
+      end
+
+      # The candidates include scanned mocks the preprocessor then discards; their
+      # directories serve the second pass and are dropped once it has decided
+      it 'narrows mock search paths to the mocks the build uses' do
+        tree = CASE_1_TREE.merge( 'src/hw/Gpt_HwType1.h' => "void Gpt_StartTimer(void);\n" )
+
+        extract_in_mode( tree, 'test_Case_01.c' ) do |_harness, testable|
+          expect(testable.mock_search_paths).to eq( ['build/mocks/test_Case_01'] )
+          expect(testable.search_paths).to_not include( 'build/mocks/test_Case_01/hw' )
+        end
+      end
+
+      describe 'a mock\'s stand-in' do
+        let(:standin) { 'build/mocks/test_Case_01/mock_Gpt.h' }
+
+        def place_before_run(contents)
+          tree = CASE_1_TREE.merge( standin => contents )
+          extract_in_mode( tree, 'test_Case_01.c' ) { |_harness, _testable| yield File.read( standin ) }
+        end
+
+        it 'includes its real header, as the generated mock will' do
+          extract_in_mode( CASE_1_TREE, 'test_Case_01.c' ) do |_harness, _testable|
+            expect(File.read( standin )).to eq( "#{StandinHeaderinator::MARKER}\n#include \"Gpt.h\"\n" )
+          end
+        end
+
+        it 'replaces a blank stand-in an earlier version left' do
+          place_before_run( "// Ceedling intentionally blank file\n\n" ) do |contents|
+            expect(contents).to include( '#include "Gpt.h"' )
+          end
+        end
+
+        it 'leaves a real mock alone' do
+          place_before_run( "/* AUTOGENERATED FILE. DO NOT EDIT. */\n" ) do |contents|
+            expect(contents).to eq( "/* AUTOGENERATED FILE. DO NOT EDIT. */\n" )
+          end
+        end
+      end
+
+      # The candidates hold the text scan, so the second pass alone still decides
+      it 'reconciles as usual when only the first pass fails' do
+        extract_in_mode( CASE_1_TREE, 'test_Case_01.c', bare_tool: IntegrationSpecHelpers::FAILING_BARE_TOOL ) do |harness, _testable|
+          expect(harness.mocks( 'test/test_Case_01.c' )).to eq( ['mock_Gpt.h'] )
+        end
+      end
+
+      # Nothing then checks the text scan, so it stands as the test's list, as a best effort
+      it 'keeps the text-scan #includes when both passes fail' do
+        tree = {
+          'src/Gpt.h'           => "void Gpt_StartTimer(void);\n",
+          'src/stop.h'          => "#error stops the second pass\n",
+          'test/test_Case_01.c' => "#include \"stop.h\"\n#include \"mock_Gpt.h\"\n"
+        }
+
+        extract_in_mode( tree, 'test_Case_01.c', bare_tool: IntegrationSpecHelpers::FAILING_BARE_TOOL ) do |harness, _testable|
+          expect(harness.includes( 'test/test_Case_01.c' )).to eq( ['stop.h', 'mock_Gpt.h'] )
+          expect(harness.mocks( 'test/test_Case_01.c' )).to eq( ['mock_Gpt.h'] )
+        end
+      end
+
+      # -P drops the line markers the second pass is read through, so reconciliation finds
+      # nothing. Validation rejects it; this shows the last line of defense.
+      it 'keeps the text-scan #includes when the second pass\'s output has no line markers' do
+        tree = {
+          'src/Gpt.h'         => "void Gpt_StartTimer(void);\n",
+          'test/test_Mixed.c' => "#include \"Gpt.h\"\n#include \"mock_Gpt.h\"\n"
+        }
+
+        extract_in_mode( tree, 'test_Mixed.c', flags: ['-P'] ) do |harness, _testable|
+          expect(harness.includes( 'test/test_Mixed.c' )).to eq( ['Gpt.h', 'mock_Gpt.h'] )
+        end
+      end
+
+      it 'writes no #include list cache when the first pass fails' do
+        extract_in_mode( CASE_1_TREE, 'test_Case_01.c', bare_tool: IntegrationSpecHelpers::FAILING_BARE_TOOL ) do |_harness, _testable|
+          expect(Dir.glob( 'build/scratch/includes/**/*.yml' )).to eq( [] )
+        end
+      end
+
+      # When the second pass fails for a file, its scanned #includes are checked against
+      # GCC's bare list, which still evaluated the #if branches
+      it 'still drops mocks in branches that are off when the second pass fails' do
+        tree = CASE_1_TREE.merge(
+          'src/stop.h'          => "#error stops the second pass\n",
+          'test/test_Case_01.c' => "#include \"stop.h\"\n" + CASE_1_TREE['test/test_Case_01.c']
+        )
+
+        extract_in_mode( tree, 'test_Case_01.c' ) do |harness, testable|
+          expect(testable.preprocess[:directives_only][:filepath]).to be_nil
+          expect(testable.preprocess[:fallback_expansion][:filepath]).to be_nil
+          expect(harness.mocks( 'test/test_Case_01.c' )).to eq( ['mock_Gpt.h'] )
+        end
+      end
+    end
+  end
+
+  # The line-marker reader finds the test file's own lines by the output's basename, and
+  # stage 11 reads only the directives-only key
+  it 'keeps the fallback expansion under the test file\'s name, apart from directives-only output' do
+    extract( CASE_1_TREE, 'test_Case_01.c', directives_only: false ) do |_harness, testable|
+      expansion = testable.preprocess[:fallback_expansion][:filepath]
+
+      expect(File.basename( expansion )).to eq( 'test_Case_01.c' )
+      expect(File.exist?( expansion )).to be true
+      expect(testable.preprocess[:directives_only][:filepath]).to be_nil
+    end
+  end
+end

data/spec/integration/tool_executor_spec.rb

@@ -0,0 +1,224 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Unlike spec/units/tool_executor_spec.rb, this spec wires the REAL ToolExecutor +
+# ToolExecutorHelper + SystemWrapper + SystemUtils + Loginator + Verbosinator +
+# RubyExpandinator graph (see tool_executor_integration_helper.rb) and genuinely shells
+# out through SystemWrapper#shell_capture3 (Open3.capture3). The one external dependency
+# is `ruby` itself -- the same interpreter running this test suite -- rather than gcc or
+# any POSIX shell builtin, so every scenario here is available on every CI platform
+# (Linux/Windows/macOS) without a toolchain probe.
+#
+# Real scripts are written to real files via with_source_tree and invoked by their real
+# path, rather than passed inline via `-e`, specifically to avoid needing to reason about
+# cross-platform (sh vs. cmd.exe) command-line quoting for script CONTENT -- only a bare
+# file path need ever survive shell parsing, and script file content is real Ruby source
+# written straight to disk, immune to any shell-quoting concern entirely.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+require 'tool_executor_integration_helper'
+require 'ceedling/constants'
+require 'ceedling/system_wrapper'
+require 'ceedling/system_utils'
+
+describe 'ToolExecutor (integration)' do
+  let(:executor) { real_tool_executor }
+
+  it 'builds and executes a real command end-to-end, returning real stdout' do
+    with_source_tree({ 'probe.rb' => 'puts "hello-from-ceedling"' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'probe.rb')])
+
+      command = executor.build_command_line(tool, [])
+      result = executor.exec(command)
+
+      expect(result[:stdout]).to include('hello-from-ceedling')
+      expect(result[:exit_code]).to eq(0)
+    end
+  end
+
+  it 'substitutes a real ${1} positional arg into a real shelled-out command' do
+    with_source_tree({ 'echo_arg.rb' => 'puts ARGV[0]' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'echo_arg.rb'), '${1}'])
+
+      command = executor.build_command_line(tool, [], 'ceedling-arg-value')
+      result = executor.exec(command)
+
+      expect(result[:stdout]).to include('ceedling-arg-value')
+    end
+  end
+
+  it 'raises ShellException with the real exit code when the real process exits non-zero and boom is true' do
+    with_source_tree({ 'fail.rb' => 'exit 3' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'fail.rb')])
+      command = executor.build_command_line(tool, [])
+
+      expect { executor.exec(command) }.to raise_error(ShellException) { |e|
+        expect(e.shell_result[:exit_code]).to eq(3)
+      }
+    end
+  end
+
+  it 'does not raise when boom is false, even though the real process exits non-zero' do
+    with_source_tree({ 'fail.rb' => 'exit 3' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'fail.rb')])
+      command = executor.build_command_line(tool, [])
+      command[:options] = { :boom => false }
+
+      result = executor.exec(command)
+
+      # Pins SystemWrapper's own real contract: :exit_code only ever reflects the real
+      # process's actual exit status when boom:true was passed through to it -- with
+      # boom:false it stays 0 regardless of what really happened. A caller handling its
+      # own failure asks #failed? instead, which the next example pins.
+      expect(result[:exit_code]).to eq(0)
+    end
+  end
+
+  it 'reports a real non-zero exit as failed when boom is false' do
+    with_source_tree({ 'fail.rb' => 'exit 3', 'pass.rb' => 'exit 0' }) do |dir|
+      results = ['fail.rb', 'pass.rb'].map do |script|
+        command = executor.build_command_line(ruby_tool_config(arguments: [File.join(dir, script)]), [])
+        command[:options] = { :boom => false }
+        executor.exec(command)
+      end
+
+      expect(executor.failed?(results[0])).to be true
+      expect(executor.failed?(results[1])).to be false
+    end
+  end
+
+  it 'captures real stderr output separately from real stdout' do
+    with_source_tree({ 'split.rb' => '$stdout.puts "on-stdout"; $stderr.puts "on-stderr"' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'split.rb')])
+      command = executor.build_command_line(tool, [])
+
+      result = executor.exec(command)
+
+      expect(result[:stdout]).to include('on-stdout')
+      expect(result[:stdout]).to_not include('on-stderr')
+      expect(result[:stderr]).to include('on-stderr')
+      expect(result[:stderr]).to_not include('on-stdout')
+    end
+  end
+
+  it 'measures a real non-negative elapsed :time for the real shell-out' do
+    with_source_tree({ 'probe.rb' => 'puts "done"' }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'probe.rb')])
+      command = executor.build_command_line(tool, [])
+
+      result = executor.exec(command)
+
+      expect(result[:time]).to be_a(Numeric)
+      expect(result[:time]).to be >= 0
+    end
+  end
+
+  it 'reads a real fixture file, whose path is substituted as a ${n} argument, through a real shell-out' do
+    with_source_tree({
+      'read_file.rb' => 'print File.read(ARGV[0])',
+      'input.txt'    => 'ceedling-fixture-content',
+    }) do |dir|
+      tool = ruby_tool_config(arguments: [File.join(dir, 'read_file.rb'), '${1}'])
+
+      command = executor.build_command_line(tool, [], File.join(dir, 'input.txt'))
+      result = executor.exec(command)
+
+      expect(result[:stdout]).to eq('ceedling-fixture-content')
+    end
+  end
+
+  it 'builds and runs a real command line using the tools.md-documented hash-style array-substitution shortcut' do
+    with_source_tree({ 'echo_args.rb' => 'print ARGV.join(",")' }) do |dir|
+      # Mirrors tools.md's own :test_linker example ("-l$-lib:" with a YAML array of
+      # plain library names) -- each array item is a literal value, not a Ruby constant
+      # or expression, dropped into the substitution string as-is.
+      tool = {
+        name: 'ruby_probe',
+        executable: RbConfig.ruby,
+        arguments: [File.join(dir, 'echo_args.rb'), { '$-suffix' => ['foo', 'bar'] }],
+      }
+
+      command = executor.build_command_line(tool, [])
+      result = executor.exec(command)
+
+      expect(result[:stdout]).to eq('foo-suffix,bar-suffix')
+    end
+  end
+
+  # Platform-detection-is-the-thing-under-test: SystemWrapper.windows?/SystemUtils#tcsh_shell?
+  # are the exact predicates ToolExecutorHelper itself branches on, so asserting against them
+  # directly checks "does the real resulting command actually work on this real platform" --
+  # something a unit test stubbing those predicates can never confirm. Different from
+  # dependency_tracker_filename_handling_spec.rb's empirical-probe style, which exists
+  # specifically because filesystem case-sensitivity is *not* reliably implied by RUBY_PLATFORM;
+  # here the platform predicate genuinely *is* what's under test.
+
+  context 'osify_path_separators on the real platform' do
+    it 'converts forward slashes to backslashes in the real executable path used to build the command line', skip: (SystemWrapper.windows? ? false : 'Windows-only: osify_path_separators is a no-op elsewhere') do
+      forward_slash_executable = RbConfig.ruby.tr('\\', '/')
+      tool = { name: 'ruby_probe', executable: forward_slash_executable, arguments: [] }
+
+      command = executor.build_command_line(tool, [])
+
+      expect(command[:executable]).to_not include('/')
+
+      result = executor.exec(command)
+      expect(result[:exit_code]).to eq(0)
+    end
+
+    it 'leaves a forward-slash executable path unchanged on a real non-Windows platform', skip: (SystemWrapper.windows? ? 'non-Windows-only' : false) do
+      tool = ruby_tool_config
+
+      command = executor.build_command_line(tool, [])
+
+      expect(command[:executable]).to eq(RbConfig.ruby)
+    end
+  end
+
+  context ':auto stderr redirect on the real platform' do
+    def redirect_probe_tool(dir)
+      ruby_tool_config(arguments: [File.join(dir, 'stderr_only.rb')])
+    end
+
+    it 'appends 2>&1 and runs successfully on real Windows', skip: (SystemWrapper.windows? ? false : 'Windows-only') do
+      with_source_tree({ 'stderr_only.rb' => '$stderr.puts "err-text"' }) do |dir|
+        tool = redirect_probe_tool(dir)
+        command = executor.build_command_line(tool, [])
+        command[:options] = { :stderr_redirect => StdErrRedirect::AUTO }
+
+        result = executor.exec(command)
+
+        expect(result[:exit_code]).to eq(0)
+      end
+    end
+
+    it 'appends 2>&1 and runs successfully on a real non-Windows, non-tcsh shell', skip: (!SystemWrapper.windows? && !SystemUtils.new(system_wrapper: SystemWrapper.new).tcsh_shell? ? false : 'requires non-Windows, non-tcsh') do
+      with_source_tree({ 'stderr_only.rb' => '$stderr.puts "err-text"' }) do |dir|
+        tool = redirect_probe_tool(dir)
+        command = executor.build_command_line(tool, [])
+        command[:options] = { :stderr_redirect => StdErrRedirect::AUTO }
+
+        result = executor.exec(command)
+
+        expect(result[:exit_code]).to eq(0)
+      end
+    end
+
+    it 'appends |& and runs successfully when the real shell is tcsh', skip: (!SystemWrapper.windows? && SystemUtils.new(system_wrapper: SystemWrapper.new).tcsh_shell? ? false : 'tcsh not available') do
+      with_source_tree({ 'stderr_only.rb' => '$stderr.puts "err-text"' }) do |dir|
+        tool = redirect_probe_tool(dir)
+        command = executor.build_command_line(tool, [])
+        command[:options] = { :stderr_redirect => StdErrRedirect::AUTO }
+
+        result = executor.exec(command)
+
+        expect(result[:exit_code]).to eq(0)
+      end
+    end
+  end
+end