ceedling 1.1.9 → 1.2.0

data/spec/units/plugins/sanitize_findings_spec.rb

@@ -0,0 +1,69 @@
+# =========================================================================
+#   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_helper'
+
+$: << File.expand_path('../../../../plugins/sanitize/lib', __FILE__)
+require 'sanitize_findings'
+
+# The reports are real output: GCC 14 on Linux and Apple Clang 15 on macOS
+describe SanitizeFindings do
+  def report(name)
+    File.read( File.expand_path( "../../../support/fixtures/sanitizer_reports/#{name}.txt", __FILE__ ) )
+  end
+
+  def finding(name)
+    findings = described_class.parse( report( name ) )
+    expect(findings.length).to eq( 1 )
+    return findings.first
+  end
+
+  it 'finds nothing in output without a sanitizer report' do
+    expect(described_class.parse( "test_a.c:4:test_x:PASS\n1 Tests 0 Failures 0 Ignored\n" )).to eq( [] )
+  end
+
+  it 'reads an ASan error and its location from GCC' do
+    found = finding( 'gcc_heap' )
+
+    expect(found.to_h.slice( :sanitizer, :kind, :file, :line )).to eq( sanitizer: :address, kind: 'heap-buffer-overflow', file: '/x/heap.c', line: 3 )
+    expect(found.message).to start_with( 'heap-buffer-overflow on address' )
+    expect(found.text).to include( 'SUMMARY: AddressSanitizer: heap-buffer-overflow' )
+  end
+
+  it 'reads an ASan error and its location from Clang' do
+    found = finding( 'clang_asan_heap' )
+    expect(found.to_h.slice( :sanitizer, :kind, :file, :line )).to eq( sanitizer: :address, kind: 'heap-buffer-overflow', file: 'heap.c', line: 3 )
+  end
+
+  # A leak's location is the first frame in the program, past the sanitizer's own malloc
+  it 'reads a leak and where it was allocated' do
+    found = finding( 'gcc_leak' )
+
+    expect(found.to_h.slice( :sanitizer, :kind, :file, :line )).to eq( sanitizer: :leak, kind: 'memory-leak', file: '/x/leak.c', line: 4 )
+    expect(found.message).to eq( 'Direct leak of 32 byte(s) in 1 object(s)' )
+  end
+
+  it 'reads a UBSan runtime error and its location from GCC and from Clang' do
+    [ 'gcc_ubsan_shift', 'clang_ubsan_shift' ].each do |name|
+      found = finding( name )
+      expect(found.to_h.slice( :sanitizer, :kind, :file, :line, :column )).to eq( sanitizer: :undefined, kind: 'undefined-behavior', file: 'ub.c', line: 3, column: 67 )
+      expect(found.message).to eq( "left shift of 128 by 24 places cannot be represented in type 'int'" )
+    end
+  end
+
+  # ASan and UBSan together catch a null dereference as UBSan's null load
+  it 'reads a null pointer load as a UBSan runtime error' do
+    found = finding( 'gcc_segv' )
+    expect(found.to_h.slice( :sanitizer, :file, :line, :message )).to eq( sanitizer: :undefined, file: 'segv.c', line: 2, message: "load of null pointer of type 'uint32_t'" )
+  end
+
+  # Recover mode keeps running after each finding
+  it 'reads each of several reports' do
+    findings = described_class.parse( report( 'gcc_ubsan_shift' ) + report( 'gcc_leak' ) )
+    expect(findings.map( &:sanitizer )).to eq( [:undefined, :leak] )
+  end
+end

data/spec/units/plugins/sanitize_records_spec.rb

@@ -0,0 +1,114 @@
+# =========================================================================
+#   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_helper'
+require 'ceedling/constants'
+
+PROJECT_BUILD_ARTIFACTS_ROOT = 'build/artifacts' unless defined?(PROJECT_BUILD_ARTIFACTS_ROOT)
+
+$: << File.expand_path('../../../../plugins/sanitize/lib', __FILE__)
+require 'sanitize_findings'
+require 'sanitize_records'
+
+describe SanitizeRecords do
+  let(:file_wrapper) { double('file_wrapper', mkdir: nil, write: nil) }
+  let(:loginator)    { double('loginator', log: nil) }
+  let(:records)      { described_class.new( file_wrapper: file_wrapper, loginator: loginator, reports: [] ) }
+  let(:log)          { described_class.log_filepath( :sanitize, 'test_a' ) }
+
+  def finding(line, text: "report at line #{line}\n")
+    return SanitizeFindings::Finding.new( sanitizer: :address, kind: 'heap-buffer-overflow', file: 'test/test_a.c', line: line, message: 'overflow', text: text )
+  end
+
+  # A crashed test's reruns reproduce the main run's finding, and reach findings it never did
+  describe '#record' do
+    # A crash's notice names its finding already
+    it 'logs all but the finding a crash explanation names' do
+      records.record( :sanitize, 'test_a', [finding( 9 ), finding( 14 )], explained: finding( 9 ) )
+
+      expect(loginator).to have_received(:log).once
+      expect(loginator).to have_received(:log).with( /line 14|test_a\.c:14/, anything, anything )
+      expect(file_wrapper).to have_received(:write).once
+      expect(records.failure_message).to eq( 'Sanitizers found 2 problems in 1 test' )
+    end
+
+    it 'counts a finding recorded again only once' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+
+      expect(records.failure_message).to eq( 'Sanitizers found 1 problem in 1 test' )
+      expect(loginator).to have_received(:log).once
+    end
+
+    it 'counts each distinct finding' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.record( :sanitize, 'test_a', [finding( 14 )] )
+
+      expect(records.failure_message).to eq( 'Sanitizers found 2 problems in 1 test' )
+    end
+
+    # A build's first report for a test replaces the last build's log
+    it 'starts a test\'s log with its first report and adds each new one after it' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.record( :sanitize, 'test_a', [finding( 9 ), finding( 14 )] )
+
+      expect(file_wrapper).to have_received(:write).with( log, "report at line 9\n", 'w' ).ordered
+      expect(file_wrapper).to have_received(:write).with( log, "\nreport at line 14\n", 'a' ).ordered
+    end
+
+    it 'writes nothing more for a finding already recorded' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+
+      expect(file_wrapper).to have_received(:write).once
+    end
+  end
+  # The build failure names the reports written, as other plugins' failures do
+  describe '#failure_message' do
+    def report(extension, write_empty)
+      return double( extension, extension: extension, write_empty?: write_empty, render: '' )
+    end
+
+    let(:reports) { [report( 'log', false ), report( 'json', true )] }
+    let(:records) { described_class.new( file_wrapper: file_wrapper, loginator: loginator, reports: reports ) }
+    let(:dir)     { File.join( SANITIZE_ARTIFACTS_PATH, 'sanitize' ) }
+
+    it 'names the reports written in their directory' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.write_reports( :sanitize )
+
+      expect(records.failure_message).to eq( "Sanitizers found 1 problem in 1 test. See the reports in #{dir}: sanitize.log, sanitize.json." )
+    end
+
+    it 'names each directory\'s reports for each instrumented build' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.record( :test, 'test_a', [finding( 9 )] )
+      records.write_reports( :sanitize )
+      records.write_reports( :test )
+
+      test_dir = File.join( SANITIZE_ARTIFACTS_PATH, 'test' )
+      expect(records.failure_message).to eq(
+        "Sanitizers found 2 problems in 1 test. See the reports in #{dir}: sanitize.log, sanitize.json; #{test_dir}: sanitize.log, sanitize.json."
+      )
+    end
+
+    it 'names a report rewritten for the same build once' do
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      2.times { records.write_reports( :sanitize ) }
+
+      expect(records.failure_message).to eq( "Sanitizers found 1 problem in 1 test. See the reports in #{dir}: sanitize.log, sanitize.json." )
+    end
+
+    it 'names no reports when none are written' do
+      records = described_class.new( file_wrapper: file_wrapper, loginator: loginator, reports: [] )
+      records.record( :sanitize, 'test_a', [finding( 9 )] )
+      records.write_reports( :sanitize )
+
+      expect(records.failure_message).to eq( 'Sanitizers found 1 problem in 1 test' )
+    end
+  end
+end

data/spec/units/plugins/sanitize_reports_spec.rb

@@ -0,0 +1,84 @@
+# =========================================================================
+#   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_helper'
+require 'json'
+require 'ceedling/exceptions'
+
+$: << File.expand_path('../../../../plugins/sanitize/lib', __FILE__)
+require 'sanitize_findings'
+require 'sanitize_reports'
+
+describe SanitizeReports do
+  let(:finding) do
+    SanitizeFindings::Finding.new(
+      sanitizer: :address, kind: 'heap-buffer-overflow', file: 'src/buffer.c', line: 12, column: nil,
+      message: 'heap-buffer-overflow on address 0x502000000020', text: "==13==ERROR: AddressSanitizer: heap-buffer-overflow\n"
+    )
+  end
+  let(:records) { [{ test: 'test_buffer', finding: finding }] }
+
+  def report(name)
+    return described_class.load( [name], version: '1.2.0' ).first
+  end
+
+  describe '.load' do
+    it 'loads the text report when none is configured' do
+      expect(described_class.load( [], version: '1.2.0' ).map( &:extension )).to eq( ['log'] )
+    end
+
+    it 'loads each configured report once, by symbol or string in any letter case' do
+      expect(described_class.load( ['JSON', :sarif, :json], version: '1.2.0' ).map( &:extension )).to eq( ['json', 'sarif'] )
+    end
+
+    it 'rejects an unknown report, listing the choices' do
+      expect { described_class.load( ['html'], version: '1.2.0' ) }.to raise_error(
+        CeedlingException, /:sanitize ↳ :reports entry `html` is not a report. Choose from :text, :json, :sarif./
+      )
+    end
+  end
+
+  it 'writes each finding\'s report as the sanitizer printed it, under its test' do
+    text = report( :text ).render( :sanitize, records )
+
+    expect(text).to include( "test_buffer: AddressSanitizer heap-buffer-overflow at src/buffer.c:12\n" )
+    expect(text).to include( '==13==ERROR: AddressSanitizer: heap-buffer-overflow' )
+  end
+
+  # UBSan names every finding undefined behavior, so its message says what happened
+  it 'heads a UBSan finding with its runtime error' do
+    ub = SanitizeFindings::Finding.new( sanitizer: :undefined, kind: 'undefined-behavior', file: 'src/shift.c', line: 3, column: 67,
+                                        message: 'left shift of 128 by 24 places cannot be represented in type \'int\'', text: '' )
+    expect(described_class.headline( ub )).to eq( "UndefinedBehaviorSanitizer left shift of 128 by 24 places cannot be represented in type 'int' at src/shift.c:3" )
+  end
+
+  it 'writes each finding\'s fields as JSON, with the build context' do
+    json = JSON.parse( report( :json ).render( :sanitize, records ) )
+
+    expect(json['context']).to eq( 'sanitize' )
+    expect(json['findings'].first).to include( 'test' => 'test_buffer', 'sanitizer' => 'address', 'kind' => 'heap-buffer-overflow', 'file' => 'src/buffer.c', 'line' => 12 )
+  end
+
+  it 'writes each finding as a SARIF error result, its rule the sanitizer and kind' do
+    sarif  = JSON.parse( report( :sarif ).render( :sanitize, records ) )
+    result = sarif['runs'].first['results'].first
+
+    expect(sarif['version']).to eq( '2.1.0' )
+    expect(result).to include( 'ruleId' => 'address/heap-buffer-overflow', 'level' => 'error' )
+    expect(result['locations'].first['physicalLocation']).to eq(
+      'artifactLocation' => { 'uri' => 'src/buffer.c', 'uriBaseId' => '%SRCROOT%' }, 'region' => { 'startLine' => 12 }
+    )
+    expect(sarif['runs'].first['tool']['driver']['rules']).to eq( [{ 'id' => 'address/heap-buffer-overflow' }] )
+  end
+
+  # A code scanning service reads an empty run as earlier findings being gone
+  it 'writes the structured reports for a build without findings, and no text log' do
+    expect(report( :text ).write_empty?).to eq( false )
+    expect(report( :json ).write_empty?).to eq( true )
+    expect(JSON.parse( report( :sarif ).render( :sanitize, [] ) )['runs'].first['results']).to eq( [] )
+  end
+end

data/spec/units/plugins/sanitize_spec.rb

@@ -0,0 +1,300 @@
+# =========================================================================
+#   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_helper'
+require 'shellwords'
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+require 'ceedling/plugins/plugin'
+
+PROJECT_BUILD_ROOT           = 'build'           unless defined?(PROJECT_BUILD_ROOT)
+PROJECT_BUILD_ARTIFACTS_ROOT = 'build/artifacts' unless defined?(PROJECT_BUILD_ARTIFACTS_ROOT)
+EXTENSION_ASSEMBLY           = /\.s\z/           unless defined?(EXTENSION_ASSEMBLY)
+
+TOOLS_SANITIZE_FIXTURE = {
+  :executable => 'env',
+  :name       => 'default_sanitize_fixture',
+  :optional   => true,
+  :arguments  => []
+}.freeze unless defined?(TOOLS_SANITIZE_FIXTURE)
+
+$: << File.expand_path('../../../../plugins/sanitize/lib', __FILE__)
+require 'sanitize'
+
+describe Sanitize do
+  def report(name)
+    File.read( File.expand_path( "../../../support/fixtures/sanitizer_reports/#{name}.txt", __FILE__ ) )
+  end
+
+  let(:defaults) do
+    { sanitizers: ['address', 'undefined'], recover: false, detect_leaks: true, test_builds: false, fail_build: true,
+      reports: [], runtime_options: {}, flags: {} }
+  end
+
+  let(:loginator)      { double('loginator', log: nil) }
+  let(:dependinator)   { double('dependinator', register: nil) }
+  let(:file_wrapper)   { double('file_wrapper', write: nil, mkdir: nil) }
+  let(:plugin_manager) { double('plugin_manager', register_build_failure: nil) }
+  let(:tracker)        { double('rake_invocation_tracker', invoked?: true) }
+  let(:tool_validator) { double('tool_validator', validate: nil) }
+  let(:system_wrapper) { double('system_wrapper', windows?: false, macos?: false) }
+  let(:plugin_reportinator) { double('plugin_reportinator', assemble_test_results: {}, run_test_results_report: nil, test_results_floor_verbosity: 3) }
+
+  def build(overrides = {})
+    configurator = double( 'configurator', plugins_display_raw_test_results: true )
+    setupinator  = double( 'setupinator', config_hash: { sanitize: defaults.merge( overrides ) } )
+    system_objects = {
+      configurator: configurator, setupinator: setupinator, loginator: loginator, dependinator: dependinator,
+      file_wrapper: file_wrapper, plugin_manager: plugin_manager, rake_invocation_tracker: tracker,
+      tool_validator: tool_validator, system_wrapper: system_wrapper, plugin_reportinator: plugin_reportinator,
+      reportinator: double( 'reportinator', generate_progress: 'PROGRESS' )
+    }
+    return described_class.new( system_objects, 'sanitize', '/plugins/sanitize' )
+  end
+
+  describe '#setup' do
+    it 'rejects a :test_builds setting that is not a boolean' do
+      expect { build( test_builds: 'yes' ) }.to raise_error( CeedlingException, /:sanitize ↳ :test_builds must be TRUE or FALSE/ )
+    end
+
+    it 'rejects an unknown sanitizer' do
+      expect { build( sanitizers: ['thread'] ) }.to raise_error( CeedlingException, /:sanitize ↳ :sanitizers entry `thread`/ )
+    end
+  end
+
+  describe '#validate_environment!' do
+    it 'stops on Windows, which the sanitizers do not support here' do
+      allow(system_wrapper).to receive(:windows?).and_return( true )
+      expect { build.validate_environment! }.to raise_error( CeedlingException, /not supported on Windows/ )
+    end
+
+    it 'checks the fixture tool' do
+      build.validate_environment!
+      expect(tool_validator).to have_received(:validate).with( tool: TOOLS_SANITIZE_FIXTURE, boom: true )
+    end
+  end
+
+  # An instrumented test: build runs through no sanitize: task, so the build itself checks
+  describe '#pre_test_build' do
+    it 'checks the platform and tools for an instrumented test: build' do
+      allow(system_wrapper).to receive(:windows?).and_return( true )
+      expect { build( test_builds: true ).pre_test_build( TEST_SYM, 0 ) }.to raise_error( CeedlingException, /not supported on Windows/ )
+    end
+
+    it 'leaves an uninstrumented test: build unchecked' do
+      allow(system_wrapper).to receive(:windows?).and_return( true )
+      expect { build.pre_test_build( TEST_SYM, 0 ) }.to_not raise_error
+    end
+
+    it 'checks only once' do
+      sanitize = build( test_builds: true )
+      sanitize.pre_test_build( TEST_SYM, 0 )
+      sanitize.pre_test_build( SANITIZE_SYM, 0 )
+
+      expect(tool_validator).to have_received(:validate).once
+    end
+  end
+
+  # Flags go only where the plugin instruments, so other plugins' builds stay clean
+  describe 'compile and link flags' do
+    def compile(sanitize, context, source: 'src/buffer.c')
+      arg_hash = { context: context, flags: ['-g'], source: source, object: 'build/buffer.o' }
+      sanitize.pre_test_compile_register( arg_hash )
+      return arg_hash[:flags]
+    end
+
+    it 'instruments a sanitize: build\'s compiles and links' do
+      sanitize = build
+      arg_hash = { context: SANITIZE_SYM, flags: [], executable: 'build/test_a.out' }
+      sanitize.pre_test_link_register( arg_hash )
+
+      expect(compile( sanitize, SANITIZE_SYM )).to include( '-fsanitize=address,undefined', '-fno-sanitize-recover=all' )
+      expect(arg_hash[:flags]).to eq( ['-fsanitize=address,undefined'] )
+    end
+
+    it 'leaves ordinary test: builds alone unless asked to instrument them' do
+      expect(compile( build, :test )).to eq( ['-g'] )
+      expect(compile( build( test_builds: true ), :test )).to include( '-fsanitize=address,undefined' )
+    end
+
+    it 'never instruments another plugin\'s build' do
+      sanitize = build( test_builds: true )
+      [:gcov, :bullseye, :valgrind].each { |context| expect(compile( sanitize, context )).to eq( ['-g'] ) }
+    end
+
+    it 'leaves assembly sources alone' do
+      expect(compile( build, SANITIZE_SYM, source: 'src/startup.s' )).to eq( ['-g'] )
+    end
+
+    it 'records its settings with each object, so changing them rebuilds it' do
+      compile( build, SANITIZE_SYM )
+      expect(dependinator).to have_received(:register).with( 'build/buffer.o', meta: { sanitize: hash_including( sanitizers: ['address', 'undefined'] ) } )
+    end
+
+    # Reporting and failing the build change nothing a build or test run produces
+    it 'leaves out the settings that change only reporting' do
+      compile( build( reports: [:sarif], fail_build: false ), SANITIZE_SYM )
+      expect(dependinator).to have_received(:register).with(
+        'build/buffer.o', meta: { sanitize: { sanitizers: ['address', 'undefined'], recover: false, detect_leaks: true, runtime_options: {}, flags: {} } }
+      )
+    end
+  end
+
+  describe '#pre_test_fixture_register' do
+    def register(sanitize, tool: { name: 'default_test_fixture', executable: '${1}', arguments: [] }, context: SANITIZE_SYM)
+      arg_hash = { context: context, tool: tool, target: 'build/test_a.out', test_name: 'test_a' }
+      sanitize.pre_test_fixture_register( arg_hash )
+      return arg_hash[:tool]
+    end
+
+    it 'runs the test executable with each sanitizer\'s options set for it alone' do
+      tool = register( build )
+
+      expect(tool[:executable]).to eq( 'env' )
+      expect(tool[:arguments]).to eq( [
+        "ASAN_OPTIONS='halt_on_error=1:exitcode=0:detect_leaks=1'",
+        "UBSAN_OPTIONS='halt_on_error=1:print_stacktrace=1:exitcode=0'",
+        '${1}'
+      ] )
+    end
+
+    # The fixture command runs in a shell, which must pass an option value through intact. The
+    # plugin, like this example, needs a POSIX shell, which Windows lacks.
+    it 'quotes each option so a shell passes its value through as written',
+       skip: (RUBY_PLATFORM.match?( /mswin|mingw/ ) ? 'needs a POSIX shell, as the plugin does' : false) do
+      tool  = register( build( runtime_options: { asan: ["suppressions=/my dir/$HOME/it's \"ok\"`date`"] } ) )
+      value = `sh -c #{Shellwords.escape( "env #{tool[:arguments].first} sh -c 'printf %s \"$ASAN_OPTIONS\"'" )}`
+
+      expect(value).to end_with( ":suppressions=/my dir/$HOME/it's \"ok\"`date`" )
+    end
+
+    # A backtrace rerun then runs with the same options as the main run
+    it 'asks for backtrace reruns to run through it' do
+      expect(register( build )[:backtrace_rerun]).to eq( true )
+    end
+
+    it 'wraps a project\'s own fixture tool, its executable and arguments after the options' do
+      tool = register( build, tool: { name: 'sim', executable: 'simulator', arguments: ['--quiet', '${1}'] } )
+      expect(tool[:arguments].last( 3 )).to eq( ['simulator', '--quiet', '${1}'] )
+    end
+
+    it 'leaves another build\'s fixture tool alone' do
+      original = { name: 'default_test_fixture', executable: '${1}', arguments: [] }
+      expect(register( build, tool: original, context: :test )).to equal( original )
+    end
+  end
+
+  describe 'findings' do
+    def execute(sanitize, stderr, context: SANITIZE_SYM)
+      sanitize.post_test_fixture_execute(
+        { context: context, test_name: 'test_a', result_file: 'build/sanitize/results/test_a.pass', shell_result: { stderr: stderr } }
+      )
+    end
+
+    it 'writes a test\'s sanitizer report to its own log and logs each finding' do
+      execute( build, report( 'gcc_heap' ) )
+
+      expect(file_wrapper).to have_received(:write).with( File.join( SANITIZE_ARTIFACTS_PATH, 'sanitize', 'test_a.log' ), /heap-buffer-overflow/, 'w' )
+      expect(loginator).to have_received(:log).with( /test_a: AddressSanitizer heap-buffer-overflow at \/x\/heap\.c:3/, Verbosity::ERRORS, LogLabels::ERROR )
+    end
+
+    it 'writes nothing for a test without findings' do
+      execute( build, '' )
+      expect(file_wrapper).not_to have_received(:write)
+    end
+
+    # A test reported from the last build's results was not run
+    it 'reads nothing for a test whose cached results were reported' do
+      sanitize = build
+      expect { sanitize.post_test_fixture_execute( { context: SANITIZE_SYM, test_name: 'test_a', result_file: 'x.pass', shell_result: nil } ) }.to_not raise_error
+    end
+
+    it 'names a crash\'s finding and its log' do
+      sanitize = build
+      arg_hash = { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: report( 'gcc_heap' ) }, explanation: nil }
+      sanitize.explain_test_crash( arg_hash )
+
+      log = File.join( SANITIZE_ARTIFACTS_PATH, 'sanitize', 'test_a.log' )
+      expect(arg_hash[:explanation_heading]).to eq( 'was stopped by a sanitizer finding' )
+      expect(arg_hash[:explanation]).to eq( 'AddressSanitizer heap-buffer-overflow at /x/heap.c:3' )
+      expect(arg_hash[:explanation_details]).to eq( ["Boom log: #{log}"] )
+    end
+
+    # A test case after the one that halted the main run runs only in its rerun
+    it 'counts the finding it names, so a rerun-only finding fails the build' do
+      sanitize = build
+      sanitize.explain_test_crash( { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: report( 'gcc_heap' ) }, explanation: nil } )
+      sanitize.post_build( 0 )
+
+      expect(plugin_manager).to have_received(:register_build_failure).with( SANITIZE_SYM, /Sanitizers found 1 problem in 1 test/ )
+    end
+
+    it 'logs no separate line for the finding a crash notice names' do
+      sanitize = build
+      sanitize.explain_test_crash( { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: report( 'gcc_heap' ) }, explanation: nil, crash_notice: true } )
+      expect(loginator).not_to have_received(:log).with( /test_a: AddressSanitizer/, anything, anything )
+    end
+
+    # A backtrace rerun's explanation reaches no crash notice
+    it 'logs the finding a backtrace rerun\'s explanation names' do
+      sanitize = build
+      sanitize.explain_test_crash( { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: report( 'gcc_heap' ) }, explanation: nil, crash_notice: false } )
+      expect(loginator).to have_received(:log).with( /test_a: AddressSanitizer/, anything, anything )
+    end
+
+    it 'counts a finding once when both the main run and its explanation report it' do
+      sanitize = build
+      sanitize.explain_test_crash( { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: report( 'gcc_heap' ) }, explanation: nil } )
+      sanitize.post_test_fixture_execute( { context: SANITIZE_SYM, test_name: 'test_a', result_file: 'x.pass', shell_result: { stderr: report( 'gcc_heap' ) } } )
+      sanitize.post_build( 0 )
+
+      expect(plugin_manager).to have_received(:register_build_failure).with( SANITIZE_SYM, /Sanitizers found 1 problem in 1 test/ )
+    end
+
+    it 'names nothing for a crash without a sanitizer report' do
+      arg_hash = { context: SANITIZE_SYM, test_name: 'test_a', shell_result: { stderr: 'Segmentation fault' }, explanation: nil }
+      build.explain_test_crash( arg_hash )
+
+      expect(arg_hash[:explanation]).to be_nil
+    end
+  end
+
+  describe '#post_build' do
+    def build_after(stderr, **overrides)
+      sanitize = build( overrides )
+      sanitize.post_test_fixture_execute( { context: SANITIZE_SYM, test_name: 'test_a', result_file: 'x.pass', shell_result: { stderr: stderr } } )
+      sanitize.post_build( 0 )
+      return sanitize
+    end
+
+    it 'fails the build when a sanitizer found something' do
+      build_after( report( 'gcc_leak' ) )
+      expect(plugin_manager).to have_received(:register_build_failure).with( SANITIZE_SYM, /Sanitizers found 1 problem in 1 test/ )
+    end
+
+    it 'leaves the build alone when asked not to fail it' do
+      build_after( report( 'gcc_leak' ), fail_build: false )
+      expect(plugin_manager).not_to have_received(:register_build_failure)
+    end
+
+    it 'leaves a build without findings alone' do
+      build_after( '' )
+      expect(plugin_manager).not_to have_received(:register_build_failure)
+    end
+
+    # The build failure summary names the reports, so the findings aren't logged again
+    it 'logs no tally after the build' do
+      build_after( report( 'gcc_leak' ), reports: [:json] )
+      expect(loginator).not_to have_received(:log).with( /Sanitizer (findings|reports):/, anything )
+    end
+
+    it 'writes each configured report for each instrumented build' do
+      build_after( report( 'gcc_leak' ), reports: [:json] )
+      expect(file_wrapper).to have_received(:write).with( File.join( SANITIZE_ARTIFACTS_PATH, 'sanitize', 'sanitize.json' ), /"memory-leak"/ )
+    end
+  end
+end

data/spec/units/plugins/tests_reporter_spec.rb

@@ -0,0 +1,89 @@
+# =========================================================================
+#   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_helper'
+require 'stringio'
+require 'ceedling/config/config_walkinator'
+
+$: << File.expand_path('../../../../plugins/report_tests_log_factory/lib', __FILE__)
+require 'tests_reporter'
+
+describe TestsReporter do
+  describe '#initialize' do
+    it "falls back to '<handle>.report' so a custom subclass that forgets to call setup still has a usable filename" do
+      reporter = described_class.new(handle: :foo_bar)
+      expect(reporter.filename).to eq('foo_bar.report')
+    end
+  end
+
+  describe '#setup' do
+    it 'uses a configured filename override in preference to the default' do
+      config_walkinator = double('config_walkinator')
+      allow(config_walkinator).to receive(:fetch_value)
+        .with(:filename, hash: { filename: 'custom.xml' }, default: 'default.xml')
+        .and_return(['custom.xml', true])
+
+      reporter = described_class.new(handle: :foo)
+      reporter.config_walkinator = config_walkinator
+      reporter.config = { filename: 'custom.xml' }
+      reporter.setup(default_filename: 'default.xml')
+
+      expect(reporter.filename).to eq('custom.xml')
+    end
+  end
+
+  describe '#header, #body, #footer' do
+    it 'are no-ops by default, so a subclass need only override what it actually renders' do
+      reporter = described_class.new(handle: :foo)
+      stream = StringIO.new
+
+      expect {
+        reporter.header(stream: stream, name: 'x', results: {}, duration_s: nil)
+        reporter.body(stream: stream, name: 'x', results: {}, duration_s: nil)
+        reporter.footer(stream: stream, name: 'x', results: {}, duration_s: nil)
+      }.not_to raise_error
+
+      expect(stream.string).to be_empty
+    end
+  end
+
+  # A report reaches disk only through the injected file layer
+  describe '#write' do
+    it 'renders header/body/footer into one buffer and hands the complete contents to file_wrapper.write' do
+      reporter_class = Class.new(described_class) do
+        def header(stream:, name:, results:, duration_s:) stream << 'H' end
+        def body(stream:, name:, results:, duration_s:) stream << 'B' end
+        def footer(stream:, name:, results:, duration_s:) stream << 'F' end
+      end
+      reporter = reporter_class.new(handle: :foo)
+      file_wrapper = double('file_wrapper')
+      reporter.file_wrapper = file_wrapper
+
+      expect(file_wrapper).to receive(:write).with('some/path.txt', 'HBF')
+
+      reporter.write(name: 'x', filepath: 'some/path.txt', results: {}, duration_s: nil)
+    end
+  end
+
+  # A custom subclass reads its own configuration beneath its report's name
+  describe '#fetch_config_value (private)' do
+    let(:reporter) do
+      reporter = described_class.new(handle: :fancy)
+      reporter.config_walkinator = ConfigWalkinator.new
+      reporter.config = { standardize: { names: true, filters: ['/^Foo/'] } }
+      reporter
+    end
+
+    it 'returns the value at the end of a key walk' do
+      expect(reporter.send(:fetch_config_value, :standardize, :filters)).to eq(['/^Foo/'])
+    end
+
+    it 'returns nil for keys that do not exist' do
+      expect(reporter.send(:fetch_config_value, :does, :not, :exist)).to be_nil
+    end
+  end
+end