ceedling 1.1.9 → 1.2.0

data/spec/integration/analysis_tool_output_spec.rb

@@ -0,0 +1,204 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Pins the Valgrind and Cppcheck plugins' output parsing against what those tools
+# really emit, rather than against hand-written sample text.
+#
+# The unit specs cover the same parsing with synthetic strings. They cannot catch a
+# real tool changing its output shape, and they cannot produce the shapes that are
+# awkward to fake correctly. The two cases that matter most here are a Valgrind run
+# whose child process yields a second ERROR SUMMARY, and Cppcheck's own XML severity
+# attributes across both of its XML schema versions.
+#
+# Shells out to real valgrind, cppcheck, and gcc. Each block skips where its tool is
+# unavailable, so this file contributes whatever the host can actually verify.
+
+require 'spec_helper'
+require 'spec_integration_helper'
+
+def tool_present?(command)
+  `#{command}`
+  $?.exitstatus == 0
+rescue
+  false
+end
+
+VALGRIND_PRESENT = tool_present?('valgrind --version 2>&1') unless defined?(VALGRIND_PRESENT)
+CPPCHECK_PRESENT = tool_present?('cppcheck --version 2>&1') unless defined?(CPPCHECK_PRESENT)
+GCC_PRESENT      = tool_present?('gcc --version 2>&1')      unless defined?(GCC_PRESENT)
+
+describe 'Analysis tool output parsing (integration)' do
+
+  # Mirrors Valgrind#count_errors' text-log branch.
+  def sum_error_summaries(contents)
+    contents.scan( /ERROR SUMMARY:\s+(\d+) errors?/ ).flatten.map( &:to_i ).sum
+  end
+
+  # Mirrors Valgrind#count_errors' XML branch.
+  def count_xml_errors(contents)
+    contents.scan( /<error\b/ ).length
+  end
+
+  # Mirrors Cppcheck#tally_findings.
+  def tally_severities(contents)
+    counts = Hash.new(0)
+    contents.scan( /<error\b[^>]*\bseverity="([^"]+)"/ ) { |m| counts[m[0]] += 1 }
+    counts
+  end
+
+  context 'Valgrind', skip: ((VALGRIND_PRESENT && GCC_PRESENT) ? false : 'requires valgrind and gcc') do
+    # One uninitialised read plus two leaks.
+    let(:leaky_source) do
+      <<~C
+        #include <stdlib.h>
+        #include <stdio.h>
+        int main(void) {
+          char *p = malloc(32);
+          int *u = malloc(sizeof(int));
+          printf("%d\\n", *u);
+          p[0] = 1;
+          return 0;
+        }
+      C
+    end
+
+    # Parent and child each leak, so each reports its own ERROR SUMMARY.
+    let(:forking_source) do
+      <<~C
+        #include <unistd.h>
+        #include <stdlib.h>
+        #include <sys/wait.h>
+        int main(void) {
+          char *a = malloc(16); a[0] = 1;
+          pid_t pid = fork();
+          if (pid == 0) { char *c = malloc(32); c[0] = 1; _exit(0); }
+          wait(NULL);
+          return 0;
+        }
+      C
+    end
+
+    def run_valgrind(dir, source_name, *extra_args)
+      binary = File.join(dir, 'prog')
+      system("gcc -g -O0 #{File.join(dir, source_name)} -o #{binary}", out: File::NULL, err: File::NULL)
+      log = File.join(dir, 'out.log')
+      args = ['--leak-check=full', '--show-leak-kinds=all', '--errors-for-leak-kinds=all'] + extra_args
+      system("valgrind --log-file=\"#{log}\" #{args.join(' ')} #{binary}", out: File::NULL, err: File::NULL)
+      log
+    end
+
+    it 'counts the errors a single-process run reports' do
+      with_source_tree({ 'leak.c' => leaky_source }) do |dir|
+        contents = File.read( run_valgrind(dir, 'leak.c') )
+
+        expect(contents).to match(/ERROR SUMMARY:/)
+        expect(sum_error_summaries(contents)).to be > 0
+      end
+    end
+
+    # Valgrind writes one summary per traced process. Reading only the first
+    # undercounts, which is what the plugin used to do.
+    it 'sums every ERROR SUMMARY when a traced child reports its own' do
+      with_source_tree({ 'forker.c' => forking_source }) do |dir|
+        contents = File.read( run_valgrind(dir, 'forker.c', '--trace-children=yes') )
+        summaries = contents.scan( /ERROR SUMMARY:\s+(\d+) errors?/ ).flatten.map( &:to_i )
+
+        expect(summaries.length).to be > 1
+        expect(sum_error_summaries(contents)).to eq(summaries.sum)
+        expect(sum_error_summaries(contents)).to be > summaries.first
+      end
+    end
+
+    # `--xml=yes` leaves the text log empty, so XML is the only place errors appear
+    # once it is enabled. This is why the plugin switches counting source.
+    it 'writes errors only to XML when XML output is enabled' do
+      with_source_tree({ 'leak.c' => leaky_source }) do |dir|
+        binary = File.join(dir, 'prog')
+        system("gcc -g -O0 #{File.join(dir, 'leak.c')} -o #{binary}", out: File::NULL, err: File::NULL)
+        log = File.join(dir, 'out.log')
+        xml = File.join(dir, 'out.xml')
+        system(
+          "valgrind --xml=yes --xml-file=\"#{xml}\" --log-file=\"#{log}\" " \
+          "--leak-check=full --show-leak-kinds=all --errors-for-leak-kinds=all #{binary}",
+          out: File::NULL, err: File::NULL
+        )
+
+        expect(File.exist?(xml)).to be true
+        expect(count_xml_errors(File.read(xml))).to be > 0
+        # Nothing for the text branch to find, hence the switch.
+        expect(sum_error_summaries(File.read(log))).to eq(0)
+      end
+    end
+  end
+
+  context 'Cppcheck', skip: (CPPCHECK_PRESENT ? false : 'requires cppcheck') do
+    # Cppcheck reports the double free at error severity.
+    let(:defective_source) do
+      <<~C
+        #include <stdlib.h>
+        int defect(void) {
+          int *p = malloc(sizeof(int));
+          if (p == NULL) { return -1; }
+          *p = 7;
+          int v = *p;
+          free(p);
+          free(p);
+          return v;
+        }
+      C
+    end
+
+    # Returns the report path, or nil if Cppcheck did not actually produce one.
+    #
+    # A `cppcheck` found on PATH is not proof it can run. Some environments
+    # (Windows CI runner images among them) preinstall a Cppcheck shim that
+    # cannot locate its own cfg/std.cfg directory, so a run silently produces no
+    # output. Verifying the report exists, rather than trusting the shell
+    # command's exit status, catches that failure the same way a hung or
+    # partially-written file would.
+    def run_cppcheck(dir, xml_version)
+      output = File.join(dir, "report#{xml_version}.xml")
+      system(
+        "cppcheck --enable=all --xml --xml-version=#{xml_version} " \
+        "--output-file=\"#{output}\" #{File.join(dir, 'defect.c')}",
+        out: File::NULL, err: File::NULL
+      )
+      return output if File.exist?(output) && File.size(output) > 0
+      nil
+    end
+
+    it 'tallies severities from a real XML version 2 report' do
+      with_source_tree({ 'defect.c' => defective_source }) do |dir|
+        output = run_cppcheck(dir, 2)
+        skip 'this Cppcheck could not complete a real analysis run' if output.nil?
+
+        expect(tally_severities( File.read(output) )['error']).to be > 0
+      end
+    end
+
+    # Both schema versions carry the same severity attribute, so one parser serves
+    # both. Version 3 is rejected outright by older Cppcheck, which is why the
+    # plugin defaults to 2.
+    it 'tallies severities from a real XML version 3 report where supported' do
+      with_source_tree({ 'defect.c' => defective_source }) do |dir|
+        output = run_cppcheck(dir, 3)
+        skip 'this Cppcheck does not support XML version 3, or could not complete a real analysis run' if output.nil?
+
+        expect(tally_severities( File.read(output) )['error']).to be > 0
+      end
+    end
+
+    it 'reports an empty tally for a clean source' do
+      with_source_tree({ 'defect.c' => "int clean(int a) { return a + 1; }\n" }) do |dir|
+        output = run_cppcheck(dir, 2)
+        skip 'this Cppcheck could not complete a real analysis run' if output.nil?
+
+        expect(tally_severities( File.read(output) )['error']).to eq(0)
+      end
+    end
+  end
+end

data/spec/{units/c_extractor/c_extractor_integration_spec.rb → integration/c_extractor_composition_spec.rb}

@@ -14,9 +14,13 @@ require 'ceedling/c_extractor/c_extractor_preprocessing'
 require 'ceedling/c_extractor/c_extractor_definitions'
 
 ##
-## These integration tests exercise the composition of all CExtractor* objects
-## in extracting features from C source code.
-## Other unit tests exhaustively exerise individual methods, including of CExtractor itself.
+## These tests exercise the composition of all CExtractor* objects -- real,
+## fully-wired collaborators, not mocked -- extracting features from real C source
+## code. Migrated here from spec/units/c_extractor/ (its former name,
+## c_extractor_integration_spec.rb, already said what it was; the directory now
+## conveys the tier instead of the filename needing to). spec/units/c_extractor/
+## still holds exhaustive per-method unit coverage of each CExtractor* class in
+## isolation, including of CExtractor itself.
 ##
 describe CExtractor do
 
@@ -38,7 +42,8 @@ describe CExtractor do
         # Bare double (no :partials_max_extraction_length stub) so #respond_to? is
         # false and CExtractor falls back to its own built-in default buffer length.
         configurator:              double('Configurator'),
-        loginator:                 double('Loginator').as_null_object
+        loginator:                 double('Loginator').as_null_object,
+        file_wrapper:              double('FileWrapper').as_null_object
       }
     )
     extractor.setup()
@@ -1007,22 +1012,196 @@ describe CExtractor do
       expect(plain.decorators).to eq([])
     end
 
-    it "normalizes a preprocessor-inserted space before ## in a backslash-continued macro definition" do
-      file_contents = <<~CONTENTS
-      #define MODULE_DEV_TYPE_CB(dev_type)      \\
-          void MODULE_TrigCbDev ##dev_type(void) \\
-          {                                     \\
-              MODULE_CommonTrigCb();            \\
-          }
+    # A bare, top-level, semicolon-less macro invocation (an x-macro call expanding to
+    # a full function definition once the macro itself is applied) has no leading '#',
+    # no trailing ';', and no trailing '{' -- directives-only preprocessing never
+    # expands it, so every extractor below sees it as literal, unexpanded text. Left
+    # unhandled, whichever extractor's own forward scan reaches it next either
+    # swallows it as a bogus prefix (the variable-declaration catch-all) or actively
+    # misinterprets a later, unrelated '{' as its own body (the function-signature
+    # scanners), silently losing whatever real content that brace belonged to (GH #1294).
+    context "bare macro invocations" do
+      it "should extract a bare macro-invocation-as-statement without corrupting the following variable declaration (GH #1294)" do
+        file_contents = <<~CONTENTS
+        #define MODULE_DEV_TYPE_CB(dev_type)      \\
+            void MODULE_TrigCbDev##dev_type(void) \\
+            {                                     \\
+                MODULE_CommonTrigCb();            \\
+            }
 
-      static AlertEntry_t s_alert_table[ALERT_MANAGER_MAX_ALERTS];
-      CONTENTS
+        MODULE_DEV_TYPE_CB(0)
+
+        static AlertEntry_t s_alert_table[ALERT_MANAGER_MAX_ALERTS];
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.macro_invocations[0].text).to eq 'MODULE_DEV_TYPE_CB(0)'
+
+        expect(contents.variable_declarations.length).to eq 1
+        var = contents.variable_declarations[0]
+        expect(var.name).to eq 's_alert_table'
+        expect(var.type).to eq 'AlertEntry_t'
+        expect(var.decorators).to eq ['static']
+
+        # macro definition, then the bare invocation, then the variable -- in that order
+        texts = contents.element_sequence.map { |item| item.is_a?(CExtractorTypes::CVariableDeclaration) ? item.name : item.text }
+        expect(texts).to eq [
+          "#define MODULE_DEV_TYPE_CB(dev_type)      \\\n    void MODULE_TrigCbDev##dev_type(void) \\\n    {                                     \\\n        MODULE_CommonTrigCb();            \\\n    }",
+          'MODULE_DEV_TYPE_CB(0)',
+          's_alert_table'
+        ]
+      end
+
+      # Same reporter-shape fixture as above, but with a stray space before ## on the
+      # continuation line -- simulating the exact cross-toolchain divergence issue #1294
+      # originally reported (a real preprocessor's own reconstruction of this macro
+      # text, not something Ceedling's extraction ever added on its own). Proves the
+      # whitespace-canonicalization fix engages correctly end to end, through the real
+      # backslash-continuation handling, not just in the isolated scanner unit tests.
+      it "normalizes a preprocessor-inserted space before ## in a backslash-continued macro definition" do
+        file_contents = <<~CONTENTS
+        #define MODULE_DEV_TYPE_CB(dev_type)      \\
+            void MODULE_TrigCbDev ##dev_type(void) \\
+            {                                     \\
+                MODULE_CommonTrigCb();            \\
+            }
 
-      contents = extract_from.call(file_contents)
+        MODULE_DEV_TYPE_CB(0)
+
+        static AlertEntry_t s_alert_table[ALERT_MANAGER_MAX_ALERTS];
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_definitions.length).to eq 1
+        expect(contents.macro_definitions[0].text).to include('MODULE_TrigCbDev##dev_type')
+        expect(contents.macro_definitions[0].text).not_to include('MODULE_TrigCbDev ##dev_type')
+      end
+
+      it "should extract a bare macro invocation without losing the typedef that follows it" do
+        file_contents = <<~CONTENTS
+        #define FOO(x) void bar##x(void) { }
+        FOO(0)
+        typedef struct { int a; } Baz_t;
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
 
-      expect(contents.macro_definitions.length).to eq 1
-      expect(contents.macro_definitions[0].text).to include('MODULE_TrigCbDev##dev_type')
-      expect(contents.macro_definitions[0].text).not_to include('MODULE_TrigCbDev ##dev_type')
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.macro_invocations[0].text).to eq 'FOO(0)'
+
+        expect(contents.type_definitions.length).to eq 1
+        expect(contents.type_definitions[0].text).to include('Baz_t')
+      end
+
+      it "should extract a bare macro invocation without losing the aggregate definition that follows it" do
+        file_contents = <<~CONTENTS
+        #define FOO(x) void bar##x(void) { }
+        FOO(0)
+        struct Baz { int a; };
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.aggregate_definitions.length).to eq 1
+        expect(contents.aggregate_definitions[0].text).to include('struct Baz')
+      end
+
+      it "should extract a bare macro invocation without losing the real function definition that follows it" do
+        file_contents = <<~CONTENTS
+        #define FOO(x) void bar##x(void) { }
+        FOO(0)
+        void RealFunc(void) { }
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.function_definitions.length).to eq 1
+        expect(contents.function_definitions[0].name).to eq 'RealFunc'
+      end
+
+      it "should extract a bare macro invocation without losing the real function declaration that follows it" do
+        file_contents = <<~CONTENTS
+        #define FOO(x) void bar##x(void) { }
+        FOO(0)
+        void RealFunc(void);
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.function_declarations.length).to eq 1
+        expect(contents.function_declarations[0].name).to eq 'RealFunc'
+      end
+
+      it "should extract multiple consecutive bare macro invocations, each individually, without losing what follows" do
+        file_contents = <<~CONTENTS
+        #define FOO(x) void bar##x(void) { }
+        FOO(0)
+        FOO(1)
+        FOO(2)
+        static int x;
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.macro_invocations.map(&:text)).to eq ['FOO(0)', 'FOO(1)', 'FOO(2)']
+
+        expect(contents.variable_declarations.length).to eq 1
+        expect(contents.variable_declarations[0].name).to eq 'x'
+        expect(contents.variable_declarations[0].decorators).to eq ['static']
+      end
+
+      # A bare invocation with genuinely nothing after it (not even a newline) is
+      # indistinguishable, at extraction time, from "not enough of the file has been
+      # read yet" -- unterminated trailing content is already silently dropped for
+      # every other feature type in this codebase (a file ending in `int x` with no
+      # trailing ';' is dropped the same way), so this is a pre-existing, accepted
+      # limitation this fix doesn't change, not a new gap it introduces.
+      it "silently drops a bare macro invocation trailing at the very end of the file with nothing after it, consistent with every other unterminated trailing construct" do
+        file_contents = "static int x;\n#define FOO(dev) void bar##dev(void) { }\nFOO(0)"
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.variable_declarations.length).to eq 1
+        expect(contents.variable_declarations[0].name).to eq 'x'
+
+        expect(contents.macro_invocations.length).to eq 0
+      end
+
+      it "still silently drops a trailing bare macro invocation even with a trailing newline after it -- a newline alone doesn't resolve the chunk-boundary ambiguity" do
+        file_contents = <<~CONTENTS
+        static int x;
+        #define FOO(dev) void bar##dev(void) { }
+        FOO(0)
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.variable_declarations.length).to eq 1
+        expect(contents.variable_declarations[0].name).to eq 'x'
+
+        expect(contents.macro_invocations.length).to eq 0
+      end
+
+      it "extracts a bare macro invocation followed by further real (non-deadspace) content" do
+        file_contents = <<~CONTENTS
+        static int x;
+        #define FOO(dev) void bar##dev(void) { }
+        FOO(0)
+        static int y;
+        CONTENTS
+
+        contents = extract_from.call(file_contents)
+
+        expect(contents.variable_declarations.map(&:name)).to eq ['x', 'y']
+        expect(contents.macro_invocations.length).to eq 1
+        expect(contents.macro_invocations[0].text).to eq 'FOO(0)'
+      end
     end
 
   end

data/spec/integration/command_hooks_plugin_spec.rb

@@ -0,0 +1,152 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# The Command Hooks plugin with Ceedling's real tool validation and execution. Each hook
+# runs a small Ruby script that records the argument the hook hands it as `${1}`.
+#
+# Each hook receives the argument hash Ceedling's core builds for that build step (see
+# the plugin_manager calls in lib/ceedling), so a hook reading the wrong key records an
+# empty argument.
+
+require 'spec_helper'
+require 'tmpdir'
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+require 'ceedling/plugins/plugin'
+require_relative '../support/integration/configurator_integration_helper'
+
+$LOAD_PATH.unshift( File.expand_path( '../../plugins/command_hooks/lib', __dir__ ) )
+
+require 'command_hooks'
+
+describe 'Command Hooks plugin (integration)' do
+  include ConfiguratorIntegrationHelpers
+
+  # Writes each argument it receives to <hook>.txt, one per line
+  COMMAND_HOOKS_RECORDER = <<~RUBY
+    File.write( "\#{ARGV.shift}.txt", ARGV.join( "\\n" ) )
+  RUBY
+
+  def recording_hook(name)
+    return { executable: 'ruby', arguments: ['record.rb', name.to_s, '"${1}"'] }
+  end
+
+  def plugin_for(config)
+    objects = configurator_objects( quiet_loginator )
+    objects[:setupinator]     = double( 'setupinator', config_hash: config )
+    objects[:config_walkinator] ||= ConfigWalkinator.new
+    return CommandHooks.new( objects, 'command_hooks', '/plugins/command_hooks' )
+  end
+
+  def in_project
+    Dir.mktmpdir( 'command_hooks' ) do |root|
+      Dir.chdir( root ) do
+        File.write( 'record.rb', COMMAND_HOOKS_RECORDER )
+        yield
+      end
+    end
+  end
+
+  def recorded(hook)
+    return File.exist?( "#{hook}.txt" ) ? File.read( "#{hook}.txt" ) : nil
+  end
+
+  # Each hook, the argument hash or values the core passes it, and the `${1}` it promises
+  COMMAND_HOOKS_CORE_CALLS = {
+    pre_mock_preprocess:       [{ header_file: 'src/adc.h', test: 'test_adc' },                    'src/adc.h'],
+    post_mock_preprocess:      [{ header_file: 'src/adc.h', test: 'test_adc' },                    'src/adc.h'],
+    pre_test_preprocess:       [{ test_file: 'test/test_adc.c', test: 'test_adc' },                'test/test_adc.c'],
+    post_test_preprocess:      [{ test_file: 'test/test_adc.c', test: 'test_adc' },                'test/test_adc.c'],
+    pre_mock_generate:         [{ header_file: 'src/adc.h', context: :test, output_path: 'mocks' }, 'src/adc.h'],
+    post_mock_generate:        [{ header_file: 'src/adc.h', context: :test, output_path: 'mocks' }, 'src/adc.h'],
+    pre_runner_generate:       [{ context: :test, test_file: 'test/test_adc.c', input_file: 'test/test_adc.c', runner_file: 'runners/test_adc_runner.c' }, 'test/test_adc.c'],
+    post_runner_generate:      [{ context: :test, test_file: 'test/test_adc.c', input_file: 'test/test_adc.c', runner_file: 'runners/test_adc_runner.c' }, 'runners/test_adc_runner.c'],
+    pre_compile_execute:       [{ context: :test, source: 'src/adc.c', object: 'out/adc.o' },     'src/adc.c'],
+    post_compile_execute:      [{ context: :test, source: 'src/adc.c', object: 'out/adc.o' },     'src/adc.c'],
+    pre_link_execute:          [{ context: :test, executable: 'out/test_adc.out' },               'out/test_adc.out'],
+    post_link_execute:         [{ context: :test, executable: 'out/test_adc.out' },               'out/test_adc.out'],
+    pre_test_fixture_execute:  [{ context: :test, executable: 'out/test_adc.out' },               'out/test_adc.out'],
+    post_test_fixture_execute: [{ context: :test, executable: 'out/test_adc.out' },               'out/test_adc.out']
+  }.freeze
+
+  describe 'hooks with an argument hash' do
+    COMMAND_HOOKS_CORE_CALLS.each do |hook, (arg_hash, expected)|
+      it "runs :#{hook} with #{expected} as ${1}" do
+        in_project do
+          plugin_for( command_hooks: { hook => recording_hook( hook ) } ).public_send( hook, arg_hash )
+
+          expect(recorded( hook )).to eq( expected )
+        end
+      end
+    end
+  end
+
+  describe 'hooks with plain values' do
+    it 'runs :pre_test and :post_test with the test filepath' do
+      in_project do
+        plugin = plugin_for( command_hooks: { pre_test: recording_hook( :pre_test ), post_test: recording_hook( :post_test ) } )
+        plugin.pre_test( 'test/test_adc.c' )
+        plugin.post_test( 'test/test_adc.c' )
+
+        expect([recorded( :pre_test ), recorded( :post_test )]).to all( eq( 'test/test_adc.c' ) )
+      end
+    end
+
+    it 'runs :pre_test_build with the build context' do
+      in_project do
+        plugin_for( command_hooks: { pre_test_build: recording_hook( :pre_test_build ) } ).pre_test_build( :gcov, 12.5 )
+
+        expect(recorded( :pre_test_build )).to eq( 'gcov' )
+      end
+    end
+
+    it 'runs :pre_build, :post_build, and :post_error with the timestamp' do
+      in_project do
+        hooks  = %i[pre_build post_build post_error]
+        plugin = plugin_for( command_hooks: hooks.to_h { |hook| [hook, recording_hook( hook )] } )
+        hooks.each { |hook| plugin.public_send( hook, 3.25 ) }
+
+        expect(hooks.map { |hook| recorded( hook ) }).to all( eq( '3.25' ) )
+      end
+    end
+  end
+
+  describe 'configuration' do
+    it 'runs each tool of a hook given a list, in order' do
+      in_project do
+        first  = { executable: 'ruby', arguments: ['-e', '"File.write(%q{order.txt}, %q{a})"'] }
+        second = { executable: 'ruby', arguments: ['-e', '"File.write(%q{order.txt}, File.read(%q{order.txt}) + %q{b})"'] }
+        plugin_for( command_hooks: { pre_build: [first, second] } ).pre_build( 1 )
+
+        expect(File.read( 'order.txt' )).to eq( 'ab' )
+      end
+    end
+
+    it 'refuses an unrecognized hook' do
+      expect { plugin_for( command_hooks: { pre_bulid: recording_hook( :pre_bulid ) } ) }
+        .to raise_error( CeedlingException, /Unrecognized hooks/ )
+    end
+
+    it 'refuses a missing :command_hooks section' do
+      expect { plugin_for( {} ) }.to raise_error( CeedlingException, /missing a required configuration block/ )
+    end
+
+    it 'refuses a hook whose executable does not exist' do
+      expect { plugin_for( command_hooks: { pre_build: { executable: 'no-such-hook-tool' } } ) }
+        .to raise_error( CeedlingException, /no-such-hook-tool/ )
+    end
+
+    it 'leaves the project configuration without a :logging entry of its own' do
+      config = { command_hooks: { pre_build: recording_hook( :pre_build ) } }
+
+      in_project { plugin_for( config ) }
+
+      expect(config).not_to have_key( :logging )
+    end
+  end
+
+end

data/spec/integration/compile_commands_json_db_spec.rb

@@ -0,0 +1,76 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Integration coverage for the JSON compilation database plugin against real files.
+#
+# Whether the database a build leaves on disk parses, and whether the next build picks it
+# up, are filesystem facts. A real FileWrapper runs here against a real temp artifacts
+# directory. The unit spec at spec/units/plugins/compile_commands_json_db_spec.rb owns
+# every decision observable through a doubled file layer.
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+require 'ceedling/constants'
+require 'ceedling/plugins/plugin'
+require 'ceedling/file_wrapper'
+
+$: << File.expand_path('../../../plugins/compile_commands_json_db/lib', __FILE__)
+require 'compile_commands_json_db'
+
+describe 'CompileCommandsJsonDb (integration)' do
+  around(:each) do |example|
+    Dir.mktmpdir do |dir|
+      @artifacts = dir
+      example.run
+    end
+  end
+
+  before(:each) do
+    stub_const('PROJECT_BUILD_ARTIFACTS_ROOT', @artifacts)
+
+    @loginator   = double('loginator', log: nil)
+    verbosinator = double('verbosinator', should_output?: false)
+    @objects     = { file_wrapper: FileWrapper.new( { loginator: @loginator, verbosinator: verbosinator } ), loginator: @loginator }
+  end
+
+  let(:database_path) { File.join( @artifacts, 'compile_commands.json' ) }
+
+  # One build: a fresh plugin, the given compiles, then the end of the build
+  def build(*sources)
+    plugin = CompileCommandsJsonDb.new( @objects, 'compile_commands_json_db', '/plugins/compile_commands_json_db' )
+    sources.each do |source|
+      plugin.post_compile_execute( source: source, object: "#{source}.o", shell_command: "gcc -c #{source}" )
+    end
+    plugin.post_build(0)
+  end
+
+  it 'leaves a JSON array of compile entries on disk' do
+    build('src/adder.c')
+
+    database = JSON.parse( File.read( database_path ) )
+    expect(database).to be_an(Array)
+    expect(database.first).to include('file' => 'src/adder.c', 'command' => 'gcc -c src/adder.c')
+  end
+
+  it "carries one build's entries into the next" do
+    build('src/adder.c')
+    build('src/sensor.c')
+
+    files = JSON.parse( File.read( database_path ) ).map { |entry| entry['file'] }
+    expect(files).to eq(['src/adder.c', 'src/sensor.c'])
+  end
+
+  it 'recovers from a corrupt database left by an earlier build' do
+    File.write( database_path, '[{"file": "src/old.c", ' )
+
+    expect { build('src/adder.c') }.to_not raise_error
+
+    files = JSON.parse( File.read( database_path ) ).map { |entry| entry['file'] }
+    expect(files).to eq(['src/adder.c'])
+  end
+end