ceedling 1.1.9 → 1.2.0

data/spec/units/config/configurator_validator_spec.rb

@@ -0,0 +1,259 @@
+# =========================================================================
+#   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 'config_yaml_helper'
+require 'ceedling/config/configurator_validator'
+require 'ceedling/config/config_walkinator'
+require 'ceedling/reportinator'
+
+# Unit coverage for ConfiguratorValidator through a doubled file layer. What these
+# validations make of a real project tree is proven in
+# spec/integration/configurator_validation_spec.rb.
+describe ConfiguratorValidator do
+  include ConfigYamlHelper
+
+  before(:each) do
+    @file_wrapper   = double('file_wrapper')
+    @loginator      = double('loginator', log: nil)
+    @tool_validator = double('tool_validator')
+
+    @validator = described_class.new(
+      {
+        config_walkinator: ConfigWalkinator.new,
+        file_wrapper:      @file_wrapper,
+        loginator:         @loginator,
+        reportinator:      Reportinator.new,
+        tool_validator:    @tool_validator
+      }
+    )
+  end
+
+  def existing(*paths)
+    allow(@file_wrapper).to receive(:exist?) { |path| paths.include?( path ) }
+  end
+
+  def directories(*paths)
+    allow(@file_wrapper).to receive(:directory?) { |path| paths.include?( path ) }
+  end
+
+  describe '#exists?' do
+    let(:config) { config_from_yaml( ":project:\n  :build_root: build\n  :use_mocks: false\n" ) }
+
+    it 'finds a value at the end of a key walk' do
+      expect(@validator.exists?( config, :project, :build_root )).to be true
+    end
+
+    it 'counts a false value as present' do
+      expect(@validator.exists?( config, :project, :use_mocks )).to be true
+    end
+
+    it 'logs the full walk of a missing entry' do
+      expect(@validator.exists?( config, :paths, :test )).to be false
+      expect(@loginator).to have_received(:log).with('Required config file entry :paths ↳ :test does not exist.', Verbosity::ERRORS)
+    end
+  end
+
+  describe '#validate_path_list' do
+    let(:config) { config_from_yaml( ":paths:\n  :test:\n    - +:test/**\n    - -:test/ignore\n    - '**/generated'\n" ) }
+
+    it 'checks each path stripped of its aggregation decorator and glob' do
+      existing('test', 'test/ignore')
+      expect(@validator.validate_path_list( config, :paths, :test )).to be true
+    end
+
+    it 'skips a path that begins with a glob' do
+      existing('test', 'test/ignore')
+      @validator.validate_path_list( config, :paths, :test )
+      expect(@file_wrapper).to_not have_received(:exist?).with('')
+    end
+
+    it 'logs each path that does not exist' do
+      existing('test')
+      expect(@validator.validate_path_list( config, :paths, :test )).to be false
+      expect(@loginator).to have_received(:log).with("Config path :paths ↳ :test => 'test/ignore' does not exist in the filesystem.", Verbosity::ERRORS)
+    end
+
+    it 'fails a missing entry' do
+      expect(@validator.validate_path_list( config, :paths, :source )).to be false
+    end
+  end
+
+  # An entry naming no path, or wrapping its path in quotes, is rejected before any
+  # filesystem check. Both usually come from quoting only the path after a +: or -:
+  # decoration, so each rejection carries a hint about quoting.
+  shared_examples 'an entry that names no usable path' do |walk|
+    {
+      'a bare subtractive decoration' => "    - '-:'\n",
+      'a bare additive decoration'    => "    - '+:'\n",
+      'an empty string'               => "    - ''\n",
+      'whitespace alone'              => "    - '   '\n",
+      'a YAML null'                   => "    -\n",
+    }.each_pair do |label, yaml|
+      it "rejects #{label} as naming no path, with a quoting hint" do
+        expect(validate( yaml )).to be false
+        expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '.*' names no path/, Verbosity::ERRORS)
+        expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
+      end
+    end
+
+    # YAML reads an unquoted decoration with nothing after it as a one-key mapping
+    it 'rejects an entry YAML read as something other than a path, with a quoting hint' do
+      expect(validate( "    - -:\n" )).to be false
+      expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '.*' is not a path \(YAML read it as a Hash\)/, Verbosity::ERRORS)
+      expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
+    end
+
+    it 'rejects a path wrapped in quotes after its decoration, with a quoting hint' do
+      expect(validate( "    - '-:\"src/a.c\"'\n" )).to be false
+      expect(@loginator).to have_received(:log).with(/#{Regexp.escape(walk)} => '-:"src\/a.c"' wraps its path in quotes/, Verbosity::ERRORS)
+      expect(@loginator).to have_received(:log).with(/Quote the whole entry/, Verbosity::ERRORS)
+    end
+  end
+
+  describe '#validate_paths_entries' do
+    def validate(yaml_list)
+      @validator.validate_paths_entries( config_from_yaml( ":paths:\n  :source:\n#{yaml_list}" ), :source )
+    end
+
+    it 'accepts a glob that yields directories' do
+      existing; directories('src', 'src/a')
+      allow(@file_wrapper).to receive(:directory_listing).with('src/**/**').and_return(['src', 'src/a', 'src/a/x.c'])
+
+      expect(validate( "    - src/**\n" )).to be true
+    end
+
+    it 'warns about and skips a path naming a file' do
+      existing('src/main.c'); directories
+
+      expect(validate( "    - src/main.c\n" )).to be true
+      expect(@loginator).to have_received(:log).with(/'src\/main.c' is a filepath and will be ignored/, Verbosity::COMPLAIN)
+    end
+
+    it 'accepts a subdirectory glob of a directory that has no subdirectories' do
+      existing; directories
+      allow(@file_wrapper).to receive(:directory_listing).and_return([])
+
+      expect(validate( "    - src/*\n" )).to be true
+    end
+
+    it 'logs a path that yields no directories' do
+      existing; directories
+      allow(@file_wrapper).to receive(:directory_listing).and_return([])
+
+      expect(validate( "    - -:src/missing\n" )).to be false
+      expect(@loginator).to have_received(:log).with(/'src\/missing' yielded no directories/, Verbosity::ERRORS)
+    end
+
+    it 'escapes literal brackets before globbing' do
+      existing; directories('src/[legacy]')
+      allow(@file_wrapper).to receive(:directory_listing).with('src/\[legacy\]').and_return(['src/[legacy]'])
+
+      expect(validate( "    - 'src/[legacy]'\n" )).to be true
+    end
+
+    it 'fails a missing entry' do
+      expect(@validator.validate_paths_entries( { paths: {} }, :source )).to be false
+    end
+
+    it_behaves_like 'an entry that names no usable path', ':paths ↳ :source'
+  end
+
+  describe '#validate_files_entries' do
+    def validate(yaml_list)
+      @validator.validate_files_entries( config_from_yaml( ":files:\n  :source:\n#{yaml_list}" ), :source )
+    end
+
+    it 'accepts a glob that yields files' do
+      existing; directories
+      allow(@file_wrapper).to receive(:instantiate_file_list).with('src/*.c').and_return(['src/a.c'])
+
+      expect(validate( "    - +:src/*.c\n" )).to be true
+    end
+
+    it 'warns about and skips a path naming a directory' do
+      existing('src'); directories('src')
+
+      expect(validate( "    - src\n" )).to be true
+      expect(@loginator).to have_received(:log).with(/'src' is a directory path and will be ignored/, Verbosity::COMPLAIN)
+    end
+
+    it 'logs a glob that yields no files' do
+      existing; directories
+      allow(@file_wrapper).to receive(:instantiate_file_list).and_return([])
+
+      expect(validate( "    - src/*.x\n" )).to be false
+      expect(@loginator).to have_received(:log).with(/'src\/\*.x' yielded no files/, Verbosity::ERRORS)
+    end
+
+    it 'escapes literal brackets before globbing' do
+      existing; directories
+      allow(@file_wrapper).to receive(:instantiate_file_list).with('src/\[legacy\]/*.c').and_return(['src/[legacy]/a.c'])
+
+      expect(validate( "    - 'src/[legacy]/*.c'\n" )).to be true
+    end
+
+    it 'fails a missing entry' do
+      expect(@validator.validate_files_entries( { files: {} }, :source )).to be false
+    end
+
+    it_behaves_like 'an entry that names no usable path', ':files ↳ :source'
+  end
+
+  describe '#validate_filepath_simple' do
+    it 'accepts an existing path' do
+      existing('helper.h')
+      expect(@validator.validate_filepath_simple( 'helper.h', :cmock, :unity_helper_path )).to be true
+    end
+
+    it 'logs a missing path with the configuration walk it came from' do
+      existing
+      expect(@validator.validate_filepath_simple( 'helper.h', :cmock, :unity_helper_path )).to be false
+      expect(@loginator).to have_received(:log).with("Config path 'helper.h' associated with :cmock ↳ :unity_helper_path does not exist in the filesystem.", Verbosity::ERRORS)
+    end
+  end
+
+  describe '#validate_tool' do
+    let(:config) { { tools: { test_compiler: { executable: 'gcc' } }, extension: { executable: '.out' } } }
+
+    it 'hands the tool, its walk, and the executable extension to the tool validator' do
+      expect(@tool_validator).to receive(:validate).with(
+        tool: { executable: 'gcc' }, name: ':tools ↳ :test_compiler', extension: '.out', respect_optional: true
+      ).and_return(true)
+
+      expect(@validator.validate_tool( config: config, key: :test_compiler )).to be true
+    end
+
+    it 'passes through a request to ignore the optional flag' do
+      expect(@tool_validator).to receive(:validate).with(hash_including( respect_optional: false )).and_return(false)
+
+      expect(@validator.validate_tool( config: config, key: :test_compiler, respect_optional: false )).to be false
+    end
+  end
+
+  describe '#validate_matcher' do
+    it 'accepts a well-formed regular expression' do
+      expect { @validator.validate_matcher( '/Test(Foo|Bar)/' ) }.to_not raise_error
+    end
+
+    it 'rejects a malformed regular expression' do
+      expect { @validator.validate_matcher( '/Test(/' ) }.to raise_error(RuntimeError, /invalid regular expression/)
+    end
+
+    it 'accepts a substring or wildcard of letters, digits, spaces, slashes, dots, dashes, underscores, and asterisks' do
+      expect { @validator.validate_matcher( 'test/Test_Foo-1 *.c' ) }.to_not raise_error
+    end
+
+    it 'treats a path with inner slashes as a substring, not a regular expression' do
+      expect { @validator.validate_matcher( 'test/Foo+Bar/' ) }.to raise_error(RuntimeError, /'\+'/)
+    end
+
+    it 'names each distinct invalid character once' do
+      expect { @validator.validate_matcher( 'Foo$Bar$#' ) }.to raise_error(RuntimeError, /'\$', '#'\z/)
+    end
+  end
+end

data/spec/units/config/line_marker_suppressors_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
+# =========================================================================
+
+# Finding the preprocessor options that suppress line markers, wherever configuration
+# hands them to test preprocessing. ConfiguratorSetup#validate_line_markers reports what
+# this finds; configurator_setup_spec.rb covers that reporting.
+
+require 'spec_helper'
+require 'ceedling/config/line_marker_suppressors'
+
+describe LineMarkerSuppressors do
+
+  context ".in_flags" do
+    it "finds -P in a context's :preprocess list" do
+      flags = { test: { preprocess: ['-std=c99', '-P'] } }
+
+      expect(described_class.in_flags( flags, [:test] )).to eq( [ [[:flags, :test, :preprocess], '-P'] ] )
+    end
+
+    # Test preprocessing uses compile flags wherever no :preprocess flags apply
+    it "finds --no-line-commands in a :compile matcher's list, naming the matcher" do
+      flags = { test: { compile: { '/Adc/' => ['--no-line-commands'] } } }
+
+      expect(described_class.in_flags( flags, [:test] )).to eq( [ [[:flags, :test, :compile, '/Adc/'], '--no-line-commands'] ] )
+    end
+
+    it "finds an option among others in one entry, and one passed through -Wp," do
+      flags = { test: { preprocess: ['-Wall -P', '-Wp,-MD,deps.d,-P'] } }
+
+      expect(described_class.in_flags( flags, [:test] ).map( &:last )).to eq( ['-Wall -P', '-Wp,-MD,deps.d,-P'] )
+    end
+
+    it "matches whole options only" do
+      flags = { test: { preprocess: ['-pedantic', '-Wpedantic', '-MP', '-fPIC', '-Pfoo', '-Wp,-MD,deps.d'] } }
+
+      expect(described_class.in_flags( flags, [:test] )).to eq( [] )
+    end
+
+    it "reads the contexts it is given, plugin contexts among them, and no others" do
+      flags = { gcov: { compile: ['-P'] }, release: { compile: ['-P'] } }
+
+      expect(described_class.in_flags( flags, [:test, :gcov] )).to eq( [ [[:flags, :gcov, :compile], '-P'] ] )
+    end
+
+    it "ignores matcher keys and operations other than :preprocess and :compile" do
+      flags = { test: { compile: { '-P' => ['-g'] }, link: ['-P'] } }
+
+      expect(described_class.in_flags( flags, [:test] )).to eq( [] )
+    end
+
+    # validate_flags reports a malformed section; this must only not trip over one
+    it "tolerates malformed flags" do
+      [nil, [], 'string', { test: 'string' }, { test: { compile: 7 } }, { test: { compile: { '/x/' => 7 } } }].each do |flags|
+        expect(described_class.in_flags( flags, [:test] )).to eq( [] )
+      end
+    end
+  end
+
+  context ".in_tools" do
+    def config(arguments, shortcut: nil)
+      config = { tools: { test_file_full_preprocessor: { arguments: arguments } } }
+      config[:tools_test_file_full_preprocessor] = { arguments: shortcut } unless shortcut.nil?
+      return config
+    end
+
+    it "finds an option in a preprocessor tool's arguments" do
+      expect(described_class.in_tools( config( ['-E', '-P', '"${1}"'] ) )).to eq( [ [[:tools, :test_file_full_preprocessor, :arguments], '-P'] ] )
+    end
+
+    # The merged tool holds the shortcut's arguments, but the user wrote them in the shortcut
+    it "names the :tools_<name> shortcut that added the option" do
+      found = described_class.in_tools( config( ['-E', '--no-line-commands'], shortcut: ['--no-line-commands'] ) )
+
+      expect(found).to eq( [ [[:tools_test_file_full_preprocessor, :arguments], '--no-line-commands'] ] )
+    end
+
+    # A bare-includes make rule has no line markers to lose
+    it "leaves the bare-includes tool alone and skips arguments that aren't strings" do
+      config = { tools: { test_bare_includes_preprocessor: { arguments: ['-P'] }, test_file_directives_only_preprocessor: { arguments: [{ '-P' => 1 }] } } }
+
+      expect(described_class.in_tools( config )).to eq( [] )
+    end
+  end
+
+end

data/spec/units/config_matchinator_spec.rb

@@ -396,6 +396,109 @@ describe ConfigMatchinator do
       end
     end
 
+    context 'no_match_default' do
+      it 'returns the accumulated (empty) result when nothing matches and no fallback is given' do
+        hash = { :Model => ['HIT'] }
+        result = @cm.matches?(hash: hash, filepath: 'test_Unrelated', section: :defines, context: :test)
+        expect(result).to eq([])
+      end
+
+      it 'returns no_match_default when nothing matches and a fallback is given' do
+        hash = { :Model => ['HIT'] }
+        result = @cm.matches?(
+          hash: hash, filepath: 'test_Unrelated', section: :defines, context: :test, no_match_default: ['FALLBACK']
+        )
+        expect(result).to eq(['FALLBACK'])
+      end
+
+      it 'ignores no_match_default when something does match' do
+        hash = { :* => ['ALWAYS'] }
+        result = @cm.matches?(
+          hash: hash, filepath: 'test_Anything', section: :defines, context: :test, no_match_default: ['FALLBACK']
+        )
+        expect(result).to eq(['ALWAYS'])
+      end
+
+      it 'logs a notice at OBNOXIOUS verbosity when falling back to no_match_default' do
+        hash = { :Model => ['HIT'] }
+        expect(@loginator).to receive(:lazy).with(Verbosity::OBNOXIOUS)
+
+        @cm.matches?(
+          hash: hash, filepath: 'test_Unrelated', section: :defines, context: :test, no_match_default: ['FALLBACK']
+        )
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Exclusion by negative lookahead
+    # -------------------------------------------------------------------------
+    # Matchers only ever add (`_values += values` in #matches?), so there is no
+    # way to say "every test executable except these." The only way to express
+    # an exclusion is a regex that fails to match what should be left alone.
+    #
+    # Ceedling's own CI relies on this to instrument the system test suite with
+    # ASan+UBSan while leaving the deliberately-crashing `nosanitize` fixtures
+    # un-instrumented -- see spec/support/system/sanitizers/. These examples
+    # pin the two properties that scheme depends on, both of which fail
+    # silently rather than loudly if they ever stop holding: the key is treated
+    # as a regex (a demotion to substring matching would match nothing, and
+    # instrument nothing), and the lookahead is anchored.
+    # -------------------------------------------------------------------------
+    context 'exclusion by negative lookahead' do
+      # The matcher Ceedling's sanitizer mixins use, verbatim
+      let(:exclusion_hash) { { :'/\A(?!.*nosanitize).*\z/' => ['INSTRUMENTED'] } }
+
+      it 'is recognized as a regex rather than demoted to a substring match' do
+        # A substring match against this key would never hit any real filepath,
+        # so a non-empty result is itself the proof the regex form was taken
+        result = @cm.matches?(
+          hash: exclusion_hash, filepath: 'test/test_example_file.c', section: :flags, context: :test
+        )
+        expect(result).to eq(['INSTRUMENTED'])
+      end
+
+      it 'matches ordinary test filepaths' do
+        [
+          'test/test_example_file.c',
+          'test/test_example_file_with_mock.c',
+          'build/test/runners/test_example_file_runner.c',
+          'test_nosanitary_name.c'
+        ].each do |filepath|
+          expect(
+            @cm.matches?(hash: exclusion_hash, filepath: filepath, section: :flags, context: :test)
+          ).to eq(['INSTRUMENTED']), "expected #{filepath} to be instrumented"
+        end
+      end
+
+      it 'excludes every filepath carrying the marker' do
+        [
+          'test/test_nosanitize_crash_sigsegv.c',
+          'test/test_nosanitize_crash_sigsegv_with_param.c',
+          'test/test_nosanitize_crash_assert.c',
+          'test/test_nosanitize_ub_shift_overflow.c',
+          'test/test_nosanitize_boom.c',
+          'build/test/runners/test_nosanitize_crash_assert_runner.c'
+        ].each do |filepath|
+          expect(
+            @cm.matches?(hash: exclusion_hash, filepath: filepath, section: :flags, context: :test)
+          ).to eq([]), "expected #{filepath} to be excluded"
+        end
+      end
+
+      it 'requires \A anchoring -- an unanchored lookahead excludes nothing' do
+        # Regexp#match scans forward for any position where the pattern can
+        # succeed. Past the marker, the lookahead is satisfied, so an
+        # unanchored pattern matches the very files it means to skip. This
+        # example exists to keep that trap documented and caught.
+        unanchored = { :'/(?!.*nosanitize).*\z/' => ['INSTRUMENTED'] }
+        expect(
+          @cm.matches?(
+            hash: unanchored, filepath: 'test/test_nosanitize_crash_sigsegv.c', section: :flags, context: :test
+          )
+        ).to eq(['INSTRUMENTED'])
+      end
+    end
+
   end # #matches?
 
 end

data/spec/units/defineinator_spec.rb

@@ -0,0 +1,158 @@
+# =========================================================================
+#   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/defineinator'
+
+# ConfigMatchinator's own matching/no-match-default semantics are already
+# thoroughly pinned in config_matchinator_spec.rb, so @config_matchinator is
+# stubbed wholesale here -- these specs only need to confirm Defineinator
+# calls it correctly and handles each return shape correctly, not
+# re-verify its internal matching logic.
+describe Defineinator do
+  before(:each) do
+    @configurator       = double('configurator')
+    @loginator          = double('loginator')
+    @config_matchinator = double('config_matchinator')
+
+    @defineinator = described_class.new({
+      :configurator       => @configurator,
+      :loginator          => @loginator,
+      :config_matchinator => @config_matchinator,
+    })
+  end
+
+  describe '#defines_defined?' do
+    it 'delegates to config_matchinator with the :defines top key and the given context' do
+      allow(@config_matchinator).to receive(:config_include?)
+        .with(primary: :defines, secondary: :test)
+        .and_return(true)
+
+      expect(@defineinator.defines_defined?(context: :test)).to eq(true)
+    end
+
+    it 'passes through a false result unchanged' do
+      allow(@config_matchinator).to receive(:config_include?)
+        .with(primary: :defines, secondary: :release)
+        .and_return(false)
+
+      expect(@defineinator.defines_defined?(context: :release)).to eq(false)
+    end
+  end
+
+  describe '#defines' do
+    it 'returns the empty-array default when get_config finds no matching configuration' do
+      allow(@config_matchinator).to receive(:get_config).and_return(nil)
+
+      expect(@defineinator.defines(subkey: :test)).to eq([])
+    end
+
+    it 'returns a caller-provided default when get_config finds no matching configuration' do
+      allow(@config_matchinator).to receive(:get_config).and_return(nil)
+
+      expect(@defineinator.defines(subkey: :test, default: [:FALLBACK])).to eq([:FALLBACK])
+    end
+
+    it 'flattens an Array result, handling nested arrays left over from YAML list aliasing' do
+      allow(@config_matchinator).to receive(:get_config).and_return([:A, [:B, :C]])
+
+      expect(@defineinator.defines(subkey: :test)).to eq([:A, :B, :C])
+    end
+
+    it 'delegates a Hash result to config_matchinator#matches? with the correct argument shape' do
+      hash_config = { '*' => [:A] }
+      allow(@config_matchinator).to receive(:get_config).and_return(hash_config)
+      allow(@config_matchinator).to receive(:matches?)
+        .with(
+          hash: hash_config,
+          filepath: 'test_Foo.c',
+          section: :defines,
+          context: :test,
+          no_match_default: nil
+        )
+        .and_return([:MATCHED])
+
+      result = @defineinator.defines(subkey: :test, filepath: 'test_Foo.c')
+
+      expect(result).to eq([:MATCHED])
+    end
+
+    it 'threads no_match_default through to config_matchinator#matches? unchanged' do
+      hash_config = { 'Model' => [:A] }
+      allow(@config_matchinator).to receive(:get_config).and_return(hash_config)
+      allow(@config_matchinator).to receive(:matches?)
+        .with(hash: hash_config, filepath: 'test_Foo.c', section: :defines, context: :test, no_match_default: [:FALLBACK])
+        .and_return([:FALLBACK])
+
+      result = @defineinator.defines(subkey: :test, filepath: 'test_Foo.c', no_match_default: [:FALLBACK])
+
+      expect(result).to eq([:FALLBACK])
+    end
+
+    it 'returns an empty array for a config value of an unexpected type' do
+      allow(@config_matchinator).to receive(:get_config).and_return('not-an-array-or-hash')
+
+      expect(@defineinator.defines(subkey: :test)).to eq([])
+    end
+
+    it 'uses an explicit topkey override instead of the default :defines section' do
+      allow(@config_matchinator).to receive(:get_config)
+        .with(primary: :unity, secondary: :defines)
+        .and_return([:UNITY_INCLUDE_PRINT_FORMATTED])
+
+      result = @defineinator.defines(topkey: :unity, subkey: :defines)
+
+      expect(result).to eq([:UNITY_INCLUDE_PRINT_FORMATTED])
+    end
+  end
+
+  describe '#generate_test_definition' do
+    it 'returns an empty array when :defines ↳ :use_test_definition is disabled' do
+      allow(@configurator).to receive(:defines_use_test_definition).and_return(false)
+
+      expect(@defineinator.generate_test_definition(filepath: 'test/test_Foo.c')).to eq([])
+    end
+
+    it 'derives an uppercase, underscore-wrapped symbol from the test file basename' do
+      allow(@configurator).to receive(:defines_use_test_definition).and_return(true)
+
+      result = @defineinator.generate_test_definition(filepath: 'test/test_Foo.c')
+
+      expect(result).to eq(['_TEST_FOO_'])
+    end
+
+    it 'replaces non-ASCII bytes with underscores but preserves dashes, matching the documented example' do
+      allow(@configurator).to receive(:defines_use_test_definition).and_return(true)
+
+      # Matches docs/mkdocs/configuration/reference/defines.md's own worked example
+      # verbatim: "Underscores and dashes are preserved."
+      result = @defineinator.generate_test_definition(filepath: 'test_123abc-xyz😵.c')
+
+      expect(result).to eq(['_TEST_123ABC-XYZ_'])
+    end
+
+    it 'does not double up a leading or trailing underscore already present in the basename' do
+      allow(@configurator).to receive(:defines_use_test_definition).and_return(true)
+
+      result = @defineinator.generate_test_definition(filepath: '_test_Foo_.c')
+
+      expect(result).to eq(['_TEST_FOO_'])
+    end
+
+    it 'treats a leading-dot-only filepath as having no extension to strip, per File.basename' do
+      allow(@configurator).to receive(:defines_use_test_definition).and_return(true)
+
+      # File.basename('.c', '.*') returns '.c' unchanged -- a leading dot with nothing
+      # before it is a dotfile name, not a stem+extension, so '.*' has nothing to strip.
+      # The leading '.' then falls to the non-alphanumeric gsub same as any other
+      # punctuation, and the already-underscore-prefixed result isn't prepended again.
+      result = @defineinator.generate_test_definition(filepath: '.c')
+
+      expect(result).to eq(['_C_'])
+    end
+  end
+end