ceedling 1.2.0 → 1.2.2

data/spec/integration/path_scenarios_spec.rb

@@ -0,0 +1,322 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# Path handling across project layouts and the spellings a project file may use for one
+# place: through configuration, collection, build-path mapping, and the lookups that invert
+# it. Every build file must land inside the build root, distinct inputs must stay distinct,
+# and every spelling of one layout must place files alike.
+#
+# Each example names the gap it probes (GH #1370 and the path handling audit around it).
+
+require 'spec_helper'
+require 'path_scenario_harness'
+
+describe 'Path scenarios (integration)' do
+  include PathScenarioHarness
+
+  TEST_C = "#include \"unity.h\"\nvoid setUp(void) {}\nvoid tearDown(void) {}\nvoid test_it(void) {}\n"
+
+  def c(name)
+    "int #{name}(void) { return 0; }\n"
+  end
+
+  def h(name)
+    "int #{name}(void);\n"
+  end
+
+  # --- Baseline -------------------------------------------------------------------------
+
+  it 'baseline: mirrors same-named files below one plain root, inside the build root' do
+    files = {
+      'app/src/a/util.c' => c( 'a' ), 'app/src/b/util.c' => c( 'b' ),
+      'app/src/a/util.h' => h( 'a' ), 'app/src/b/util.h' => h( 'b' ),
+      'app/test/test_u.c' => TEST_C
+    }
+    in_workspace( files ) do |ws, app|
+      scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['src/**'] } ) )
+      placed = placements( scene )
+
+      placed.each_value { |paths| expect_inside_build( paths ) }
+      expect_distinct( placed[:test_objects], 'test objects' )
+      expect_distinct( placed[:release_objects], 'release objects' )
+      expect_distinct( placed[:preprocessed], 'preprocessed headers' )
+    end
+  end
+
+  # --- G1 (#1370): a `..` root beside a header outside the project ------------------------
+
+  # The report's vendor SDK sat at its drive's root, far above the project, so its headers'
+  # paths climb past the `..` root. A sibling one level up is truly below `..` and mirrors.
+  context 'G1 (#1370): a `..` root beside an include path far outside the project' do
+    def files
+      {
+        'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ),
+        'app/test/test_m.c' => TEST_C,
+        'vendor/inc/cmsis.h' => h( 'cmsis' )
+      }
+    end
+
+    [
+      ['an absolute vendor path far outside', '%{far}/inc'],
+      ['a sibling vendor path', '../vendor/inc']
+    ].each do |label, vendor|
+      it "places a mock of the vendor header inside the build root, with #{label}" do
+        in_workspace( files, far: { 'inc/sdk.h' => h( 'sdk' ) } ) do |ws, app|
+          scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['../**', vendor] } ) )
+          placed = placements( scene )
+
+          expect_inside_build( placed[:mocks] )
+          expect_inside_build( placed[:preprocessed] )
+          expect_inside_build( placed[:test_objects] )
+        end
+      end
+    end
+  end
+
+  # --- G2: equivalent spellings of one root ------------------------------------------------
+
+  context 'G2: one layout under each spelling of its roots' do
+    def files
+      {
+        'app/src/a/util.c' => c( 'a' ), 'app/src/b/util.c' => c( 'b' ),
+        'app/src/a/util.h' => h( 'a' ), 'app/src/b/util.h' => h( 'b' ),
+        'app/test/test_u.c' => TEST_C
+      }
+    end
+
+    def placed_with(spelling, ws, app)
+      spell = PathScenarioHarness::ROOT_SPELLINGS[spelling]
+      roots = ->(root) { [spell.call( root, ws: ws, app: app )] }
+      scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: roots.( 'test/**' ), source: roots.( 'src/**' ), include: roots.( 'src/**' ) } ) )
+      return [scene, relative_placements( scene )]
+    end
+
+    (PathScenarioHarness::ROOT_SPELLINGS.keys - [:plain]).each do |spelling|
+      it "places every build file as the plain spelling does, with #{spelling} roots" do
+        in_workspace( files, symlink: spelling == :symlink ) do |ws, app|
+          _, plain = placed_with( :plain, ws, app )
+          scene, spelled = placed_with( spelling, ws, app )
+
+          expect_one_spelling_each( scene[:configurator] )
+          expect(spelled).to eq( plain )
+        end
+      end
+    end
+  end
+
+  # --- G3 and G13: exclusions ---------------------------------------------------------------
+
+  context 'G3 and G13: a `-:` exclusion' do
+    def files
+      {
+        'app/src/sub/x.c' => c( 'x1' ), 'app/src/exp/sub/x.c' => c( 'x2' ), 'app/src/exp/deep/y.c' => c( 'y' ),
+        'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C
+      }
+    end
+
+    it 'G13: excludes the whole subtree it names' do
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['+:src/**', '-:src/exp'], include: ['src/**'] } ) )
+
+        expect(scene[:configurator].collection_all_source).to match_array( %w[src/sub/x.c] )
+      end
+    end
+
+    # A file the exclusion fails to drop (G13) must not mirror below the exclusion itself
+    it 'G3: is never a root that kept files mirror below' do
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['+:src/**', '-:src/exp'], include: ['src/**'] } ) )
+        placed = placements( scene )
+
+        expect_distinct( placed[:release_objects], 'release objects' )
+      end
+    end
+  end
+
+  # --- G4: header-to-source correlation ---------------------------------------------------
+
+  context 'G4: a header found beside its source by convention' do
+    def files
+      {
+        'app/include/drv/x.h' => h( 'x' ), 'app/src/drv/x.c' => c( 'x' ),
+        'app/components/foo/include/foo.h' => h( 'foo' ), 'app/components/foo/src/foo.c' => c( 'foo' ),
+        'app/test/test_x.c' => TEST_C
+      }
+    end
+
+    {
+      'a plain include root'     => ['include/**'],
+      'a `./` include root'      => ['./include/**'],
+      'an absolute include root' => ['%{app}/include/**']
+    }.each do |label, include|
+      it "finds the source of a header below #{label}" do
+        in_workspace( files ) do |ws, app|
+          scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: include } ) )
+
+          expect(scene[:finder].find_build_input_file( filepath: 'include/drv/x.h', complain: :ignore, context: :test )).to eq( 'src/drv/x.c' )
+        end
+      end
+    end
+
+    it 'finds the source of a header below a glob-middle include root' do
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['components/*/src'], include: ['components/*/include'] } ) )
+
+        expect(scene[:finder].find_build_input_file( filepath: 'components/foo/include/foo.h', complain: :ignore, context: :test )).to eq( 'components/foo/src/foo.c' )
+      end
+    end
+  end
+
+  # --- G5 and G6: collisions --------------------------------------------------------------
+
+  context 'G5: the same relative path below two roots' do
+    it 'gives each source its own release object' do
+      files = { 'app/src/foo.c' => c( 'a' ), 'app/lib/foo.c' => c( 'b' ), 'app/src/foo.h' => h( 'a' ), 'app/test/test_f.c' => TEST_C }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**', 'lib/**'], include: ['src/**'] } ) )
+
+        expect_distinct( placements( scene )[:release_objects], 'release objects' )
+      end
+    end
+  end
+
+  context 'G6: nested roots' do
+    it 'gives a file in the inner root and one in the outer root their own objects' do
+      files = { 'app/src/util.c' => c( 'a' ), 'app/src/legacy/util.c' => c( 'b' ), 'app/src/util.h' => h( 'a' ), 'app/test/test_u.c' => TEST_C }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**', 'src/legacy/**'], include: ['src/**'] } ) )
+        placed = placements( scene )
+
+        expect_distinct( placed[:test_objects], 'test objects' )
+        expect_distinct( placed[:release_objects], 'release objects' )
+      end
+    end
+  end
+
+  # --- G8: outside every root -------------------------------------------------------------
+
+  context 'G8: sources reached only through :files' do
+    it 'gives same-named files outside every root their own objects' do
+      files = { 'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/a/util.c' => c( 'a' ), 'app/b/util.c' => c( 'b' ), 'app/test/test_m.c' => TEST_C }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['src/**'] }, files: { source: ['a/util.c', 'b/util.c'] } ) )
+
+        expect_distinct( placements( scene )[:release_objects], 'release objects' )
+      end
+    end
+  end
+
+  # --- Sources outside the project --------------------------------------------------------
+
+  context 'sources and headers in a sibling directory' do
+    it 'places their build files inside the build root, each its own' do
+      files = {
+        'shared/src/a/util.c' => c( 'a' ), 'shared/src/b/util.c' => c( 'b' ),
+        'shared/src/a/util.h' => h( 'a' ), 'shared/src/b/util.h' => h( 'b' ),
+        'app/test/test_u.c' => TEST_C
+      }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['../shared/src/**'], include: ['../shared/src/**'] } ) )
+        placed = placements( scene )
+
+        placed.each_value { |paths| expect_inside_build( paths ) }
+        expect_distinct( placed[:release_objects], 'release objects' )
+      end
+    end
+  end
+
+  # --- G15: a root above the build root --------------------------------------------------
+
+  context 'G15: a root that holds the build root' do
+    it 'collects nothing from an existing build directory' do
+      files = {
+        'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C,
+        'app/build/test/mocks/test/test_m/mock_main.h' => h( 'mock' ), 'app/build/test/runners/test/test_m/test_m_runner.c' => c( 'r' )
+      }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['../**'] } ) )
+
+        expect_collections_outside_build( scene[:configurator] )
+      end
+    end
+
+    # A release compiles every collected source, so generated mocks and runners broke it
+    it 'collects nothing from an existing build directory through a `:files` glob' do
+      files = {
+        'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C,
+        'app/build/test/mocks/test/test_m/mock_main.c' => c( 'mock' ), 'app/build/vendor/unity/src/unity.c' => c( 'unity' )
+      }
+      in_workspace( files ) do |ws, app|
+        yaml  = scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['src/**'] }, files: { source: ['+:**/*.c'] } )
+        scene = scenario( yaml )
+
+        expect_collections_outside_build( scene[:configurator] )
+        expect(scene[:configurator].collection_release_build_input.to_a.grep( %r{\Abuild/} )).to be_empty
+        expect(scene[:configurator].collection_existing_test_build_input.to_a.grep( %r{\Abuild/test/} )).to be_empty
+      end
+    end
+
+    # Generated code may sit in the build root, beside the directories Ceedling creates there
+    it 'collects generated code an entry names in the build root, but nothing Ceedling created there' do
+      files = {
+        'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C,
+        'app/build/gen/table.c' => c( 'table' ), 'app/build/gen/table.h' => h( 'table' ),
+        'app/build/test/mocks/test/test_m/mock_main.c' => c( 'mock' ), 'app/build/test/mocks/test/test_m/mock_main.h' => h( 'mock' )
+      }
+      in_workspace( files ) do |ws, app|
+        paths = { test: ['test/**'], source: ['src/**', 'build/**'], include: ['src/**', 'build/gen'] }
+        yaml  = scenario_yaml( ws: ws, app: app, paths: paths, files: { source: ['+:build/**/*.c'] } )
+        scene = scenario( yaml )
+
+        expect(scene[:configurator].collection_all_source.to_a).to contain_exactly( 'src/main.c', 'build/gen/table.c' )
+        expect(scene[:configurator].collection_all_headers.to_a).to include( 'build/gen/table.h' )
+        expect(scene[:configurator].collection_all_headers.to_a.grep( %r{\Abuild/test/} )).to be_empty
+      end
+    end
+  end
+
+  # --- Test files kept out of the sources and the release --------------------------------
+
+  context 'test files among the sources' do
+    # A release compiles every source it collects, and a test file holds a second main()
+    it 'collects no test file into the sources or the release through a `:files` glob' do
+      files = { 'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C }
+      in_workspace( files ) do |ws, app|
+        yaml  = scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**'], include: ['src/**'] }, files: { source: ['+:**/*.c'] } )
+        scene = scenario( yaml )
+
+        expect(scene[:configurator].collection_all_tests.to_a).to eq( ['test/test_m.c'] )
+        expect(scene[:configurator].collection_all_source.to_a).to eq( ['src/main.c'] )
+        expect(scene[:configurator].collection_release_build_input.to_a).to eq( ['src/main.c'] )
+      end
+    end
+
+    # A test root beside the sources reaches the release through :paths as well
+    it 'collects no test file into the release from a source root that holds the tests' do
+      files = { 'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/src/test/test_m.c' => TEST_C }
+      in_workspace( files ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['src/test/**'], source: ['src/**'], include: ['src/**'] } ) )
+
+        expect(scene[:configurator].collection_release_build_input.to_a).to eq( ['src/main.c'] )
+      end
+    end
+
+  end
+
+  # --- G12: the working directory reached through a symlink -------------------------------
+
+  context 'G12: absolute roots spelled through a symlink to the project' do
+    it 'collects each file once' do
+      files = { 'app/src/main.c' => c( 'main' ), 'app/src/main.h' => h( 'main' ), 'app/test/test_m.c' => TEST_C }
+      in_workspace( files, symlink: true ) do |ws, app|
+        scene = scenario( scenario_yaml( ws: ws, app: app, paths: { test: ['test/**'], source: ['src/**', '%{ws}/link/src/**'], include: ['src/**'] } ) )
+
+        expect_one_spelling_each( scene[:configurator] )
+      end
+    end
+  end
+end

data/spec/integration/quote_include_isolator_spec.rb

@@ -24,7 +24,7 @@ require 'spec_integration_helper'
 require 'fileutils'
 require 'tmpdir'
 require 'open3'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/quote_include_isolator'
 require 'ceedling/constants'
 

data/spec/integration/rake_task_registry_plugins_spec.rb

@@ -0,0 +1,95 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# The task registry decides from the requested task names whether a command builds tests or a
+# release, and so whether build/vendor/ is populated (GH #1361). It reads that from the real
+# .rake files. The first pass runs before plugin constants are loaded, so a plugin namespace
+# such as `namespace GCOV_SYM do` is resolved by its NAME_SYM naming convention. The second
+# pass resolves the constants themselves. Both must agree.
+
+require 'spec_helper'
+require 'ceedling/constants'
+require 'ceedling/rake_app/rake_task_registry'
+
+describe 'RakeTaskRegistry against the real rakefiles (integration)' do
+  REGISTRY_SPEC_ROOT = File.expand_path( '../..', __dir__ )
+
+  REGISTRY_SPEC_RAKEFILES = Dir.glob( File.join( REGISTRY_SPEC_ROOT, 'lib/ceedling/rakefiles/**/*.rake' ) ) +
+              %w[gcov valgrind sanitize bullseye].map { |plugin| File.join( REGISTRY_SPEC_ROOT, "plugins/#{plugin}/#{plugin}.rake" ) }
+
+  REGISTRY_SPEC_PLUGIN_CONSTANTS = {
+    'GCOV_SYM'     => :gcov,
+    'VALGRIND_SYM' => :valgrind,
+    'SANITIZE_SYM' => :sanitize,
+    'BULLSEYE_SYM' => :bullseye
+  }.freeze
+
+  REGISTRY_SPEC_TEST_BUILDS = %w[
+    test test:all test:test_foo.c test:unit/test_foo.c
+    gen:mocks:test_foo.c
+    gcov:all gcov:test_foo.c gcov:test/test_foo.c
+    valgrind:all valgrind:test/test_foo.c
+    sanitize:all sanitize:test/test_foo.c
+    bullseye:all bullseye:test/test_foo.c
+  ].freeze
+
+  REGISTRY_SPEC_NOT_BUILDS = %w[files:test dumpconfig clobber clean utils:gcov report:gcov module:create].freeze
+
+  def registry
+    registry = RakeTaskRegistry.new
+    registry.register_test_tasks( REGISTRY_SPEC_RAKEFILES )
+    registry.register_release_tasks( REGISTRY_SPEC_RAKEFILES )
+    return registry
+  end
+
+  def expect_classified(registry)
+    REGISTRY_SPEC_TEST_BUILDS.each do |task|
+      expect( registry.task_is?( task, RakeTaskRegistry::TAG_TEST ) ).to be(true), "#{task} should be a test build"
+      expect( registry.task_is?( task, RakeTaskRegistry::TAG_BUILD ) ).to be(true), "#{task} should be a build"
+    end
+
+    expect( registry.task_is?( 'release', RakeTaskRegistry::TAG_RELEASE ) ).to be(true)
+    expect( registry.task_is?( 'release', RakeTaskRegistry::TAG_TEST ) ).to be(false)
+
+    REGISTRY_SPEC_NOT_BUILDS.each do |task|
+      expect( registry.task_is?( task, RakeTaskRegistry::TAG_BUILD ) ).to be(false), "#{task} should not be a build"
+    end
+  end
+
+  it 'finds every test-building plugin namespace before plugin constants are loaded' do
+    REGISTRY_SPEC_PLUGIN_CONSTANTS.each_key { |name| hide_const( name ) }
+    expect_classified( registry )
+  end
+
+  # A build reached through a call the registry can't place would leave build/vendor
+  # unpopulated. Each call sits in a namespace, or in a top-level task (`task RELEASE_SYM`)
+  # named for a namespace the registry knows.
+  it 'places every test and release pipeline call where the registry finds it' do
+    registered = registry
+    markers = [RakeTaskRegistry::MARKER_TEST_TASKS_SETUP_AND_INVOKE, RakeTaskRegistry::MARKER_RELEASE_TASKS]
+
+    REGISTRY_SPEC_RAKEFILES.each do |rakefile|
+      lines = File.readlines( rakefile, encoding: 'bom|utf-8' )
+      lines.each_with_index do |line, index|
+        next unless markers.any? { |marker| line.match?( marker ) }
+
+        namespace = registered.send( :find_enclosing_namespace, lines, index )
+        task_line = lines[0...index].reverse.find { |prior| prior.match?( /\Atask\s/ ) }
+        task_name = task_line && task_line[/\Atask\s*\(?\s*:?([A-Za-z_]+)/, 1]
+        task_name = Object.const_get( task_name ).to_s if task_name&.match?( /\A[A-Z_]+\z/ )
+        found = !namespace.nil? || !registered.tags_for( task_name.to_s ).empty?
+
+        expect( found ).to be(true), "#{File.basename( rakefile )}:#{index + 1} runs a pipeline the registry cannot place"
+      end
+    end
+  end
+
+  it 'finds every test-building plugin namespace once plugin constants are loaded' do
+    REGISTRY_SPEC_PLUGIN_CONSTANTS.each { |name, value| stub_const( name, value ) }
+    expect_classified( registry )
+  end
+end

data/spec/integration/report_build_warnings_log_spec.rb

@@ -16,7 +16,7 @@ require 'open3'
 require 'json'
 require 'ceedling/constants'
 require 'ceedling/plugins/plugin'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 
 $LOAD_PATH.unshift( File.expand_path( '../../plugins/report_build_warnings_log/lib', __dir__ ) )
 

data/spec/integration/report_tests_log_factory_spec.rb

@@ -16,7 +16,7 @@ require 'spec_helper'
 require 'json'
 require 'tmpdir'
 require 'rexml/document'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/config/config_walkinator'
 
 $: << File.expand_path('../../../plugins/report_tests_log_factory/lib', __FILE__)

data/spec/integration/test_executable_manifest_spec.rb

@@ -14,7 +14,7 @@ require 'spec_integration_helper'
 require 'open3'
 require 'tmpdir'
 require 'ceedling/constants'
-require 'ceedling/file_wrapper'
+require 'ceedling/filesystem/file_wrapper'
 require 'ceedling/generators/generator'
 require 'ceedling/system_wrapper'
 require 'fileutils'

data/spec/integration/test_includes_extractinator_spec.rb

@@ -140,7 +140,8 @@ describe 'Test file #include extraction (integration)' do
 
         extract_in_mode( tree, 'test_reader.c' ) do |harness, testable|
           expect(harness.mocks( 'test/test_reader.c' )).to eq( ['mock_widget.h'] )
-          expect(testable.mock_search_paths).to eq( ['build/mocks/test_reader/drivers'] )
+          # The macro's #include resolves as `drivers/mock_widget.h`, reached from the mock root
+          expect(testable.mock_search_paths).to eq( ['build/mocks/test_reader/drivers', 'build/mocks/test_reader'] )
         end
       end
 

data/spec/integration/test_naming_spec.rb

@@ -0,0 +1,198 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# How tests are named, across project layouts with same-named tests (GH #1364). A project's YAML runs through the real
+# configuration pipeline in a temporary project, so test paths and collections come from
+# real globs. A real FilePathUtils names each test, and a real TestBuildSetup prepares its
+# directories, as stage 1 of a build does.
+
+require 'spec_helper'
+require 'configurator_integration_helper'
+require 'ceedling/filesystem/file_path_utils'
+require 'ceedling/filesystem/file_finder'
+require 'ceedling/filesystem/file_finder_helper'
+require 'ceedling/test_invoker/test_build_setup'
+require 'ceedling/test_invoker/test_invoker_types'
+
+describe 'Test naming (integration)' do
+  include ConfiguratorIntegrationHelpers
+
+  # Runs each test of a batch in turn, in place of the thread pool
+  class TestNamingBatchinator
+    def exec(things:, **_options)
+      things.each { |thing| yield thing }
+    end
+  end
+
+  # name => [test paths, `:paths ↳ :test` entries, `:files ↳ :test` entries]
+  TEST_NAMING_LAYOUTS = {
+    'flat and nested under one root' => [%w[test/test_calc.c test/unit/test_calc.c], %w[test/**], []],
+    'the same subdirectory under two roots' => [%w[test/unit/test_calc.c extra/unit/test_calc.c], %w[test/unit/** extra/**], []],
+    'overlapping roots' => [%w[test/test_calc.c test/unit/test_calc.c], %w[test/** test/unit/**], []],
+    'the same layout under two roots' => [%w[test/foo/test_x.c extra/foo/test_x.c], %w[test/** extra/**], []],
+    'a :files test outside every root' => [%w[test/test_calc.c other/test_calc.c], %w[test/**], %w[other/test_calc.c]]
+  }.freeze
+
+  def project_yaml(test_paths, test_files)
+    return <<~YAML
+      :project:
+        :build_root: build
+      :paths:
+        :test: #{test_paths.inspect}
+        :source: [src/**]
+        :include: [src/**]
+      :files:
+        :test: #{test_files.inspect}
+    YAML
+  end
+
+  def project_files(tests)
+    files = { 'src/calc.c' => "int calc(void) { return 1; }\n", 'src/calc.h' => "int calc(void);\n" }
+    tests.each { |test| files[test] = "#include \"unity.h\"\nvoid test_it(void) {}\n" }
+    return files
+  end
+
+  # Stage 1 of a build of `tests`, with real naming and real directories
+  def prepare(configurator, tests)
+    file_wrapper    = FileWrapper.new( loginator: double( 'loginator', log: nil ), verbosinator: double( 'verbosinator', should_output?: false ) )
+    file_path_utils = FilePathUtils.new( configurator: configurator, file_wrapper: file_wrapper )
+
+    collaborators = TestBuildSetup.constructor_keys.to_h { |key| [key, double( key.to_s )] }
+    setup = TestBuildSetup.new( collaborators.merge(
+      configurator: configurator, file_wrapper: file_wrapper, file_path_utils: file_path_utils, batchinator: TestNamingBatchinator.new
+    ) )
+
+    state = TestInvokerTypes::PipelineState.new( tests: tests, testables: {}, context: :test, options: [], lock: Mutex.new )
+    setup.stage_prepare_build_paths( state )
+    return [state, file_path_utils]
+  end
+
+  def finder(configurator, file_path_utils)
+    loginator = double( 'loginator', log: nil )
+    return FileFinder.new(
+      configurator: configurator, file_finder_helper: FileFinderHelper.new( loginator: loginator ), file_path_utils: file_path_utils,
+      file_wrapper: FileWrapper.new( loginator: loginator, verbosinator: double( 'verbosinator', should_output?: false ) ), yaml_wrapper: nil
+    )
+  end
+
+  # Each test's own object resolves to that test, by name and from its object path alone
+  def expect_own_objects_resolve(configurator, state, file_path_utils)
+    finder = finder( configurator, file_path_utils )
+    state.testables.each_value do |testable|
+      object = File.join( testable.paths[:build], File.basename( testable.filepath ).ext( '.o' ) )
+      expect(finder.find_build_input_file( filepath: object, context: :test, test: testable.name )).to eq( testable.filepath )
+      expect(finder.find_build_input_file( filepath: object, context: :test )).to eq( testable.filepath )
+    end
+  end
+
+  TEST_NAMING_LAYOUTS.each do |layout, (tests, test_paths, test_files)|
+    context "with #{layout}" do
+      it 'names each test by its path, inside the build directory, with results where summaries look' do
+        in_temp_project( project_files( tests ) ) do
+          configurator = configure( project_yaml( test_paths, test_files ) )[:configurator]
+          expect(configurator.collection_all_tests).to match_array( tests )
+
+          state, file_path_utils = prepare( configurator, configurator.collection_all_tests )
+
+          expect(state.testables.keys.map( &:to_s )).to match_array( tests.map { |test| test.ext( '' ) } )
+
+          build = File.expand_path( 'build' ) + '/'
+          state.testables.each_value do |testable|
+            testable.paths.each_value { |path| expect(File.expand_path( path )).to start_with( build ) }
+          end
+
+          expected = state.testables.values.map { |testable| file_path_utils.form_pass_results_filepath( testable.paths[:results], testable.filepath ) }
+          expect(file_path_utils.form_pass_results_filelist( configurator.project_test_results_path, tests )).to match_array( expected )
+          expect(expected.uniq.size).to eq( tests.size )
+
+          expect_own_objects_resolve( configurator, state, file_path_utils )
+        end
+      end
+    end
+  end
+
+  # One test's name continues another's, so its directories nest inside the other's
+  context 'with a test directory named like a test beside it' do
+    it "keeps each test's mocks its own" do
+      tests = %w[test/test_foo.c test/test_foo/test_bar.c]
+      in_temp_project( project_files( tests ) ) do
+        configurator = configure( project_yaml( %w[test/**], [] ) )[:configurator]
+        state, file_path_utils = prepare( configurator, configurator.collection_all_tests )
+        expect_own_objects_resolve( configurator, state, file_path_utils )
+
+        mock = "#{configurator.cmock_mock_prefix}widget"
+        state.testables.each_value do |testable|
+          FileUtils.mkdir_p( testable.paths[:mocks] )
+          File.write( File.join( testable.paths[:mocks], "#{mock}.c" ), "\n" )
+        end
+
+        finder = finder( configurator, file_path_utils )
+        state.testables.each_value do |testable|
+          object = File.join( testable.paths[:build], "#{mock}.o" )
+          expect(finder.find_build_input_file( filepath: object, context: :test, test: testable.name )).to eq( File.join( testable.paths[:mocks], "#{mock}.c" ) )
+        end
+      end
+    end
+  end
+
+  context 'with tests outside the project' do
+    def outside_files
+      return project_files( [] ).transform_keys { |path| File.join( 'app', path ) }.merge(
+        'shared/test/unit/test_s.c' => "void test_it(void) {}\n",
+        'other/test_o.c'            => "void test_it(void) {}\n"
+      )
+    end
+
+    it 'keeps their names and directories inside the build directory' do
+      in_temp_project( outside_files ) do
+        Dir.chdir( 'app' ) do
+          configurator = configure( project_yaml( %w[../shared/test/**], %w[../other/test_o.c] ) )[:configurator]
+
+          state, file_path_utils = prepare( configurator, configurator.collection_all_tests )
+
+          expect(state.testables.keys.map( &:to_s )).to match_array( %w[_up_/shared/test/unit/test_s _up_/other/test_o] )
+          expect_own_objects_resolve( configurator, state, file_path_utils )
+          build = File.expand_path( 'build' ) + '/'
+          state.testables.each_value do |testable|
+            testable.paths.each_value { |path| expect(File.expand_path( path )).to start_with( build ) }
+          end
+        end
+      end
+    end
+
+    # A project directory named like the marker a test outside the project is named by keeps
+    # a name of its own
+    it 'names a test below a project directory called `_up_` apart from one above the project' do
+      files = outside_files.merge( 'app/_up_/other/test_o.c' => "void test_it(void) {}\n" )
+
+      in_temp_project( files ) do
+        Dir.chdir( 'app' ) do
+          configurator = configure( project_yaml( %w[../shared/test/** _up_/**], %w[../other/test_o.c] ) )[:configurator]
+
+          state, _file_path_utils = prepare( configurator, ['_up_/other/test_o.c', '../other/test_o.c'] )
+
+          expect(state.testables.keys.map( &:to_s )).to match_array( %w[__up_/other/test_o _up_/other/test_o] )
+        end
+      end
+    end
+
+    it 'stops a build that has two tests sharing one name, naming both' do
+      files = outside_files.merge( 'app/test/test_d.c' => "void test_it(void) {}\n", 'app/test/test_d.cpp' => "void test_it(void) {}\n" )
+
+      in_temp_project( files ) do
+        Dir.chdir( 'app' ) do
+          yaml = project_yaml( %w[test/**], [] ) + ":extension:\n  :source: ['.c', '.cpp']\n"
+          configurator = configure( yaml )[:configurator]
+
+          expect { prepare( configurator, ['test/test_d.c'] ) }.to raise_error( CeedlingException ) { |error|
+            expect(error.message).to include( 'test/test_d.c', 'test/test_d.cpp', '`test/test_d`' )
+          }
+        end
+      end
+    end
+  end
+end