ceedling 1.1.9 → 1.2.0

data/spec/system/support/valgrind_common_test_cases.rb

@@ -39,6 +39,26 @@ module ValgrindCommonTestCases
     end
   end
 
+  # The plugin builds in its own context, apart from test builds
+  def run_valgrind_build_removed_by_clobber
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_valgrind
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        @c.ceedling_build_exec("valgrind:all")
+        expect(Dir.glob('build/valgrind/**/*').select { |path| File.file?( path ) }).not_to be_empty
+
+        @c.ceedling_build_exec("clobber")
+        expect(@c.last_exit_status).to eq(0)
+        expect(Dir.glob('build/valgrind/**/*').select { |path| File.file?( path ) }).to be_empty
+        expect(Dir.glob('build/artifacts/valgrind/**/*').select { |path| File.file?( path ) }).to be_empty
+      end
+    end
+  end
+
   def run_valgrind_on_single_test
     @c.with_context do
       Dir.chdir @proj_name do
@@ -66,22 +86,21 @@ module ValgrindCommonTestCases
         prep_project_yml_for_valgrind
         FileUtils.cp test_asset_path("example_file.h"), 'src/'
         FileUtils.cp test_asset_path("example_file.c"), 'src/'
-        FileUtils.cp test_asset_path("test_example_file_crash_sigsegv.c"), 'test/'
+        FileUtils.cp test_asset_path("test_nosanitize_crash_sigsegv.c"), 'test/'
 
         output = @c.ceedling_build_exec("valgrind:all")
 
         expect(@c.last_exit_status).to eq(1) # Crash + Valgrind build failure
-        # Ceedling crash detection
-        expect(output).to match(/test_example_file_crash_sigsegv.+crashed/i)
-        # Per-test Valgrind memory error log (always fires when errors found)
-        expect(output).to match(/Valgrind detected.*memory error/i)
+        # The crash notice names the first memory error in place of the generic notice
+        expect(output).to match(/test_nosanitize_crash_sigsegv\.out` terminated with Valgrind memory errors\.\n> Invalid read of size \d+ at test_nosanitize_crash_sigsegv\.c:\d+\n> Boom log: /)
+        expect(output).not_to match(/seems to have crashed/)
         # Aggregate build failure registered by Valgrind plugin
         expect(output).to match(/Valgrind detected.*memory error.*across/i)
         expect(output).to match(/Wrote 1 Valgrind report/i)
-        expect(File.exist?('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to eq(true)
-        expect(File.size('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to be > 0
+        expect(File.exist?('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to eq(true)
+        expect(File.size('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to be > 0
         # Expected memory error(s) detected by Valgrind
-        expect(File.read('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to match(/ERROR SUMMARY:\s+[1-9]/)
+        expect(read_spec_file('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to match(/ERROR SUMMARY:\s+[1-9]/)
       end
     end
   end
@@ -97,22 +116,103 @@ module ValgrindCommonTestCases
         @c.merge_project_yml_for_test({ :valgrind => { :fail_build => false } })
         FileUtils.cp test_asset_path("example_file.h"), 'src/'
         FileUtils.cp test_asset_path("example_file.c"), 'src/'
-        FileUtils.cp test_asset_path("test_example_file_crash_sigsegv.c"), 'test/'
+        FileUtils.cp test_asset_path("test_nosanitize_crash_sigsegv.c"), 'test/'
 
         output = @c.ceedling_build_exec("valgrind:all")
 
         expect(@c.last_exit_status).to eq(1) # Crash causes failure even without Valgrind build failure
-        # Ceedling crash detection
-        expect(output).to match(/test_example_file_crash_sigsegv.+crashed/i)
-        # Per-test Valgrind error log still fires (independent of :fail_build)
-        expect(output).to match(/Valgrind detected.*memory error/i)
+        # The crash notice names the first memory error in place of the generic notice
+        expect(output).to match(/test_nosanitize_crash_sigsegv\.out` terminated with Valgrind memory errors\.\n> Invalid read of size \d+ at test_nosanitize_crash_sigsegv\.c:\d+\n> Boom log: /)
+        expect(output).not_to match(/seems to have crashed/)
         # No aggregate Valgrind build failure registered
         expect(output).not_to match(/Valgrind detected.*memory error.*across/i)
         expect(output).to match(/Wrote 1 Valgrind report/i)
-        expect(File.exist?('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to eq(true)
-        expect(File.size('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to be > 0
+        expect(File.exist?('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to eq(true)
+        expect(File.size('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to be > 0
         # Expected memory error(s) detected by Valgrind
-        expect(File.read('build/artifacts/valgrind/test_example_file_crash_sigsegv.log')).to match(/ERROR SUMMARY:\s+[1-9]/)
+        expect(read_spec_file('build/artifacts/valgrind/test_nosanitize_crash_sigsegv.log')).to match(/ERROR SUMMARY:\s+[1-9]/)
+      end
+    end
+  end
+
+  def run_valgrind_with_xml_report
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_valgrind
+        @c.merge_project_yml_for_test({ valgrind: { xml_report: true } })
+
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        @c.ceedling_build_exec("valgrind:all")
+
+        expect(@c.last_exit_status).to eq(0)
+
+        xml_path = 'build/artifacts/valgrind/test_example_file_success.xml'
+        expect(File.exist?(xml_path)).to eq(true)
+        expect(read_spec_file(xml_path)).to match(/<valgrindoutput>/)
+      end
+    end
+  end
+
+  def run_valgrind_with_suppressions
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_valgrind
+
+        # A well-formed suppression. Valgrind aborts the whole run when
+        # --suppressions names a file it cannot parse, so a clean build proves the
+        # argument reached Valgrind and was accepted. A suppression needs at least
+        # one location line that is not "...".
+        File.write('all.supp', "{\n   placeholder\n   Memcheck:Leak\n   fun:malloc\n}\n")
+        @c.merge_project_yml_for_test({ valgrind: { suppressions: ['all.supp'] } })
+
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        @c.ceedling_build_exec("valgrind:all")
+
+        expect(@c.last_exit_status).to eq(0)
+        expect(File.exist?('build/artifacts/valgrind/test_example_file_success.log')).to eq(true)
+      end
+    end
+  end
+
+  # Enabling the plugin must not make Valgrind a dependency of unrelated builds.
+  # Regression coverage for the same defect class as issue #1252 in the Gcov plugin.
+  # Only meaningful where Valgrind is absent, which is every non-Linux platform.
+  def test_build_unaffected_when_valgrind_absent
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_valgrind
+
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        output = @c.ceedling_build_exec("test:all")
+
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/PASSED:\s+\d/)
+      end
+    end
+  end
+
+  def valgrind_task_reports_platform_constraint
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_valgrind
+
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        output = @c.ceedling_build_exec("valgrind:all")
+
+        expect(@c.last_exit_status).to eq(1)
+        expect(output).to match(/Linux and other Unix-like systems|does not run on Windows/i)
       end
     end
   end

data/spec/system/support/valgrind_helpers.rb

@@ -9,12 +9,11 @@ require 'fileutils'
 
 module ValgrindHelpers
 
-  def valgrind_available?
-    tool_available?('valgrind --version 2>&1')
-  end
+  # valgrind_available? lives in spec_system_helper.rb beside the other tool probes,
+  # paired with the "requires valgrind" shared context.
 
   def prep_project_yml_for_valgrind
-    FileUtils.cp test_asset_path("project.yml"), "project.yml"
+    FileUtils.cp feature_asset_path("project.yml"), "project.yml"
     @c.uncomment_project_yml_option_for_test("- valgrind")
   end
 

data/spec/system/test_pipeline_stop_points_spec.rb

@@ -0,0 +1,160 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'spec_system_helper'
+
+# End-to-end coverage of the gen: namespace's pipeline stop-point tasks
+# (TestPipelineManager) against a real example project on disk -- proving each
+# task halts the test-build pipeline at its named stage rather than merely
+# succeeding.
+ceedling_system_tests do
+  before :all do
+    @c = SystemContext.new
+    @c.deploy_gem
+  end
+
+  after :all do
+    @c.done!
+  end
+
+  describe "Pipeline stop points (temp_sensor)" do
+    before do
+      @c.with_context do
+        output = @c.ceedling_appcmd_exec("example temp_sensor")
+        expect(output).to match(/created/)
+
+        # `example` only deploys src/test/project.yml -- a build/ directory left
+        # over from a prior example in this same shared context would make this
+        # test's targets look already fresh. Clobber guarantees an empty cache.
+        Dir.chdir "temp_sensor" do
+          @c.ceedling_build_exec("clobber")
+        end
+      end
+    end
+
+    it "gen:mocks generates mocks but compiles, links, and runs nothing, announcing a mocks-only run" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          output = @c.ceedling_build_exec("gen:mocks")
+
+          expect(output).to match(/Generating mock for adc\/TestAdcModel::TaskScheduler\.h/)
+          expect(output).to_not match(/Generating runner for/)
+          expect(output).to_not match(/^Compiling /)
+          expect(output).to_not match(/^Linking /)
+          expect(output).to_not match(/^Running /)
+          expect(output).to match(/Generating mocks only -- no test runners, compiling, linking, or running\./)
+
+          # Regression guard: gen: tasks must be recognized as build tasks (see
+          # tasks_tests_generate.rake/rules_tests_generate.rake's own namespace-nesting
+          # comments) so timing/completion logging isn't silently suppressed.
+          expect(output).to match(/Ceedling operations completed/)
+          expect(output).to match(/-+\n\s*MOCKS GENERATED\n-+/)
+        end
+      end
+    end
+
+    it "gen:test_runner generates mocks and runners but compiles, links, and runs nothing, announcing a mocks-and-runners-only run" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          output = @c.ceedling_build_exec("gen:test_runner")
+
+          expect(output).to match(/Generating mock for adc\/TestAdcModel::TaskScheduler\.h/)
+          expect(output).to match(/Generating runner for TestAdcModel\.c/)
+          expect(output).to_not match(/^Compiling /)
+          expect(output).to_not match(/^Linking /)
+          expect(output).to_not match(/^Running /)
+          expect(output).to match(/Generating mocks and test runners only -- no compiling, linking, or running\./)
+
+          expect(output).to match(/Ceedling operations completed/)
+          expect(output).to match(/-+\n\s*MOCKS & TEST RUNNERS GENERATED\n-+/)
+        end
+      end
+    end
+
+    it "gen:mocks:<file> generates only that one test's mocks, not every test's" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          output = @c.ceedling_build_exec("gen:mocks:TestAdcModel.c")
+
+          expect(output).to match(/Generating mock for adc\/TestAdcModel::TaskScheduler\.h/)
+          # TestAdcModel.c mocks TaskScheduler, TemperatureCalculator, and TemperatureFilter --
+          # exactly its own 3 mocks, none belonging to any other test.
+          expect(output.to_s.scan(/Generating mock for /).length).to eq(3)
+          expect(output).to_not match(/Generating runner for/)
+          expect(output).to_not match(/^Compiling /)
+          expect(output).to_not match(/^Linking /)
+          expect(output).to_not match(/^Running /)
+          expect(output).to match(/Generating mocks only -- no test runners, compiling, linking, or running\./)
+
+          expect(output).to match(/Ceedling operations completed/)
+          expect(output).to match(/-+\n\s*MOCKS GENERATED\n-+/)
+        end
+      end
+    end
+
+    it "gen:test_runner:<file> generates only that one test's mock(s) and runner, not every test's" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          output = @c.ceedling_build_exec("gen:test_runner:TestAdcModel.c")
+
+          expect(output).to match(/Generating mock for adc\/TestAdcModel::TaskScheduler\.h/)
+          # TestAdcModel.c mocks TaskScheduler, TemperatureCalculator, and TemperatureFilter --
+          # exactly its own 3 mocks, none belonging to any other test.
+          expect(output.to_s.scan(/Generating mock for /).length).to eq(3)
+          expect(output).to match(/Generating runner for TestAdcModel\.c/)
+          expect(output.to_s.scan(/Generating runner for /).length).to eq(1)
+          expect(output).to_not match(/^Compiling /)
+          expect(output).to_not match(/^Linking /)
+          expect(output).to_not match(/^Running /)
+          expect(output).to match(/Generating mocks and test runners only -- no compiling, linking, or running\./)
+
+          expect(output).to match(/Ceedling operations completed/)
+          expect(output).to match(/-+\n\s*MOCKS & TEST RUNNERS GENERATED\n-+/)
+        end
+      end
+    end
+
+    it "test:build_only builds test executables but does not run them, ending with its own completed-operations line and BUILT banner" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          output = @c.ceedling_build_exec("test:build_only")
+
+          expect(output).to match(/^Compiling /)
+          expect(output).to match(/^Linking /)
+          expect(output).to_not match(/^Running /)
+          expect(output).to match(/Building test executables only -- not running them\./)
+          expect(output).to match(/Ceedling operations completed/)
+          expect(output).to match(/-+\n\s*TEST EXECUTABLES BUILT\n-+/)
+        end
+      end
+    end
+
+    it "does not interfere with a subsequent test:all run's own dependency cache, and a full run announces no partial run scope or BUILT banner" do
+      @c.with_context do
+        Dir.chdir "temp_sensor" do
+          @c.ceedling_build_exec("gen:test_runner")
+
+          rebuild = @c.ceedling_build_exec("test:all")
+          expect(rebuild).to match(/^Compiling /)
+          expect(rebuild).to match(/^Linking /)
+          expect(rebuild).to match(/^Running /)
+          expect(rebuild).to match(/TESTED:\s+86/)
+          expect(rebuild).to match(/PASSED:\s+86/)
+          expect(rebuild).to_not match(/Generating mocks only/)
+          expect(rebuild).to_not match(/Generating mocks and test runners only/)
+          expect(rebuild).to_not match(/Building test executables only/)
+          expect(rebuild).to_not match(/Determining test sources only/)
+          expect(rebuild).to match(/Ceedling operations completed/)
+          expect(rebuild).to_not match(/MOCKS GENERATED/)
+          expect(rebuild).to_not match(/MOCKS & TEST RUNNERS GENERATED/)
+          expect(rebuild).to_not match(/TEST EXECUTABLES BUILT/)
+          expect(rebuild).to_not match(/TEST SOURCES DETERMINED/)
+        end
+      end
+    end
+  end
+end

data/spec/system/test_runner_system_include_spec.rb

@@ -36,53 +36,31 @@ TEST_RUNNER_SYSTEM_INCLUDE_C = <<~C
 C
 
 ceedling_system_tests do
-
-  before :all do
-    @c = SystemContext.new
-    @c.deploy_gem
-  end
-
-  after :all do
-    @c.done!
-  end
-
-  before { @proj_name = unique_proj_name("runner_sys_inc") }
+  include_context "a fresh ceedling gem project", "runner_sys_inc"
 
   describe "Deployed as a gem" do
     before do
-      @c.with_context do
-        @c.ceedling_appcmd_exec("new #{@proj_name}")
-      end
-    end
-
-    before do
-      @c.with_context do
-        Dir.chdir @proj_name do
-          File.write('test/test_runner_system_include.c', TEST_RUNNER_SYSTEM_INCLUDE_C)
-        end
-      end
+      in_project { File.write('test/test_runner_system_include.c', TEST_RUNNER_SYSTEM_INCLUDE_C) }
     end
 
     it "preserves a system include's directory component and angle brackets in the generated runner" do
-      @c.with_context do
-        Dir.chdir @proj_name do
-          output = @c.ceedling_build_exec("test:all")
-
-          expect(@c.last_exit_status).to eq(0)
-          expect(output).to match(/TESTED:\s+1/)
-          expect(output).to match(/PASSED:\s+1/)
-          expect(output).to match(/FAILED:\s+0/)
-
-          # The generated runner is what actually failed to compile in the reported
-          # issue -- assert on its content directly rather than just overall build
-          # success, since only the runner (not the test file itself) was affected.
-          runner_path = Dir.glob('build/test/runners/*_runner.c').first
-          expect(runner_path).not_to be_nil
-
-          runner_contents = File.read(runner_path)
-          expect(runner_contents).to include('#include <sys/stat.h>')
-          expect(runner_contents).not_to include('#include "stat.h"')
-        end
+      in_project do
+        output = @c.ceedling_build_exec("test:all")
+
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/TESTED:\s+1/)
+        expect(output).to match(/PASSED:\s+1/)
+        expect(output).to match(/FAILED:\s+0/)
+
+        # The generated runner is what actually failed to compile in the reported
+        # issue -- assert on its content directly rather than just overall build
+        # success, since only the runner (not the test file itself) was affected.
+        runner_path = Dir.glob('build/test/runners/*_runner.c').first
+        expect(runner_path).not_to be_nil
+
+        runner_contents = read_spec_file(runner_path)
+        expect(runner_contents).to include('#include <sys/stat.h>')
+        expect(runner_contents).not_to include('#include "stat.h"')
       end
     end
   end

data/spec/system/test_source_file_directive_spec.rb

@@ -0,0 +1,235 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'spec_system_helper'
+
+##
+## TEST_SOURCE_FILE() Build Directive
+## ====================================
+##
+## Everything TEST_SOURCE_FILE() itself is responsible for, collected in one
+## file: resolving a bare or path-disambiguated entry the same way any other
+## source lookup in the project resolves (test_source_file_directive_resolver.rb),
+## overriding the implicit header/source convention when an entry shares a
+## header's own basename, and -- the `-:` addition -- removing a named file
+## from a test's final compile/link list outright, regardless of how that
+## file got there in the first place.
+##
+## Path disambiguation (bare vs. path-qualified entries):
+##
+## TEST_SOURCE_FILE("...") names a source file to compile and link into a test
+## executable outside the usual #include-driven convention -- the documented use
+## case is a source file with no corresponding header at all. That name is
+## resolved through the same FileFinder/PathMatcher path as every other source
+## lookup in the project, so it was never given basename-only treatment to begin
+## with: a uniquely-named source resolves whether given bare or with a path,
+## while a source name that exists more than once in the project resolves to
+## the first candidate by :paths search-path order (with an ℹ️ NOTICE naming
+## what else matched) unless enough trailing path is given to identify exactly
+## one outright.
+##
+## Test assets: assets/fixtures/test_source_file_duplicate_basenames/
+##   - alpha/calc.c: calc_value() returning 111, no corresponding header
+##   - beta/calc.c: calc_value() returning 222, no corresponding header
+##   - test_calc_ambiguous.c: TEST_SOURCE_FILE("calc.c"), bare
+##   - test_calc_alpha.c: TEST_SOURCE_FILE("alpha/calc.c"), asserts 111
+##   - test_calc_beta.c: TEST_SOURCE_FILE("beta/calc.c"), asserts 222
+##
+## Overriding and removing (assets/fixtures/implicit_source_header_correspondence/):
+##
+## A test may mix TEST_SOURCE_FILE() with the implicit header/source convention.
+## When a directive entry shares a header's own basename, the directive is
+## authoritative outright -- its own resolution wins and the implicit
+## convention's independent resolution for that basename is skipped entirely,
+## rather than both landing in the source list (which would fail to link: two
+## same-named files each defining the same functions). This holds even when the
+## implicit resolution would already have been unambiguous on its own.
+##
+## A `-:`-prefixed entry goes further: it removes a named file from the final
+## compile/link list outright, independent of the basename-override mechanism
+## above and regardless of how the file arrived there -- the implicit
+## convention, a positive directive, or a Partial.
+##
+##   - alpha/dup.h, alpha/dup.c: declares/defines dup_value() returning 111
+##   - beta/dup.h, beta/dup.c: declares/defines dup_value() returning 222
+##   - gamma/dup_gamma.c: defines dup_value() returning 333, no header of its
+##     own -- only ever enters a build via a positive TEST_SOURCE_FILE() entry,
+##     and its basename shares no stem with "dup", so referencing it never
+##     engages the basename-stem override mechanism either
+##   - test_dup_override.c: #include "dup.h" (bare) + TEST_SOURCE_FILE("beta/dup.c"),
+##     asserts 222 -- the directive overrides what the bare #include would have
+##     implicitly resolved to on its own (alpha, 111)
+##   - test_dup_subtractive.c: #include "alpha/dup.h" (unambiguous, no other
+##     entry shares its "dup" stem) + TEST_SOURCE_FILE("-:alpha/dup.c") +
+##     TEST_SOURCE_FILE("gamma/dup_gamma.c"), asserts 333 -- the unambiguous
+##     implicit match is removed outright, independent of the basename-override
+##     mechanism above, and a differently-named file supplied in its place
+##   - test_dup_subtractive_noop.c: #include "alpha/dup.h" +
+##     TEST_SOURCE_FILE("-:beta/dup.c"), asserts 111 -- removing a real file
+##     that was never part of this test's own list changes nothing
+##
+## copy_duplicate_dup_pairs (the alpha/beta dup.{h,c} fixture pair used by the
+## "overriding and removing" scenarios below) is shared with
+## implicit_source_header_correspondence_disambiguation_spec.rb via
+## spec_system_helper.rb -- both files build scenarios around this same
+## same-basename ambiguity.
+##
+
+ceedling_system_tests do
+  include_context "a fresh ceedling gem project", "test_source_file_directive"
+
+  describe "Deployed as a gem" do
+
+    # Unique to this file -- the same-basename-but-no-header shape TEST_SOURCE_FILE()
+    # itself is documented for, distinct from copy_duplicate_dup_pairs's header+source
+    # pairs (which exercise TEST_SOURCE_FILE() overriding/removing an implicit match).
+    def copy_duplicate_calc_sources
+      in_project do
+        copy_fixture("test_source_file_duplicate_basenames/alpha/calc.c", 'src/alpha')
+        copy_fixture("test_source_file_duplicate_basenames/beta/calc.c", 'src/beta')
+      end
+    end
+
+    def copy_gamma_dup_replacement
+      in_project { copy_fixture("implicit_source_header_correspondence/gamma/dup_gamma.c", 'src/gamma') }
+    end
+
+    # =========================================================================
+    describe "A project with two same-named, header-less sources and a bare TEST_SOURCE_FILE() reference" do
+    # =========================================================================
+
+      before do
+        copy_duplicate_calc_sources
+        in_project { copy_fixture("test_source_file_duplicate_basenames/test_calc_ambiguous.c", 'test') }
+      end
+
+      it "resolves to the first candidate by search-path order, logging a NOTICE naming the other" do
+        in_project do
+          output = @c.ceedling_build_exec("test:all")
+          expect(@c.last_exit_status).to eq(0)
+          expect(output).to match(/Multiple files matched/)
+          expect(output).to match(/alpha[\/\\]calc\.c/)
+          expect(output).to match(/beta[\/\\]calc\.c/)
+          expect(output).to match(/TESTED:\s+1/)
+          expect(output).to match(/PASSED:\s+1/)
+        end
+      end
+
+    end
+
+    # =========================================================================
+    describe "A project with two same-named, header-less sources, each identified by a disambiguating TEST_SOURCE_FILE() path" do
+    # =========================================================================
+
+      before do
+        copy_duplicate_calc_sources
+        in_project do
+          copy_fixture("test_source_file_duplicate_basenames/test_calc_alpha.c", 'test')
+          copy_fixture("test_source_file_duplicate_basenames/test_calc_beta.c", 'test')
+        end
+      end
+
+      it "compiles, links, and passes both tests, each correctly linked against its own same-named source" do
+        in_project do
+          output = @c.ceedling_build_exec("test:all")
+          expect(@c.last_exit_status).to eq(0)
+          expect(output).to_not match(/Ambiguous/)
+          expect(output).to match(/TESTED:\s+2/)
+          expect(output).to match(/PASSED:\s+2/)
+        end
+      end
+
+    end
+
+    # =========================================================================
+    describe "A test file that both #includes a header and names a same-basename TEST_SOURCE_FILE()" do
+    # =========================================================================
+
+      before do
+        copy_duplicate_dup_pairs
+        in_project { copy_fixture("implicit_source_header_correspondence/test_dup_override.c", 'test') }
+      end
+
+      it "lets TEST_SOURCE_FILE() override the implicit convention's own resolution rather than compiling both same-named sources" do
+        in_project do
+          output = @c.ceedling_build_exec("test:all")
+          expect(@c.last_exit_status).to eq(0)
+          expect(output).to match(/TESTED:\s+1/)
+          expect(output).to match(/PASSED:\s+1/)
+
+          # The bare #include "dup.h" is still itself ambiguous (validate_header_includes
+          # is untouched by the override), so its own NOTICE still fires -- but the
+          # correctly-linked pass above already proves only beta/dup.c was ever compiled,
+          # not both. A duplicate-symbol link error would have failed the build otherwise.
+          expect(File.exist?('build/test/out/test_dup_override/beta/dup.o')).to be true
+          expect(File.exist?('build/test/out/test_dup_override/alpha/dup.o')).to be false
+
+          # A second, distinct NOTICE -- from extract_sources's own override, not the
+          # header-ambiguity NOTICE above -- names the winning TEST_SOURCE_FILE() entry
+          # and the #include it overrode.
+          expect(output).to match(/TEST_SOURCE_FILE\(\).*beta[\/\\]dup\.c/)
+          expect(output).to match(/dup\.h/)
+        end
+      end
+
+    end
+
+    # =========================================================================
+    describe "A test file that removes an unambiguously-matched implicit source and supplies a different one" do
+    # =========================================================================
+
+      before do
+        copy_duplicate_dup_pairs
+        copy_gamma_dup_replacement
+        in_project { copy_fixture("implicit_source_header_correspondence/test_dup_subtractive.c", 'test') }
+      end
+
+      it "never compiles the removed file, compiles and links the supplied one instead, and logs a NOTICE naming the removal" do
+        in_project do
+          output = @c.ceedling_build_exec("test:all")
+          expect(@c.last_exit_status).to eq(0)
+          expect(output).to match(/TESTED:\s+1/)
+          expect(output).to match(/PASSED:\s+1/)
+
+          expect(File.exist?('build/test/out/test_dup_subtractive/alpha/dup.o')).to be false
+          expect(File.exist?('build/test/out/test_dup_subtractive/gamma/dup_gamma.o')).to be true
+
+          expect(output).to match(/TEST_SOURCE_FILE\(.*-:alpha[\/\\]dup\.c.*\)/)
+          expect(output).to match(/removed/)
+          expect(output).to match(/alpha[\/\\]dup\.c/)
+        end
+      end
+
+    end
+
+    # =========================================================================
+    describe "A test file whose subtractive entry names a file never part of its own compile/link list" do
+    # =========================================================================
+
+      before do
+        copy_duplicate_dup_pairs
+        in_project { copy_fixture("implicit_source_header_correspondence/test_dup_subtractive_noop.c", 'test') }
+      end
+
+      it "builds and passes normally, logging no removal NOTICE" do
+        in_project do
+          output = @c.ceedling_build_exec("test:all")
+          expect(@c.last_exit_status).to eq(0)
+          expect(output).to match(/TESTED:\s+1/)
+          expect(output).to match(/PASSED:\s+1/)
+
+          expect(File.exist?('build/test/out/test_dup_subtractive_noop/alpha/dup.o')).to be true
+
+          expect(output).to_not match(/TEST_SOURCE_FILE\(.*removed/)
+        end
+      end
+
+    end
+
+  end
+
+end