ceedling 1.1.10 → 1.2.0

data/spec/units/preprocess/preprocessinator_spec.rb

@@ -8,6 +8,7 @@
 require 'spec_helper'
 require 'ceedling/preprocess/preprocessinator'
 require 'ceedling/includes/includes'
+require 'ceedling/tool_executor'
 
 RSpec.describe Preprocessinator do
 
@@ -17,8 +18,8 @@ RSpec.describe Preprocessinator do
     @file_assembler    = double('preprocessinator_file_assembler')
     @reconstructor     = double('preprocessinator_reconstructor')
     @file_path_utils   = double('file_path_utils')
-    @tool_executor     = double('tool_executor')
     @file_wrapper      = double('file_wrapper')
+    @tool_executor     = double('tool_executor')
     @plugin_manager    = double('plugin_manager')
     @configurator      = double('configurator')
     @loginator         = double('loginator')
@@ -28,6 +29,17 @@ RSpec.describe Preprocessinator do
     allow(@loginator).to receive(:log_list)
     allow(@reportinator).to receive(:generate_module_progress).and_return('')
     allow(@configurator).to receive(:cmock_mock_prefix).and_return('Mock')
+    # Whoever writes a preprocessed file creates its directory, since the path may mirror
+    # a source's own namespace below the test's flat preprocess directories.
+    allow(@file_wrapper).to receive(:mkdir)
+    # The real rule, so a stubbed result reads exactly as it would from a real run
+    allow(@tool_executor).to receive(:failed?) { |result| ToolExecutor.allocate.failed?( result ) }
+  end
+
+  # What a failed command run with :boom false really returns: a zero exit code with a
+  # failed process status. A bare nonzero :exit_code cannot occur under :boom false.
+  def failed_run
+    { exit_code: 0, status: instance_double(Process::Status, success?: false) }
   end
 
   subject do
@@ -37,8 +49,8 @@ RSpec.describe Preprocessinator do
       preprocessinator_file_assembler:   @file_assembler,
       preprocessinator_reconstructor:    @reconstructor,
       file_path_utils:                   @file_path_utils,
-      tool_executor:                     @tool_executor,
       file_wrapper:                      @file_wrapper,
+      tool_executor:                     @tool_executor,
       plugin_manager:                    @plugin_manager,
       configurator:                      @configurator,
       loginator:                         @loginator,
@@ -67,12 +79,17 @@ RSpec.describe Preprocessinator do
     end
 
     before do
-      # Force the cache-miss path so real extraction runs every time.
+      # preprocess_file_includes_common is only ever called once a caller has
+      # already determined, via its own DependencyTracker target, that this
+      # file/test pair is stale -- no internal freshness check to route around,
+      # so extraction runs for real on every call here.
       allow(@file_path_utils).to receive(:form_preprocessed_includes_list_filepath).and_return('/build/includes/module.c.yml')
-      allow(@file_wrapper).to receive(:newer?).and_return(false)
       allow(@includes_handler).to receive(:write_includes_list)
 
       allow(@includes_handler).to receive(:extract_system_includes_preprocess).and_return([])
+      # Computed-include supplement: off by default here; the dedicated cases below
+      # override this return to exercise the union.
+      allow(@includes_handler).to receive(:extract_computed_includes).and_return([])
     end
 
     # Regression coverage for #1223: the gcc-based bare pass runs against an
@@ -113,8 +130,17 @@ RSpec.describe Preprocessinator do
       expect(result.map(&:filename)).not_to include('phantom.h')
     end
 
+    # A header's text scan stands in for a failed gcc pass
+    it "reconciles from the text-scan bare pass when the gcc bare pass failed" do
+      allow(@includes_handler).to receive(:extract_bare_includes).and_return( nil )
+      allow(@includes_handler).to receive(:extract_bare_includes_from_text).and_return( [ Include.new('Types.h') ] )
+      allow(@includes_handler).to receive(:extract_user_includes_preprocess).and_return( [ UserInclude.new('Types.h') ] )
+
+      expect(call_it().map(&:filename)).to eq( ['Types.h'] )
+    end
+
     # Both bare sources finding the same entry must not produce a duplicate
-    # (the union is deduplicated by filename before being handed to reconcile).
+    # (the union is deduplicated by filepath before being handed to reconcile).
     it "does not duplicate an entry both bare passes agree on" do
       allow(@includes_handler).to receive(:extract_bare_includes).and_return(
         [ Include.new('Types.h') ]
@@ -131,6 +157,668 @@ RSpec.describe Preprocessinator do
       expect(result.map(&:filename)).to eq(['Types.h'])
     end
 
+    # The union dedups by filepath, not filename -- two bare entries that merely
+    # SHARE a basename but are genuinely different files (different filepath) must
+    # both survive into reconcile. Deduping by filename alone would silently drop
+    # one distinct header and everything it declares from the reconstructed file.
+    it "keeps two bare entries with the same basename but different filepaths distinct" do
+      allow(@includes_handler).to receive(:extract_bare_includes).and_return(
+        [ Include.new('hw/config.h') ]
+      )
+      allow(@includes_handler).to receive(:extract_bare_includes_from_text).and_return(
+        [ Include.new('hw/config.h'), Include.new('app/config.h') ]
+      )
+      allow(@includes_handler).to receive(:extract_user_includes_preprocess).and_return(
+        [ UserInclude.new('hw/config.h'), UserInclude.new('app/config.h') ]
+      )
+
+      result = call_it()
+
+      expect(result.map(&:filepath)).to contain_exactly('hw/config.h', 'app/config.h')
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#preprocessed_dependencies' do
+  # ===========================================================================
+
+    it "gives the files a preprocessor's output entered" do
+      allow(@includes_handler).to receive(:extract_preprocessed_dependencies)
+        .with( preprocessed_filepath: 'build/do/test_a.c' ).and_return( ['src/config.h'] )
+
+      expect(subject.preprocessed_dependencies( preprocessed_filepath: 'build/do/test_a.c' )).to eq( ['src/config.h'] )
+    end
+  end
+
+  # ===========================================================================
+  describe '#supplement_with_text_includes / #supplement_with_computed_includes' do
+  # ===========================================================================
+
+    it "adds a file's literal #includes to a bare list, once each by filepath" do
+      allow(@includes_handler).to receive(:extract_bare_includes_from_text).with( filepath: 'test/test_a.c' )
+        .and_return( [ Include.new('a.h'), Include.new('hw/config.h'), Include.new('app/config.h') ] )
+
+      result = subject.supplement_with_text_includes( filepath: 'test/test_a.c', bare: [ Include.new('a.h'), Include.new('hw/config.h') ] )
+
+      expect(result.map(&:filepath)).to eq( ['a.h', 'hw/config.h', 'app/config.h'] )
+    end
+
+    it "adds the #includes a macro names, as the directives-only output resolved them" do
+      allow(@includes_handler).to receive(:extract_computed_includes)
+        .with( filepath: 'test/test_a.c', directives_only_filepath: 'build/do/test_a.c' )
+        .and_return( [ Include.new('mock_widget.h'), Include.new('a.h') ] )
+
+      result = subject.supplement_with_computed_includes(
+        filepath: 'test/test_a.c', bare: [ Include.new('a.h') ], directives_only_filepath: 'build/do/test_a.c'
+      )
+
+      expect(result.map(&:filepath)).to eq( ['a.h', 'mock_widget.h'] )
+    end
+  end
+
+  # ===========================================================================
+  describe '#preprocess_partial_header_expand_macros / #preprocess_partial_source_expand_macros' do
+  # ===========================================================================
+  # Both public methods funnel through the same private _preprocess_partial_expand_macros.
+
+    let(:filepath) { '/src/module.c' }
+
+    def call_it(method: :preprocess_partial_header_expand_macros)
+      subject.send(
+        method,
+        filepath:      filepath,
+        test:          'test',
+        flags:         [],
+        include_paths: [],
+        vendor_paths:  [],
+        defines:       []
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_file_full_expansion_filepath).and_return('/build/full_expansion/module.c')
+      allow(@configurator).to receive(:tools_test_file_full_preprocessor).and_return({})
+      allow(@tool_executor).to receive(:build_command_line).and_return({ options: {} })
+    end
+
+    # Without boom: false, the real ToolExecutor#exec (not this double) raises
+    # ShellException on a nonzero exit code before the fallback below it ever runs,
+    # crashing the build instead of gracefully degrading as documented.
+    it "sets boom: false on the command before invoking the full preprocessor" do
+      captured_command = nil
+      allow(@tool_executor).to receive(:exec) do |command|
+        captured_command = command
+        { exit_code: 0 }
+      end
+      allow(@file_assembler).to receive(:collect_file_contents_from_full_expansion).and_return([])
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file)
+
+      call_it()
+
+      expect(captured_command[:options][:boom]).to eq(false)
+    end
+
+    # Vendor paths follow the file's own search paths, so a project header wins a name clash
+    it "runs the full preprocessor tool on the file, its output, defines, and search paths ahead of vendor paths" do
+      allow(@configurator).to receive(:tools_test_file_full_preprocessor).and_return( { name: 'full' } )
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      subject.send( :preprocess_partial_header_expand_macros,
+        filepath: filepath, test: 'test', flags: ['-std=c99'], include_paths: ['inc'], vendor_paths: ['vendor'], defines: ['FOO']
+      )
+
+      expect(@tool_executor).to have_received(:build_command_line).with(
+        { name: 'full' }, ['-std=c99'], filepath, '/build/full_expansion/module.c', ['FOO'], ['inc', 'vendor']
+      )
+    end
+
+    it "returns nil without raising when the full preprocessor invocation fails" do
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      result = nil
+      expect { result = call_it() }.to_not raise_error
+      expect(result).to be_nil
+    end
+
+    it "returns nil without raising via preprocess_partial_source_expand_macros too" do
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      result = nil
+      expect { result = call_it(method: :preprocess_partial_source_expand_macros) }.to_not raise_error
+      expect(result).to be_nil
+    end
+
+    it "returns the full expansion filepath and assembles the code file on success" do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0 })
+      allow(@file_assembler).to receive(:collect_file_contents_from_full_expansion).and_return(['expanded line'])
+
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file) { |**kwargs| captured = kwargs }
+
+      result = call_it()
+
+      expect(result).to eq('/build/full_expansion/module.c')
+      expect(captured[:contents]).to eq(['expanded line'])
+      expect(captured[:includes]).to eq([])
+      expect(captured[:extras]).to eq([])
+    end
+
+    it "reaches the same success behavior via preprocess_partial_source_expand_macros too" do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0 })
+      allow(@file_assembler).to receive(:collect_file_contents_from_full_expansion).and_return(['expanded line'])
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file)
+
+      result = call_it(method: :preprocess_partial_source_expand_macros)
+
+      expect(result).to eq('/build/full_expansion/module.c')
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#generate_directives_only_output' do
+  # ===========================================================================
+
+    let(:filepath) { '/src/module.c' }
+
+    def call_it
+      subject.generate_directives_only_output(
+        filepath:      filepath,
+        test:          'test',
+        flags:         [],
+        include_paths: [],
+        vendor_paths:  [],
+        defines:       []
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_file_raw_directives_only_filepath).and_return('/build/directives_only/module.c')
+      allow(@file_path_utils).to receive(:form_preprocessed_file_compacted_directives_only_filepath).and_return('/build/directives_only/module_compacted.c')
+      allow(@configurator).to receive(:tools_test_file_directives_only_preprocessor).and_return({})
+      allow(@tool_executor).to receive(:build_command_line).and_return({ options: {} })
+      allow(@comment_stripper).to receive(:strip_file)
+      allow(@reconstructor).to receive(:compact_file_from_expansion)
+    end
+
+    # A preprocessed artifact's path mirrors its source's own namespace, so the directory
+    # may not exist yet -- a test's flat preprocess directories are created with the rest
+    # of its build paths, before any source is known. Both outputs are written here.
+    it 'creates the directory for each output it writes' do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0, output: '' })
+
+      expect(@file_wrapper).to receive(:mkdir).with('/build/directives_only').twice
+
+      call_it
+    end
+
+    it "sets boom: false on the command before invoking the directives-only preprocessor" do
+      captured_command = nil
+      allow(@tool_executor).to receive(:exec) do |command|
+        captured_command = command
+        { exit_code: 0 }
+      end
+
+      call_it()
+
+      expect(captured_command[:options][:boom]).to eq(false)
+    end
+
+    it "runs the directives-only tool on the file, its raw output, defines, and search paths ahead of vendor paths" do
+      allow(@configurator).to receive(:tools_test_file_directives_only_preprocessor).and_return( { name: 'directives-only' } )
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      subject.generate_directives_only_output(
+        filepath: filepath, test: 'test', flags: ['-std=c99'], include_paths: ['inc'], vendor_paths: ['vendor'], defines: ['FOO']
+      )
+
+      expect(@tool_executor).to have_received(:build_command_line).with(
+        { name: 'directives-only' }, ['-std=c99'], filepath, '/build/directives_only/module.c', ['FOO'], ['inc', 'vendor']
+      )
+    end
+
+    it "logs that the file falls back when the preprocessor fails" do
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      call_it()
+
+      expect(@loginator).to have_received(:log).with( /Failed to generate directive-only preprocessor output .* for \/src\/module\.c/, Verbosity::OBNOXIOUS, LogLabels::ERROR )
+    end
+
+    it "on success, strips comments, compacts the expansion, and returns the raw filepath" do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0 })
+
+      result = call_it()
+
+      expect(@comment_stripper).to have_received(:strip_file).with('/build/directives_only/module.c')
+      expect(@reconstructor).to have_received(:compact_file_from_expansion).with(
+        input_filepath:  '/build/directives_only/module.c',
+        source_filepath: filepath,
+        output_filepath: '/build/directives_only/module_compacted.c'
+      )
+      expect(result).to eq('/build/directives_only/module.c')
+    end
+
+    it "returns nil without stripping or compacting when the preprocessor fails" do
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      result = call_it()
+
+      expect(@comment_stripper).to_not have_received(:strip_file)
+      expect(@reconstructor).to_not have_received(:compact_file_from_expansion)
+      expect(result).to be_nil
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#generate_fallback_expansion_output' do
+  # ===========================================================================
+  # Fallback's stand-in for directives-only output: a plain expansion whose line markers
+  # name the files the preprocessor entered. Nothing reads its code, so it is neither
+  # stripped nor compacted.
+
+    let(:filepath) { '/src/test_module.c' }
+
+    def call_it
+      subject.generate_fallback_expansion_output(
+        filepath: filepath, test: 'test', flags: ['-std=c99'], include_paths: ['inc'], vendor_paths: ['vendor'], defines: ['FOO']
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_file_fallback_expansion_filepath).and_return('/build/fallback_expansion/test_module.c')
+      allow(@configurator).to receive(:tools_test_file_full_preprocessor).and_return( { name: 'full' } )
+      allow(@tool_executor).to receive(:build_command_line).and_return({ options: {} })
+      allow(@comment_stripper).to receive(:strip_file)
+      allow(@reconstructor).to receive(:compact_file_from_expansion)
+    end
+
+    it 'runs the full preprocessor tool on the file, its expansion, defines, and search paths ahead of vendor paths' do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0 })
+
+      call_it
+
+      expect(@tool_executor).to have_received(:build_command_line).with(
+        { name: 'full' }, ['-std=c99'], filepath, '/build/fallback_expansion/test_module.c', ['FOO'], ['inc', 'vendor']
+      )
+    end
+
+    it 'sets boom: false and creates the expansion\'s directory' do
+      captured_command = nil
+      allow(@tool_executor).to receive(:exec) { |command| captured_command = command; { exit_code: 0 } }
+
+      expect(@file_wrapper).to receive(:mkdir).with('/build/fallback_expansion')
+
+      call_it
+
+      expect(captured_command[:options][:boom]).to eq(false)
+    end
+
+    it 'returns the expansion\'s path without stripping comments or compacting' do
+      allow(@tool_executor).to receive(:exec).and_return({ exit_code: 0 })
+
+      expect(call_it).to eq('/build/fallback_expansion/test_module.c')
+      expect(@comment_stripper).to_not have_received(:strip_file)
+      expect(@reconstructor).to_not have_received(:compact_file_from_expansion)
+    end
+
+    it 'returns nil without raising, and logs that text-scan #includes will be used, when the preprocessor fails' do
+      allow(@tool_executor).to receive(:exec).and_return( failed_run )
+
+      result = nil
+      expect { result = call_it }.to_not raise_error
+
+      expect(result).to be_nil
+      expect(@loginator).to have_received(:log).with(
+        'Failed to generate fallback preprocessor expansion (text-scan #includes will be used) for /src/test_module.c', Verbosity::OBNOXIOUS, LogLabels::ERROR
+      )
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#store_includes_list / #load_includes_list' do
+  # ===========================================================================
+
+    let(:filepath) { '/src/module.h' }
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_includes_list_filepath).and_return('/build/includes/module.h.yml')
+    end
+
+    it "writes includes to the path computed from filepath/test" do
+      captured = nil
+      allow(@includes_handler).to receive(:write_includes_list) { |path, includes| captured = [path, includes] }
+
+      subject.store_includes_list( test: 'test', filepath: filepath, includes: [ UserInclude.new('a.h') ] )
+
+      expect(captured[0]).to eq('/build/includes/module.h.yml')
+      expect(captured[1].map(&:filename)).to eq(['a.h'])
+    end
+
+    it "loads includes from the same computed path" do
+      loaded = [ UserInclude.new('a.h') ]
+      allow(@includes_handler).to receive(:load_includes_list).with('/build/includes/module.h.yml').and_return(loaded)
+
+      result = subject.load_includes_list( test: 'test', filepath: filepath )
+
+      expect(result).to eq(loaded)
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#preprocess_user_includes / #preprocess_system_includes' do
+  # ===========================================================================
+    # Each is a thin dispatcher: the accurate line-marker extraction when fallback is
+    # false, the text-scan extraction when it is true.
+
+    it "uses the line-marker (preprocess) extraction when fallback: false" do
+      expect(@includes_handler).to receive(:extract_user_includes_preprocess)
+        .with(name: 't', filepath: 'f.h', preprocessed_filepath: 'd.pp').and_return([])
+      subject.preprocess_user_includes(name: 't', filepath: 'f.h', directives_only_filepath: 'd.pp', fallback: false)
+    end
+
+    it "uses the text-scan (fallback) extraction when fallback: true" do
+      expect(@includes_handler).to receive(:extract_system_includes_from_text)
+        .with(name: 't', filepath: 'f.h', defines: ['X']).and_return([])
+      subject.preprocess_system_includes(name: 't', filepath: 'f.h', directives_only_filepath: nil, fallback: true, defines: ['X'])
+    end
+  end
+
+  # ===========================================================================
+  describe '#reconcile_includes' do
+  # ===========================================================================
+    # The merge step shared by preprocess_file_includes_common and stage 4's test-file
+    # pass: bare ∩ (user ∪ system), a NOTICE on a genuinely ambiguous #include, and an
+    # optional mock-supersedes-real filter. Uses the real Includes.reconcile.
+
+    it "keeps only entries the bare list and the accurate user/system lists agree on" do
+      result = subject.reconcile_includes(
+        bare:   [ Include.new('a.h'), Include.new('b.h') ],
+        user:   [ UserInclude.new('a.h') ],
+        system: [ SystemInclude.new('sys.h') ],   # not in bare -> dropped
+        test_filepath: 'test/T.c'
+      )
+      expect(result.map(&:filename)).to eq(['a.h'])
+    end
+
+    it "logs an ℹ️ NOTICE naming the chosen file and the candidates passed over for an ambiguous #include" do
+      expect(@loginator).to receive(:log).with(
+        a_string_matching(/foo\/bar\.h/).and(a_string_matching(/baz\/bar\.h/)).and(a_string_matching(%r{test/T\.c})),
+        Verbosity::COMPLAIN, LogLabels::NOTICE
+      )
+      subject.reconcile_includes(
+        bare:   [ Include.new('bar.h') ],
+        user:   [ UserInclude.new('foo/bar.h'), UserInclude.new('baz/bar.h') ],
+        system: [],
+        test_filepath: 'test/T.c'
+      )
+    end
+
+    it "logs no NOTICE when every bare #include resolves uniquely" do
+      expect(@loginator).to_not receive(:log).with(anything, Verbosity::COMPLAIN, LogLabels::NOTICE)
+      subject.reconcile_includes(
+        bare:   [ Include.new('bar.h') ],
+        user:   [ UserInclude.new('foo/bar.h') ],
+        system: [],
+        test_filepath: 'test/T.c'
+      )
+    end
+
+    it "drops a header whose mock is also present when drop_mocked is true (the default)" do
+      result = subject.reconcile_includes(
+        bare:   [ Include.new('sensor.h'), Include.new('Mocksensor.h') ],
+        user:   [ UserInclude.new('sensor.h'), UserInclude.new('Mocksensor.h') ],
+        system: [],
+        test_filepath: 'test/T.c'
+      )
+      expect(result.map(&:filename)).to eq(['Mocksensor.h'])
+    end
+
+    it "keeps a header alongside its mock when drop_mocked is false" do
+      result = subject.reconcile_includes(
+        bare:   [ Include.new('sensor.h'), Include.new('Mocksensor.h') ],
+        user:   [ UserInclude.new('sensor.h'), UserInclude.new('Mocksensor.h') ],
+        system: [],
+        test_filepath: 'test/T.c',
+        drop_mocked: false
+      )
+      expect(result.map(&:filename)).to contain_exactly('sensor.h', 'Mocksensor.h')
+    end
+  end
+
+  # ===========================================================================
+  describe '#preprocess_mockable_header_file' do
+  # ===========================================================================
+
+    let(:filepath) { '/src/module.h' }
+
+    def call_it(extras: false)
+      subject.preprocess_mockable_header_file(
+        test:                      'test',
+        filepath:                  filepath,
+        directives_only_filepath:  '/build/directives_only/module.h',
+        fallback:                  false,
+        flags:                     [],
+        include_paths:             [],
+        vendor_paths:              [],
+        defines:                   [],
+        extras:                    extras
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_file_filepath).and_return('/build/preprocessed/module.h')
+      allow(@file_path_utils).to receive(:preprocessed_file_subpath).and_return('drivers/uart/module.h')
+      allow(@file_path_utils).to receive(:form_preprocessed_includes_list_filepath).and_return('/build/includes/module.h.yml')
+      allow(@includes_handler).to receive(:extract_bare_includes).and_return([])
+      allow(@includes_handler).to receive(:extract_bare_includes_from_text).and_return([])
+      allow(@includes_handler).to receive(:extract_computed_includes).and_return([])
+      allow(@includes_handler).to receive(:extract_user_includes_preprocess).and_return([])
+      allow(@includes_handler).to receive(:extract_system_includes_preprocess).and_return([])
+      allow(@includes_handler).to receive(:write_includes_list)
+      allow(@file_assembler).to receive(:collect_mockable_header_file_contents).and_return([['content'], [], nil])
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file)
+      allow(@plugin_manager).to receive(:pre_mock_preprocess)
+      allow(@plugin_manager).to receive(:post_mock_preprocess)
+    end
+
+    it "returns the preprocessed filepath" do
+      expect(call_it()).to eq('/build/preprocessed/module.h')
+    end
+
+    it "fires pre_mock_preprocess before assembling and post_mock_preprocess after" do
+      order = []
+      allow(@plugin_manager).to receive(:pre_mock_preprocess) { order << :pre }
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file) { order << :assemble }
+      allow(@plugin_manager).to receive(:post_mock_preprocess) { order << :post }
+
+      call_it()
+
+      expect(order).to eq([:pre, :assemble, :post])
+    end
+
+    it "passes extracted contents, extras, and include guard through to assemble_preprocessed_header_file" do
+      allow(@file_assembler).to receive(:collect_mockable_header_file_contents).and_return([['line1'], ['extra1'], 'MODULE_H'])
+
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file) { |**kwargs| captured = kwargs }
+
+      call_it()
+
+      expect(captured[:contents]).to eq(['line1'])
+      expect(captured[:extras]).to eq(['extra1'])
+      expect(captured[:include_guard]).to eq('MODULE_H')
+    end
+
+    # A synthetic guard is derived from this, and a basename alone would give two headers
+    # sharing one name the same guard.
+    it "passes the header's own mirrored namespace, not a bare basename" do
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file) { |**kwargs| captured = kwargs }
+
+      call_it()
+
+      expect(captured[:filepath]).to eq('drivers/uart/module.h')
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#preprocess_partial_header_file_preserve_macros / #preprocess_partial_source_file_preserve_macros' do
+  # ===========================================================================
+
+    let(:filepath) { '/src/module.h' }
+
+    def call_it(method:, fallback:)
+      subject.send(
+        method,
+        test:                      'test',
+        filepath:                  filepath,
+        directives_only_filepath:  '/build/directives_only/module.h',
+        fallback:                  fallback,
+        flags:                     [],
+        include_paths:             [],
+        vendor_paths:              [],
+        defines:                   []
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:preprocessed_file_subpath) { |path| File.basename(path) }
+      allow(@file_path_utils).to receive(:form_preprocessed_file_filepath).and_return('/build/preprocessed/module.h')
+      allow(@file_path_utils).to receive(:form_preprocessed_includes_list_filepath).and_return('/build/includes/module.h.yml')
+      allow(@includes_handler).to receive(:extract_bare_includes).and_return([])
+      allow(@includes_handler).to receive(:extract_bare_includes_from_text).and_return([])
+      allow(@includes_handler).to receive(:extract_computed_includes).and_return([])
+      allow(@includes_handler).to receive(:extract_user_includes_preprocess).and_return([])
+      allow(@includes_handler).to receive(:extract_user_includes_from_text).and_return([])
+      allow(@includes_handler).to receive(:extract_system_includes_preprocess).and_return([])
+      allow(@includes_handler).to receive(:extract_system_includes_from_text).and_return([])
+      allow(@includes_handler).to receive(:write_includes_list)
+      allow(@file_assembler).to receive(:collect_file_contents_fallback).and_return(['fallback content'])
+      allow(@file_assembler).to receive(:collect_file_contents_from_directives_only_preprocessing).and_return(['directives content'])
+      allow(@file_assembler).to receive(:collect_macros_and_pragmas_fallback).and_return(['macro'])
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file)
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file)
+    end
+
+    it "uses the fallback content-source and re-extracts macros/pragmas when fallback: true (header)" do
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file) { |**kwargs| captured = kwargs }
+
+      call_it(method: :preprocess_partial_header_file_preserve_macros, fallback: true)
+
+      expect(@file_assembler).to have_received(:collect_file_contents_fallback)
+      expect(@file_assembler).to_not have_received(:collect_file_contents_from_directives_only_preprocessing)
+      expect(captured[:contents]).to eq(['fallback content'])
+      expect(captured[:extras]).to eq(['macro'])
+    end
+
+    it "uses directives-only content and empty extras when fallback: false (header)" do
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_header_file) { |**kwargs| captured = kwargs }
+
+      call_it(method: :preprocess_partial_header_file_preserve_macros, fallback: false)
+
+      expect(@file_assembler).to have_received(:collect_file_contents_from_directives_only_preprocessing)
+      expect(@file_assembler).to_not have_received(:collect_file_contents_fallback)
+      expect(captured[:contents]).to eq(['directives content'])
+      expect(captured[:extras]).to eq([])
+    end
+
+    it "uses the fallback content-source for the source-file variant too" do
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file) { |**kwargs| captured = kwargs }
+
+      call_it(method: :preprocess_partial_source_file_preserve_macros, fallback: true)
+
+      expect(captured[:contents]).to eq(['fallback content'])
+      expect(captured[:extras]).to eq(['macro'])
+    end
+
+    it "returns the preprocessed filepath and the discovered includes" do
+      preprocessed_filepath, includes = call_it(method: :preprocess_partial_header_file_preserve_macros, fallback: false)
+
+      expect(preprocessed_filepath).to eq('/build/preprocessed/module.h')
+      expect(includes).to eq([])
+    end
+
+  end
+
+  # ===========================================================================
+  describe '#preprocess_test_file' do
+  # ===========================================================================
+
+    let(:filepath) { '/test/test_module.c' }
+
+    def call_it
+      subject.preprocess_test_file(
+        test:                      'test',
+        filepath:                  filepath,
+        directives_only_filepath:  '/build/directives_only/test_module.c',
+        fallback:                  false,
+        includes:                  [],
+        flags:                     [],
+        include_paths:             [],
+        vendor_paths:              [],
+        defines:                   []
+      )
+    end
+
+    before do
+      allow(@file_path_utils).to receive(:form_preprocessed_file_filepath).and_return('/build/preprocessed/test_module.c')
+      allow(@file_assembler).to receive(:collect_test_file_contents).and_return([['content'], ['extra']])
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file)
+      allow(@plugin_manager).to receive(:pre_test_preprocess)
+      allow(@plugin_manager).to receive(:post_test_preprocess)
+    end
+
+    it "returns the preprocessed filepath" do
+      expect(call_it()).to eq('/build/preprocessed/test_module.c')
+    end
+
+    it "fires pre_test_preprocess before assembling and post_test_preprocess after" do
+      order = []
+      allow(@plugin_manager).to receive(:pre_test_preprocess) { order << :pre }
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file) { order << :assemble }
+      allow(@plugin_manager).to receive(:post_test_preprocess) { order << :post }
+
+      call_it()
+
+      expect(order).to eq([:pre, :assemble, :post])
+    end
+
+    it "does not extract includes again -- the caller already supplied them" do
+      expect(@includes_handler).to_not receive(:extract_bare_includes)
+
+      call_it()
+    end
+
+    it "passes the given includes straight through to assemble_preprocessed_code_file" do
+      given_includes = [ UserInclude.new('a.h') ]
+
+      captured = nil
+      allow(@file_assembler).to receive(:assemble_preprocessed_code_file) { |**kwargs| captured = kwargs }
+
+      subject.preprocess_test_file(
+        test:                      'test',
+        filepath:                  filepath,
+        directives_only_filepath:  '/build/directives_only/test_module.c',
+        fallback:                  false,
+        includes:                  given_includes,
+        flags:                     [],
+        include_paths:             [],
+        vendor_paths:              [],
+        defines:                   []
+      )
+
+      expect(captured[:includes]).to eq(given_includes)
+    end
+
   end
 
 end