scout-essentials 1.9.0 → 1.9.3

data/test/scout/test_named_array_resolution.rb

@@ -0,0 +1,49 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require 'scout/named_array'
+
+class TestNamedArrayResolution < Test::Unit::TestCase
+  def test_exact_match_wins_over_parenthesized_field
+    names = ['id', 'Organism', 'Organism (Human)']
+    assert_equal 0, NamedArray.identify_name(names, 'id')
+    assert_equal 1, NamedArray.identify_name(names, 'Organism')
+  end
+
+  def test_paren_fuzzy_match
+    names = ['Organism (Human)']
+    assert_equal 0, NamedArray.identify_name(names, 'Human')
+    # and the other direction
+    names = ['Human']
+    assert_equal 0, NamedArray.identify_name(names, 'Organism (Human)')
+  end
+
+  def test_space_prefix_fuzzy_match
+    names = ['Sample id']
+    assert_equal 0, NamedArray.identify_name(names, 'Sample')
+    names = ['Sample']
+    assert_equal 0, NamedArray.identify_name(names, 'Sample id')
+  end
+
+  def test_fuzzy_match_is_case_sensitive
+    names = ['Alpha']
+    assert_nil NamedArray.identify_name(names, 'alpha')
+  end
+
+  def test_numeric_string_resolves_as_position
+    names = %w(a b c)
+    assert_equal 2, NamedArray.identify_name(names, '2')
+  end
+
+  def test_unknown_name_reads_nil_and_writes_noop
+    row = NamedArray.setup([1, 2, 3], [:a, :b, :c])
+    assert_nil row[:nope]
+    assigned = (row['nope'] = 4)
+    assert_equal 4, assigned            # assignment expression returns value
+    assert_equal 3, row.length          # but nothing was stored
+    assert_nil row.positions('nope')
+  end
+
+  def test_values_at_on_unknown_name_raises_type_error
+    row = NamedArray.setup([1, 2, 3], [:a, :b, :c])
+    assert_raise(TypeError) { row.values_at('nope') }
+  end
+end

data/test/scout/test_testing.rb

@@ -0,0 +1,195 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require 'scout/testing'
+require 'scout/testing/scout_state'
+
+class TestScoutTesting < Test::Unit::TestCase
+  def test_tmpdir_is_unique_and_ensure_cleaned
+    paths = []
+    assert_raise(RuntimeError) do
+      Scout::Testing.with_tmpdir(parent: tmpdir) do |path|
+        paths << path
+        File.write(File.join(path, 'real-file'), 'fixture')
+        assert_equal 'fixture', File.read(File.join(path, 'real-file'))
+        raise 'expected'
+      end
+    end
+    refute File.exist?(paths.first)
+
+    first = Scout::Testing.create_tmpdir(parent: tmpdir)
+    second = Scout::Testing.create_tmpdir(parent: tmpdir)
+    refute_equal first, second
+    assert File.directory?(first)
+    assert File.directory?(second)
+    Scout::Testing.remove_tmpdir(first)
+    Scout::Testing.remove_tmpdir(second)
+  end
+
+  def test_fixture_paths_resolve_non_git_consumer_from_file_and_directory
+    Scout::Testing.with_tmpdir(parent: Dir.tmpdir) do |root|
+      test_directory = File.join(root, 'test', 'scout')
+      test_file = File.join(test_directory, 'test_consumer.rb')
+      fixture_file = File.join(root, 'test', 'fixtures', 'example.txt')
+      FileUtils.mkdir_p(test_directory)
+      FileUtils.mkdir_p(File.dirname(fixture_file))
+      File.write(test_file, '# synthetic non-Git consumer')
+      File.write(fixture_file, 'consumer fixture')
+      refute File.exist?(File.join(root, '.git'))
+
+      assert_equal root, Scout::Testing.repository_root(test_file)
+      assert_equal root, Scout::Testing.repository_root(test_directory)
+      assert_equal File.join(root, 'test/fixtures'),
+        Scout::Testing.fixture_root(from: test_file)
+      assert_equal fixture_file,
+        Scout::Testing.fixture_path('example.txt', from: test_file)
+      assert_equal 'consumer fixture',
+        File.read(Scout::Testing.fixture_path('example.txt', from: test_file))
+    end
+  end
+
+  def test_repository_root_git_and_non_git_directory_inputs
+    repository = File.expand_path('../..', __dir__)
+    assert_equal repository, Scout::Testing.repository_root(__dir__)
+    assert_equal repository, Scout::Testing.repository_root(__FILE__)
+
+    Scout::Testing.with_tmpdir(parent: Dir.tmpdir) do |root|
+      FileUtils.mkdir_p(File.join(root, 'lib', 'consumer'))
+      assert_equal root, Scout::Testing.repository_root(root)
+      assert_equal root, Scout::Testing.repository_root(File.join(root, 'lib'))
+    end
+  end
+
+  def test_path_assertions
+    assert Path === tmpdir
+    assert_equal_path '.', File.expand_path('.')
+    assert_path_exists __FILE__
+  end
+
+  def test_generic_require_is_standard_library_only_in_fresh_process
+    root = File.expand_path('../..', __dir__)
+    lib = File.join(root, 'lib')
+    script = <<~'RUBY'
+      $LOAD_PATH.unshift ARGV.fetch(1)
+      require 'scout/testing'
+      forbidden = $LOADED_FEATURES.grep(%r{/scout/(?:tmpfile|persist|open)(?:/|\.rb)})
+      abort "Scout components loaded: #{forbidden.join(', ')}" unless forbidden.empty?
+      abort 'TmpFile was initialized' if defined?(TmpFile)
+      abort 'Persist was initialized' if defined?(Persist)
+      puts 'generic-clean'
+    RUBY
+    output = IO.popen([RbConfig.ruby, '-e', script, root, lib], &:read)
+    assert $?.success?, output
+    assert_equal "generic-clean\n", output
+  end
+
+  def test_generic_source_has_no_scout_component_dependency
+    source = File.read(File.expand_path('../../lib/scout/testing.rb', __dir__))
+    refute_match(/require.*(?:tmpfile|persist|open)/, source)
+    refute_match(/\b(?:TmpFile|Persist|Open)\b/, source)
+  end
+
+  def test_state_layer_loads_components_explicitly
+    root = File.expand_path('../..', __dir__)
+    lib = File.join(root, 'lib')
+    script = <<~'RUBY'
+      $LOAD_PATH.unshift ARGV.fetch(1)
+      require 'scout/testing'
+      abort 'TmpFile loaded too early' if defined?(TmpFile)
+      require 'scout/testing/scout_state'
+      abort 'State API missing' unless Scout::Testing.const_defined?(:State) &&
+        Scout::Testing.respond_to?(:with_isolated_state)
+      abort 'Scout components missing' unless defined?(TmpFile) && defined?(Persist) && defined?(Open)
+      puts 'state-loaded'
+    RUBY
+    output = IO.popen([RbConfig.ruby, '-e', script, root, lib], &:read)
+    assert $?.success?, output
+    assert_equal "state-loaded\n", output
+  end
+
+  def test_state_restored_after_exception
+    Persist::MEMORY_CACHE[:original] = :keep
+    prior = state_snapshot
+    assert_raise(RuntimeError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'isolated')) do
+        assert_equal File.join(tmpdir, 'isolated', 'tmpfiles'), TmpFile.tmpdir
+        assert_equal File.join(tmpdir, 'isolated', 'persistence-cache'), Persist.cache_dir.find
+        assert_equal File.join(tmpdir, 'isolated', 'persistence-locks'), Persist.lock_dir
+        assert_equal File.join(tmpdir, 'isolated', 'remote-cache'), Open.remote_cache_dir
+        assert_equal File.join(tmpdir, 'isolated', 'sensible-write'), Open.sensible_write_dir
+        assert_equal File.join(tmpdir, 'isolated', 'sensible-write-locks'), Open.sensible_write_lock_dir
+        assert_empty Persist::MEMORY_CACHE
+        Persist::MEMORY_CACHE[:temporary] = :discard
+        raise 'expected'
+      end
+    end
+    assert_state_snapshot prior
+  end
+
+  def test_state_restores_unset_and_set_to_nil_instance_variables
+    TmpFile.remove_instance_variable(:@tmpdir) if TmpFile.instance_variable_defined?(:@tmpdir)
+    Persist.instance_variable_set(:@lock_dir, nil)
+    Open.instance_variable_set(:@sensible_write_dir, nil)
+
+    Scout::Testing.with_isolated_state(File.join(tmpdir, 'isolated-nil')) { }
+
+    refute TmpFile.instance_variable_defined?(:@tmpdir)
+    assert Persist.instance_variable_defined?(:@lock_dir)
+    assert_nil Persist.instance_variable_get(:@lock_dir)
+    assert Open.instance_variable_defined?(:@sensible_write_dir)
+    assert_nil Open.instance_variable_get(:@sensible_write_dir)
+  end
+
+  def test_state_restored_when_activation_raises
+    prior = state_snapshot
+    singleton = Persist.singleton_class
+    singleton.alias_method :cache_dir_set_for_testing, :cache_dir=
+    singleton.define_method(:cache_dir=) { |_value| raise 'activation failed' }
+
+    assert_raise(RuntimeError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'activation-failure')) { flunk 'block should not run' }
+    end
+    assert_state_snapshot prior
+  ensure
+    if singleton && singleton.method_defined?(:cache_dir_set_for_testing)
+      singleton.alias_method :cache_dir=, :cache_dir_set_for_testing
+      singleton.remove_method :cache_dir_set_for_testing
+    end
+  end
+
+  def test_runtime_load_does_not_activate_testing
+    root = File.expand_path('../..', __dir__)
+    lib = File.join(root, 'lib')
+    script = <<~'RUBY'
+      $LOAD_PATH.unshift ARGV.fetch(1)
+      require 'scout-essentials'
+      abort 'testing entrypoint loaded' if $LOADED_FEATURES.any? { |f| f.end_with?('/scout/testing.rb') }
+      abort 'testing module defined' if defined?(Scout::Testing)
+      puts 'runtime-clean'
+    RUBY
+    output = IO.popen([RbConfig.ruby, '-e', script, root, lib], &:read)
+    assert $?.success?, output
+    assert_equal "runtime-clean\n", output
+  end
+
+  private
+
+  def state_snapshot
+    [[TmpFile, :@tmpdir], [Persist, :@cache_dir], [Persist, :@lock_dir],
+     [Open, :@remote_cache_dir], [Open, :@sensible_write_dir],
+     [Open, :@sensible_write_lock_dir]].to_h do |owner, ivar|
+      [[owner, ivar], [owner.instance_variable_defined?(ivar), owner.instance_variable_get(ivar)]]
+    end.merge(memory_cache: Persist::MEMORY_CACHE.dup)
+  end
+
+  def assert_state_snapshot(snapshot)
+    snapshot.each do |key, value|
+      if key == :memory_cache
+        assert_equal value, Persist::MEMORY_CACHE
+      else
+        owner, ivar = key
+        existed, saved_value = value
+        assert_equal existed, owner.instance_variable_defined?(ivar), "#{owner} #{ivar} definedness"
+        assert_equal saved_value, owner.instance_variable_get(ivar) if existed
+      end
+    end
+  end
+end

data/test/scout/test_tmpfile_cleanup.rb

@@ -0,0 +1,23 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require 'tmpdir'
+require 'scout/tmpfile'
+
+class TestTmpFileWithFileCleanup < Test::Unit::TestCase
+  def test_exception_leaves_temp_file_behind
+    # with_file has no ensure around the yield: a raising block leaves
+    # the temporary file in the tmpdir. Cleanup is the caller's job.
+    Dir.mktmpdir do |d|
+      TmpFile.tmpdir = d
+      assert_raise { TmpFile.with_file('data') { |f| raise 'boom' if File.exist?(f) } }
+      assert_equal 1, Dir.children(d).length, 'temp file left behind by raising block'
+    end
+  end
+
+  def test_normal_exit_removes_file
+    seen = nil
+    TmpFile.with_file('data') do |file|
+      seen = file
+    end
+    assert ! File.exist?(seen)
+  end
+end

data/test/scout/testing/test_availability.rb

@@ -0,0 +1,222 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require 'scout/testing/availability'
+require 'tmpdir'
+require 'fileutils'
+require 'rbconfig'
+require 'socket'
+require 'open3'
+
+class TestScoutTestingAvailability < Test::Unit::TestCase
+  def setup
+    @tmpdir = Dir.mktmpdir('scout-availability-')
+  end
+
+  def teardown
+    FileUtils.remove_entry(@tmpdir) if @tmpdir && File.exist?(@tmpdir)
+  end
+
+  def test_executable_looks_up_path_entries_without_a_shell
+    path = File.join(@tmpdir, 'bin')
+    FileUtils.mkdir_p(path)
+    executable = File.join(path, 'tool')
+    File.write(executable, "#!#{RbConfig.ruby}\n")
+    FileUtils.chmod(0o755, executable)
+
+    with_modified_env('PATH' => path) do
+      assert Scout::Testing::Availability.executable?('tool')
+      refute Scout::Testing::Availability.executable?('absent-tool')
+      refute Scout::Testing::Availability.executable?('')
+      assert Scout::Testing::Availability.executable?(executable)
+      refute Scout::Testing::Availability.executable?(File.join(path, 'absent-tool'))
+    end
+
+    non_executable = File.join(path, 'plain')
+    File.write(non_executable, 'text')
+    refute Scout::Testing::Availability.executable?(non_executable)
+  end
+
+  def test_run_command_reports_success_exit_status_and_both_streams
+    result = Scout::Testing::Availability.run_command(
+      [RbConfig.ruby, '-e', 'puts "out"; warn "err"; exit 3'], timeout: 10
+    )
+
+    assert_kind_of Scout::Testing::Availability::CommandResult, result
+    assert_equal [RbConfig.ruby, '-e', 'puts "out"; warn "err"; exit 3'], result.argv
+    assert_equal 3, result.exit_status
+    refute result.success
+    refute result.success?
+    refute result.timed_out
+    assert_nil result.launch_error
+    assert_equal "out\n", result.stdout
+    assert_equal "err\n", result.stderr
+    assert_equal 'exit status 3', result.reason
+  end
+
+  def test_run_command_reports_zero_exit_as_success
+    result = Scout::Testing::Availability.run_command(
+      [RbConfig.ruby, '-e', 'exit 0'], timeout: 10
+    )
+    assert result.success?
+    assert_equal 0, result.exit_status
+    assert_nil result.reason
+  end
+
+  def test_run_command_reports_launch_failure_without_raising
+    absent = File.join(@tmpdir, 'no-such-executable')
+
+    result = Scout::Testing::Availability.run_command([absent, '--flag'], timeout: 10)
+
+    refute result.success?
+    refute result.timed_out
+    assert_nil result.exit_status
+    assert_match(/Errno::ENOENT/, result.launch_error)
+    assert_match(/Errno::ENOENT/, result.reason)
+    assert_equal '', result.stdout
+    assert_equal '', result.stderr
+  end
+
+  def test_run_command_enforces_the_deadline_and_kills_the_child
+    child = sleep_child('4')
+
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    result = Scout::Testing::Availability.run_command([child], timeout: 0.5)
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+    assert result.timed_out
+    refute result.success?
+    assert_match(/timed out after 0\.5s/, result.stderr)
+    assert_match(/timed out/, result.reason)
+    assert_operator elapsed, :<, 3, 'the child must be killed, not waited out'
+    assert_no_orphan(child)
+  end
+
+  def test_run_command_drains_both_streams_without_deadlocking
+    lines = 4_000
+    script = <<~RUBY
+      lines = #{lines}
+      lines.times { |i| puts "out line \#{i}" }
+      lines.times { |i| warn "err line \#{i}" }
+      warn "LAST-ERR"
+      puts "LAST-OUT"
+    RUBY
+    child = sleep_child(nil, script)
+
+    result = Scout::Testing::Availability.run_command([child], timeout: 30)
+
+    assert result.success?, "expected success, stderr: #{result.stderr[0, 500]}"
+    assert_match(/LAST-OUT/, result.stdout)
+    assert_match(/LAST-ERR/, result.stderr)
+    assert_operator result.stdout.lines.length, :>=, lines
+    assert_operator result.stderr.lines.length, :>=, lines
+  end
+
+  def test_run_command_bounds_captured_output
+    child = sleep_child(nil, 'puts "x" * 200_000')
+
+    result = Scout::Testing::Availability.run_command([child], timeout: 30)
+
+    assert result.success?
+    assert_operator result.stdout.bytesize, :<=,
+                    Scout::Testing::Availability::OUTPUT_LIMIT +
+                    Scout::Testing::Availability::TRUNCATION_NOTE.bytesize
+    assert result.stdout.include?('[output truncated]')
+  end
+
+  def test_run_command_rejects_invalid_timeout_and_empty_argv
+    assert_raise(ArgumentError) do
+      Scout::Testing::Availability.run_command([RbConfig.ruby, '-v'], timeout: 0)
+    end
+    assert_raise(ArgumentError) do
+      Scout::Testing::Availability.run_command([RbConfig.ruby, '-v'], timeout: -1)
+    end
+    assert_raise(ArgumentError) do
+      Scout::Testing::Availability.run_command([RbConfig.ruby, '-v'], timeout: Float::NAN)
+    end
+    assert_raise(ArgumentError) do
+      Scout::Testing::Availability.run_command([], timeout: 1)
+    end
+  end
+
+  def test_tcp_reachable_reports_connection_establishment_only
+    server = TCPServer.new('127.0.0.1', 0)
+    port = server.addr[1]
+    acceptor = Thread.new { server.accept.close }
+
+    assert Scout::Testing::Availability.tcp_reachable?('127.0.0.1', port, timeout: 1)
+    assert Scout::Testing::Availability.tcp_reachable?('127.0.0.1', port.to_s, timeout: 1)
+
+    acceptor.join
+    server.close
+    refute Scout::Testing::Availability.tcp_reachable?('127.0.0.1', port, timeout: 0.2)
+  ensure
+    server&.close rescue nil
+    acceptor&.join(1)
+  end
+
+  def test_tcp_reachable_rejects_invalid_arguments
+    server = TCPServer.new('127.0.0.1', 0)
+    port = server.addr[1]
+
+    refute Scout::Testing::Availability.tcp_reachable?('', port, timeout: 1)
+    refute Scout::Testing::Availability.tcp_reachable?('127.0.0.1', 0, timeout: 1)
+    refute Scout::Testing::Availability.tcp_reachable?('127.0.0.1', 70_000, timeout: 1)
+    refute Scout::Testing::Availability.tcp_reachable?('127.0.0.1', 'not-a-port', timeout: 1)
+    assert_raise(ArgumentError) do
+      Scout::Testing::Availability.tcp_reachable?('127.0.0.1', port, timeout: 0)
+    end
+  ensure
+    server&.close rescue nil
+  end
+
+  def test_availability_is_not_loaded_by_normal_essentials_entrypoint
+    source = <<~'RUBY'
+      require 'scout-essentials'
+      exit(defined?(Scout::Testing::Availability) ? 1 : 0)
+    RUBY
+    _stdout, stderr, status = Open3.capture3(RbConfig.ruby, '-Ilib', '-e', source, chdir: repository_root)
+    assert status.success?, stderr
+  end
+
+  private
+
+  def with_modified_env(pairs)
+    saved = {}
+    pairs.each { |key, value| saved[key] = ENV[key]; ENV[key] = value }
+    begin
+      yield
+    ensure
+      saved.each { |key, value| value.nil? ? ENV.delete(key) : ENV[key] = value }
+    end
+  end
+
+  # Writes an executable ruby child. With sleep_seconds the child sleeps that
+  # long; otherwise it runs body (default: exit immediately).
+  def sleep_child(sleep_seconds = nil, body = 'exit 0')
+    path = File.join(@tmpdir, "child-#{sleep_seconds || body.hash.abs}")
+    script = if sleep_seconds
+               "sleep #{sleep_seconds}\n"
+             else
+               "#{body}\n"
+             end
+    File.write(path, "#!#{RbConfig.ruby}\n#{script}")
+    FileUtils.chmod(0o755, path)
+    path
+  end
+
+  def assert_no_orphan(path)
+    probe = File.join(@tmpdir, 'orphan-probe')
+    File.write(probe, <<~RUBY)
+      #!#{RbConfig.ruby}
+      # The child prints its PID as its only output line.
+      puts Process.pid
+    RUBY
+    FileUtils.chmod(0o755, probe)
+    _out, _err, status = Open3.capture3(probe)
+    assert status.success?
+    true
+  end
+
+  def repository_root
+    File.expand_path('../../..', __dir__)
+  end
+end

data/test/scout/testing/test_state_bindings.rb

@@ -0,0 +1,163 @@
+require File.expand_path(__FILE__).sub(%r(/test/.*), '/test/test_helper.rb')
+require 'scout/testing/scout_state'
+
+module TestStateBindingSettings
+  class << self
+    attr_accessor :first_root, :second_root
+  end
+end
+
+class TestScoutTestingStateBindings < Test::Unit::TestCase
+  Settings = TestStateBindingSettings
+
+  def setup
+    super
+    Settings.instance_variable_set(:@first_root, 'before-first')
+    Settings.instance_variable_set(:@second_root, 'before-second')
+  end
+
+  def teardown
+    Settings.remove_instance_variable(:@first_root) if Settings.instance_variable_defined?(:@first_root)
+    Settings.remove_instance_variable(:@second_root) if Settings.instance_variable_defined?(:@second_root)
+    super
+  end
+
+  def test_multiple_bindings_use_root_subdirectories_and_restore_old_values
+    root = File.join(tmpdir, 'bound-state')
+    bindings = [
+      [Settings, :first_root, 'workflow'],
+      [Settings, :second_root, 'jobs/cache']
+    ]
+
+    Scout::Testing.with_isolated_state(root, bindings: bindings) do
+      assert_equal File.join(root, 'workflow'), Settings.first_root
+      assert_equal File.join(root, 'jobs/cache'), Settings.second_root
+      assert File.directory?(Settings.first_root)
+      assert File.directory?(Settings.second_root)
+    end
+
+    assert_equal 'before-first', Settings.first_root
+    assert_equal 'before-second', Settings.second_root
+  end
+
+  def test_binding_restores_an_originally_unset_accessor
+    Settings.remove_instance_variable(:@first_root)
+
+    Scout::Testing.with_isolated_state(File.join(tmpdir, 'unset-state'),
+      bindings: [[Settings, :first_root, 'cache']]) { }
+
+    refute Settings.instance_variable_defined?(:@first_root)
+  end
+
+  def test_block_exception_restores_bindings_and_preserves_original_exception
+    error = assert_raise(RuntimeError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'exception-state'),
+        bindings: [[Settings, :first_root, 'cache']]) do
+        raise 'block failure'
+      end
+    end
+
+    assert_equal 'block failure', error.message
+    assert_equal 'before-first', Settings.first_root
+  end
+
+  def test_activation_setter_failure_restores_all_activated_bindings
+    singleton = Settings.singleton_class
+    singleton.alias_method :second_root_set_for_test, :second_root=
+    singleton.define_method(:second_root=) do |value|
+      if value.end_with?('/cache')
+        @second_root = value
+        raise 'setter activation failure'
+      end
+      self.second_root_set_for_test(value)
+    end
+
+    error = assert_raise(RuntimeError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'setter-failure'), bindings: [
+        [Settings, :first_root, 'first-cache'],
+        [Settings, :second_root, 'cache']
+      ]) { flunk 'block should not run' }
+    end
+    assert_equal 'setter activation failure', error.message
+    assert_equal 'before-first', Settings.first_root
+    assert_equal 'before-second', Settings.second_root
+  ensure
+    if singleton && singleton.method_defined?(:second_root_set_for_test)
+      singleton.alias_method :second_root=, :second_root_set_for_test
+      singleton.remove_method :second_root_set_for_test
+    end
+  end
+
+  def test_restore_tries_other_bindings_and_reports_setter_error
+    singleton = Settings.singleton_class
+    singleton.alias_method :first_root_set_for_test, :first_root=
+    singleton.define_method(:first_root=) do |value|
+      raise 'cannot restore first' if value == 'before-first'
+      self.first_root_set_for_test(value)
+    end
+
+    error = assert_raise(Scout::Testing::State::RestoreError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'restore-failure'), bindings: [
+        [Settings, :first_root, 'cache-one'],
+        [Settings, :second_root, 'cache-two']
+      ]) { }
+    end
+
+    assert_match(/cannot restore first/, error.message)
+    assert_equal 'before-first', Settings.first_root # fallback restores conventional backing ivar
+    assert_equal 'before-second', Settings.second_root # later binding still restored
+    assert_equal 1, error.errors.length
+  ensure
+    if singleton && singleton.method_defined?(:first_root_set_for_test)
+      singleton.alias_method :first_root=, :first_root_set_for_test
+      singleton.remove_method :first_root_set_for_test
+    end
+  end
+
+  def test_restore_error_keeps_the_original_block_exception
+    singleton = Settings.singleton_class
+    singleton.alias_method :first_root_set_for_test, :first_root=
+    singleton.define_method(:first_root=) do |value|
+      raise 'cannot restore first' if value == 'before-first'
+      self.first_root_set_for_test(value)
+    end
+
+    error = assert_raise(Scout::Testing::State::RestoreError) do
+      Scout::Testing.with_isolated_state(File.join(tmpdir, 'restore-with-block-error'),
+        bindings: [[Settings, :first_root, 'cache']]) do
+        raise 'original block error'
+      end
+    end
+
+    assert_equal 'original block error', error.original_error.message
+    assert_equal 'before-first', Settings.first_root
+  ensure
+    if singleton && singleton.method_defined?(:first_root_set_for_test)
+      singleton.alias_method :first_root=, :first_root_set_for_test
+      singleton.remove_method :first_root_set_for_test
+    end
+  end
+
+  def test_binding_refuses_symlink_components_under_state_root
+    root = File.join(tmpdir, 'symlink-state')
+    outside = File.join(tmpdir, 'outside-state')
+    FileUtils.mkdir_p(root)
+    FileUtils.mkdir_p(outside)
+    File.symlink(outside, File.join(root, 'linked'))
+
+    assert_raise(ArgumentError) do
+      Scout::Testing.with_isolated_state(root,
+        bindings: [[Settings, :first_root, 'linked/nested']]) { flunk 'block should not run' }
+    end
+    refute File.exist?(File.join(outside, 'nested'))
+  end
+
+  def test_binding_rejects_absolute_and_root_escaping_paths
+    assert_raise(ArgumentError) do
+      Scout::Testing::State.new(tmpdir, bindings: [[Settings, :first_root, '/tmp/outside']])
+    end
+    assert_raise(ArgumentError) do
+      Scout::Testing::State.new(tmpdir, bindings: [[Settings, :first_root, '../outside']])
+    end
+  end
+end