ceedling 1.0.1 → 1.1.0

data/spec/system/support/cppcheck_common_test_cases.rb

@@ -0,0 +1,98 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require_relative 'cppcheck_helpers'
+
+module CppcheckCommonTestCases
+  include CppcheckHelpers
+
+  def project_build_tasks_plugins_help_for_cppcheck
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck
+        output = @c.ceedling_appcmd_exec("help")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/ceedling cppcheck:\*/i)
+        expect(output).to match(/ceedling cppcheck:all/i)
+        expect(output).to match(/ceedling files:cppcheck/i)
+      end
+    end
+  end
+
+  def can_run_cppcheck_on_whole_project
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck(reports: [:text])
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+
+        output = @c.ceedling_build_exec("cppcheck:all")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/Creating Cppcheck text report/i)
+      end
+    end
+  end
+
+  def can_run_cppcheck_on_single_file
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck(reports: [:text])
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+
+        output = @c.ceedling_build_exec("cppcheck:example_file.c")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/Running Cppcheck on file/i)
+        expect(output).to match(/example_file\.c/i)
+      end
+    end
+  end
+
+  def can_list_cppcheck_suppression_files
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck
+        output = @c.ceedling_build_exec("files:cppcheck")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/Cppcheck suppression files/i)
+      end
+    end
+  end
+
+  def can_create_xml_report
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck(reports: [:xml])
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+
+        output = @c.ceedling_build_exec("cppcheck:all")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/Creating Cppcheck xml report/i)
+        expect(File.exist?('build/artifacts/cppcheck/CppcheckReport.xml')).to eq(true)
+        expect(File.size('build/artifacts/cppcheck/CppcheckReport.xml')).to be > 0
+      end
+    end
+  end
+
+  def can_create_text_report
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_cppcheck(reports: [:text])
+        FileUtils.cp test_asset_path("example_file.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file.c"), 'src/'
+
+        output = @c.ceedling_build_exec("cppcheck:all")
+        expect(@c.last_exit_status).to eq(0)
+        expect(output).to match(/Creating Cppcheck text report/i)
+        expect(File.exist?('build/artifacts/cppcheck/CppcheckReport.txt')).to eq(true)
+        expect(File.size('build/artifacts/cppcheck/CppcheckReport.txt')).to be > 0
+      end
+    end
+  end
+
+end

data/spec/system/support/cppcheck_helpers.rb

@@ -0,0 +1,27 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'fileutils'
+
+module CppcheckHelpers
+
+  def cppcheck_available?
+    begin
+      `cppcheck --version 2>&1`
+      $?.exitstatus == 0
+    rescue
+      false
+    end
+  end
+
+  def prep_project_yml_for_cppcheck(reports: [:text])
+    FileUtils.cp test_asset_path("project.yml"), "project.yml"
+    @c.uncomment_project_yml_option_for_test("- cppcheck")
+    @c.merge_project_yml_for_test({cppcheck: {reports: reports}})
+  end
+
+end

data/spec/{gcov/gcov_test_cases_spec.rb → system/support/gcov_common_test_cases.rb}

@@ -1,88 +1,16 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'fileutils'
-require 'tmpdir'
-require 'yaml'
-require 'spec_system_helper'
-require 'pp'
+require_relative 'gcov_helpers'
 
+module GcovCommonTestCases
+  include GcovHelpers
 
-module GcovTestCases
-
-  def determine_reports_to_test
-    @gcov_reports = []
-
-    begin
-      `gcovr --version 2>&1`
-      @gcov_reports << :gcovr if $?.exitstatus == 0
-    rescue
-      puts "No GCOVR exec to test against"
-    end
-
-    begin
-      `reportgenerator --version 2>&1`
-      @gcov_reports << :reportgenerator if $?.exitstatus == 0
-    rescue
-      puts "No ReportGenerator exec to test against"
-    end
-  end
-
-  def prep_project_yml_for_coverage
-    FileUtils.cp test_asset_path("project.yml"), "project.yml"
-    @c.uncomment_project_yml_option_for_test("- gcov")
-    @c.comment_project_yml_option_for_test("- gcovr") unless @gcov_reports.include? :gcovr
-    @c.uncomment_project_yml_option_for_test("- ReportGenerator") if @gcov_reports.include? :reportgenerator
-  end
-
-  def _add_gcov_section_in_project(project_file_path, name, values)
-    project_file_contents = File.readlines(project_file_path)
-    name_index = project_file_contents.index(":gcov:\n")
-
-    if name_index.nil?
-      # Something wrong with project.yml file, no project section?
-      return
-    end
-
-    project_file_contents.insert(name_index + 1, "  :#{name}:\n")
-    values.each.with_index(2) do |value, index|
-      project_file_contents.insert(name_index + index, "    - #{value}\n")
-    end
-
-    File.open(project_file_path, "w+") do |f|
-      f.puts(project_file_contents)
-    end
-  end
-  
-  def _add_gcov_option_in_project(project_file_path, option, value)
-    project_file_contents = File.readlines(project_file_path)
-    option_index = project_file_contents.index(":gcov:\n")
-
-    if option_index.nil?
-      # Something wrong with project.yml file, no project section?
-      return
-    end
-
-    project_file_contents.insert(option_index + 1, "  :#{option}: #{value}\n")
-  
-    File.open(project_file_path, "w+") do |f|
-      f.puts(project_file_contents)
-    end
-  end
-
-  def add_gcov_section(name, values)
-    _add_gcov_section_in_project("project.yml", name, values)
-  end
-
-  def add_gcov_option(option, value)
-    _add_gcov_option_in_project("project.yml", option, value)
-  end
-
-  def can_test_projects_with_gcov_with_success
+  def project_with_gcov_success
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
@@ -100,7 +28,7 @@ module GcovTestCases
     end
   end
 
-  def can_test_projects_with_gcov_with_fail
+  def project_with_gcov_fail
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
@@ -119,7 +47,7 @@ module GcovTestCases
   end
 
   # TODO: Restore this test when the :abort_on_uncovered option is restored in the Gcov plugin
-  # def can_test_projects_with_gcov_with_fail_because_of_uncovered_files
+  # def project_with_gcov_fail_because_of_uncovered_files
   #   @c.with_context do
   #     Dir.chdir @proj_name do
   #       prep_project_yml_for_coverage
@@ -140,7 +68,7 @@ module GcovTestCases
   # end
 
   # TODO: Restore this test when the :abort_on_uncovered option is restored in the Gcov plugin
-  # def can_test_projects_with_gcov_with_success_because_of_ignore_uncovered_list
+  # def project_with_gcov_success_because_of_ignore_uncovered_list
   #   @c.with_context do
   #     Dir.chdir @proj_name do
   #       prep_project_yml_for_coverage
@@ -163,7 +91,7 @@ module GcovTestCases
   # end
 
   # TODO: Restore this test when the :abort_on_uncovered option is restored in the Gcov plugin
-  # def can_test_projects_with_gcov_with_success_because_of_ignore_uncovered_list_with_globs
+  # def project_with_gcov_success_because_of_ignore_uncovered_list_with_globs
   #   @c.with_context do
   #     Dir.chdir @proj_name do
   #       prep_project_yml_for_coverage
@@ -186,8 +114,7 @@ module GcovTestCases
   #   end
   # end
 
-
-  def can_test_projects_with_gcov_with_compile_error
+  def project_with_gcov_compile_error
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
@@ -202,7 +129,7 @@ module GcovTestCases
     end
   end
 
-  def can_fetch_project_help_for_gcov
+  def help_tasks_include_gcov
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
@@ -214,7 +141,7 @@ module GcovTestCases
     end
   end
 
-  def can_create_html_reports
+  def create_html_report
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
@@ -224,68 +151,162 @@ module GcovTestCases
 
         output = `bundle exec ruby -S ceedling gcov:all 2>&1`
         if @gcov_reports.include? :gcovr
-          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr'\.\.\./)
+          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/gcovr/GcovCoverageResults.html')).to eq true
         end
         if @gcov_reports.include? :modulegenerator
-          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator'\.\.\./)
+          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/ReportGenerator/summary.htm')).to eq true
         end
       end
     end
   end
 
-  def can_create_html_reports_from_crashing_test_runner_with_enabled_debug_for_test_cases_not_causing_crash
+  def gcov_console_report_with_system_header
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        FileUtils.cp test_asset_path("example_file_with_stdio.h"), 'src/'
+        FileUtils.cp test_asset_path("example_file_with_stdio.c"), 'src/'
+        FileUtils.cp test_asset_path("test_example_file_with_stdio.c"), 'test/'
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        expect($?.exitstatus).to match(0)
+        # Console summary must report coverage for the source file, not a warning.
+        # When <stdio.h> is included, gcov may list a system header (e.g. _stdio.h)
+        # as the first File entry — the fix ensures the correct source is found.
+        expect(output).to match(/example_file_with_stdio\.c \| Lines executed:/)
+        expect(output).not_to match(/Found no coverage results for.*example_file_with_stdio/)
+      end
+    end
+  end
+
+  def gcov_console_report_with_partial
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+
+        asset_base = test_asset_path("tests_with_fallback_conditionals")
+        FileUtils.cp "#{asset_base}/src/conditional_module.h", 'src/'
+        FileUtils.cp "#{asset_base}/src/conditional_module.c", 'src/'
+        FileUtils.cp "#{asset_base}/src/optional_dep.h",       'src/'
+        FileUtils.cp "#{asset_base}/test/test_conditionals.c", 'test/'
+
+        @c.merge_project_yml_for_test({ :project => { :use_partials => true } })
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        expect($?.exitstatus).to match(0)
+        # Coverage must be reported for the Partial (gcov references the original
+        # module via #line remapping); no spurious "Found no coverage results" warning.
+        expect(output).to match(/Lines executed:/)
+        expect(output).not_to match(/Found no coverage results for.*conditional_module/)
+      end
+    end
+  end
+
+  def create_html_report_with_gcovr_config_file_overrides_default
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
         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.c"), 'test/'
+        FileUtils.cp test_asset_path("test_example_file_success.c"), 'test/'
+
+        # A second test file covering the same source creates duplicate function
+        # coverage entries: Ceedling builds one executable per test file, and both
+        # link against example_file.c, producing two sets of .gcda coverage data
+        # for the same functions.
+        File.write('test/test_example_file_2.c', <<~C)
+          #include "unity.h"
+          #include "example_file.h"
+
+          void setUp(void) {}
+          void tearDown(void) {}
+
+          void test_difference_between_two_numbers(void)
+          {
+            TEST_ASSERT_EQUAL_INT(0, difference_between_numbers(1, 1));
+          }
+        C
+
+        # 'strict' causes gcovr to exit non-zero when the same function appears in
+        # multiple test executables' coverage data. Ceedling's default is
+        # 'merge-use-line-max' (set in defaults.yml), which it injects as a CLI
+        # arg that would override this config file setting without the fix.
+        File.write('gcovr.cfg', [
+          "[gcovr]",
+          "merge-mode-functions = strict"
+        ].join("\n"))
+
+        @c.merge_project_yml_for_test({
+          :gcov => {
+            :gcovr => {
+              :config_file => 'gcovr.cfg'
+            }
+          }
+        })
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        if @gcov_reports.include? :gcovr
+          # Config file honored (fix applied): strict mode exits non-zero on duplicate functions.
+          # Config file overridden by Ceedling CLI (bug): merge-use-line-max exits 0.
+          expect($?.exitstatus).not_to eq(0)
+        end
+      end
+    end
+  end
+
+  def create_html_report_from_crashing_test_with_backtrace_enabled
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        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/'
 
         @c.merge_project_yml_for_test({:project => { :use_backtrace => :gdb }})
 
         output = `bundle exec ruby -S ceedling gcov:all 2>&1`
         expect($?.exitstatus).to match(1) # Ceedling should exit with error because of failed test due to crash
         expect(output).to match(/crashed/i)
-        expect(output).to match(/Unit test failures./)
-        expect(File.exist?('./build/gcov/results/test_example_file_crash.fail'))
-        output_rd = File.read('./build/gcov/results/test_example_file_crash.fail')
-        expect(output_rd =~ /test_add_numbers_will_fail \(\) at test\/test_example_file_crash.c\:14/ )
+        expect(output).to match(/Unit test failures/)
+        expect(File.exist?('./build/gcov/results/test_example_file_crash_sigsegv.fail'))
+        output_rd = File.read('./build/gcov/results/test_example_file_crash_sigsegv.fail')
+        expect(output_rd =~ /test_add_numbers_will_fail \(\) at test\/test_example_file_crash_sigsegv.c\:\d+/ )
         expect(output).to match(/TESTED:\s+2/)
         expect(output).to match(/PASSED:\s+(?:0|1)/)
         expect(output).to match(/FAILED:\s+(?:1|2)/)
         expect(output).to match(/IGNORED:\s+0/)
         expect(output).to match(/example_file.c \| Lines executed:5?0.00% of 4/)
         if @gcov_reports.include? :gcovr
-          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr'\.\.\./)
+          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/gcovr/GcovCoverageResults.html')).to eq true
         end
         if @gcov_reports.include? :modulegenerator
-          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator'\.\.\./)
+          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/ReportGenerator/summary.htm')).to eq true
         end
       end
     end
   end
 
-  def can_create_html_reports_from_crashing_test_runner_with_enabled_debug_with_zero_coverage
+  def create_html_report_with_zero_coverage_after_crashing_test_and_backtrace
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
         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.c"), 'test/'
+        FileUtils.cp test_asset_path("test_example_file_crash_sigsegv.c"), 'test/'
 
         @c.merge_project_yml_for_test({:project => { :use_backtrace => :gdb }})
 
         output = `bundle exec ruby -S ceedling gcov:all --exclude_test_case=test_add_numbers_adds_numbers 2>&1`
         expect($?.exitstatus).to match(1) # Ceedling should exit with error because of failed test due to crash
         expect(output).to match(/Test Case Crashed/i)
-        expect(output).to match(/Unit test failures./)
-        expect(File.exist?('./build/gcov/results/test_example_file_crash.fail'))
-        output_rd = File.read('./build/gcov/results/test_example_file_crash.fail')
-        expect(output_rd =~ /test_add_numbers_will_fail \(\) at test\/test_example_file_crash.c\:14/ )
+        expect(output).to match(/Unit test failures/)
+        expect(File.exist?('./build/gcov/results/test_example_file_crash_sigsegv.fail'))
+        output_rd = File.read('./build/gcov/results/test_example_file_crash_sigsegv.fail')
+        expect(output_rd =~ /test_add_numbers_will_fail \(\) at test\/test_example_file_crash_sigsegv.c\:\d+/ )
         expect(output).to match(/TESTED:\s+1/)
         expect(output).to match(/PASSED:\s+0/)
         expect(output).to match(/FAILED:\s+1/)
@@ -293,37 +314,37 @@ module GcovTestCases
         expect(output).to match(/example_file.c \| Lines executed:0.00% of 4/)
 
         if @gcov_reports.include? :gcovr
-          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr'\.\.\./)
+          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/gcovr/GcovCoverageResults.html')).to eq true
         end
         if @gcov_reports.include? :modulegenerator
-          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator'\.\.\./)
+          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/ReportGenerator/summary.htm')).to eq true
         end
       end
     end
   end
 
-  def can_create_html_reports_from_test_runner_with_enabled_debug_with_100_coverage_when_excluding_crashing_test_case
+  def create_html_report_100_coverage_excluding_crashing_test_case
     @c.with_context do
       Dir.chdir @proj_name do
         prep_project_yml_for_coverage
         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.c"), 'test/'
+        FileUtils.cp test_asset_path("test_example_file_crash_sigsegv.c"), 'test/'
 
         add_test_case = "\nvoid test_difference_between_two_numbers(void)\n"\
                         "{\n" \
                         "  TEST_ASSERT_EQUAL_INT(0, difference_between_numbers(1,1));\n" \
                         "}\n"
-        
-        updated_test_file = File.read('test/test_example_file_crash.c').split("\n")
+
+        updated_test_file = File.read('test/test_example_file_crash_sigsegv.c').split("\n")
         updated_test_file.insert(updated_test_file.length(), add_test_case)
-        File.write('test/test_example_file_crash.c', updated_test_file.join("\n"), mode: 'w')
+        File.write('test/test_example_file_crash_sigsegv.c', updated_test_file.join("\n"), mode: 'w')
 
         output = `bundle exec ruby -S ceedling gcov:all --exclude_test_case=test_add_numbers_will_fail 2>&1`
         expect($?.exitstatus).to match(0)
-        expect(File.exist?('./build/gcov/results/test_example_file_crash.pass'))
+        expect(File.exist?('./build/gcov/results/test_example_file_crash_sigsegv.pass'))
         expect(output).to match(/TESTED:\s+2/)
         expect(output).to match(/PASSED:\s+2/)
         expect(output).to match(/FAILED:\s+0/)
@@ -331,14 +352,106 @@ module GcovTestCases
         expect(output).to match(/example_file.c \| Lines executed:100.00% of 4/)
 
         if @gcov_reports.include? :gcovr
-          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr'\.\.\./)
+          expect(output).to match(/Generating HTML coverage report in 'build\/artifacts\/gcov\/gcovr\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/gcovr/GcovCoverageResults.html')).to eq true
         end
         if @gcov_reports.include? :modulegenerator
-          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator'\.\.\./)
+          expect(output).to match(/Generating HtmlBasic coverage report in 'build\/artifacts\/gcov\/ReportGenerator\/'\.\.\./)
           expect(File.exist?('build/artifacts/gcov/ReportGenerator/summary.htm')).to eq true
         end
       end
     end
   end
+
+  def project_with_gcov_untested_sources_ignore
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        add_gcov_option("untested_sources", ":ignore")
+        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/'
+        # Untested — no test references this source file.
+        FileUtils.cp test_asset_path("uncovered_example_file.c"), 'src/'
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        expect($?.exitstatus).to match(0)
+        expect(output).not_to match(/Untested Source Files/)
+        expect(output).not_to match(/Processing Untested Sources/)
+        expect(output).not_to match(/uncovered_example_file/)
+      end
+    end
+  end
+
+  def project_with_gcov_untested_sources_list
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        add_gcov_option("untested_sources", ":list")
+        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/'
+        # Untested — no test references this source file.
+        FileUtils.cp test_asset_path("uncovered_example_file.c"), 'src/'
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        expect($?.exitstatus).to match(0)
+        # Immediate warning-level filepath listing (no compilation attempted).
+        expect(output).to match(/Untested.+not.+coverage report/)
+        expect(output).to match(/uncovered_example_file\.c/)
+        expect(output).not_to match(/Compiling with coverage.*uncovered_example_file/)
+        # Post-build console summary still lists it (basename-keyed).
+        expect(output).to match(/Untested Source Files/)
+        expect(output).to match(/uncovered_example_file\.c \| No tests executed: 0% coverage/)
+      end
+    end
+  end
+
+  def project_with_gcov_untested_sources_compile_failure
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        add_gcov_option("untested_sources", ":compile")
+        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/'
+
+        # Untested source with a syntax error — fails to compile regardless of
+        # any :defines/:flags, deliberately triggering the guidance notice.
+        File.write('src/broken_uncovered_file.c', <<~C)
+          int broken_uncovered_function(int a, int b) {
+            return a + b // Missing semicolon and closing brace: guaranteed compile error.
+        C
+
+        output = `bundle exec ruby -S ceedling gcov:all 2>&1`
+        expect($?.exitstatus).not_to eq(0) # Fail-fast: compile failure fails the build
+        expect(output).to match(/Compiling.+with coverage failed/)
+        expect(output).to match(/:untested_sources.*:compile/)
+        # Avoid unicode character matching in log matching, since some shells may not support them.
+        expect(output).to match(/Switch :gcov.+:untested_sources to :list/)
+        expect(output).to match(/Switch :gcov.+:untested_sources to :ignore/)
+      end
+    end
+  end
+
+  def project_with_gcov_untested_sources_standalone_task
+    @c.with_context do
+      Dir.chdir @proj_name do
+        prep_project_yml_for_coverage
+        add_gcov_option("untested_sources", ":compile")
+        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/'
+        # Untested — no test references this source file.
+        FileUtils.cp test_asset_path("uncovered_example_file.c"), 'src/'
+
+        # Run the standalone task directly — no prior `gcov:all` in this invocation,
+        # so no test fixture is ever built or executed.
+        output = `bundle exec ruby -S ceedling gcov:untested_sources 2>&1`
+        expect($?.exitstatus).to match(0)
+        expect(output).not_to match(/TESTED:\s+\d/) # No test build/run occurred
+        expect(File.exist?('build/gcov/out/uncovered_example_file.o')).to eq true
+      end
+    end
+  end
 end