expect-pty 0.2.0

data/test/support/interact_probe.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "script_probe"
+
+module InteractProbe
+  ESCAPE = "\x1d".b.freeze
+  TAIL = "LOCAL_ONLY_TAIL".b.freeze
+
+  def self.configuration(session)
+    state = session.stty
+    return state unless RUBY_PLATFORM.include?("darwin")
+
+    # PENDIN is a transient Darwin kernel state, not a termios configuration.
+    state.sub(/lflag=([0-9a-f]+)/) { "lflag=#{(Regexp.last_match(1).to_i(16) & ~0x20000000).to_s(16)}" }
+  end
+
+  def self.settings(session)
+    [session.listeners, session.log_stdout, session.log_listeners, session.raw_terminal?,
+     session.instance_variable_get(:@sequences).dup]
+  end
+
+  def self.prepare(session, echo: false)
+    # The remote tty needs ISIG for Ctrl-C to reach its foreground process.
+    # Manual interaction needs remote echo because the local input is raw.
+    session.write("stty sane #{echo ? "echo" : "-echo"}; set +o emacs; set +o vi\n")
+    ScriptProbe.check(session.expect(ScriptProbe::PROMPT, timeout: 5), "terminal setup did not return to shell")
+    session.clear_buffer
+  end
+
+  # A real local terminal slave is passed to interact; its master acts as a
+  # keyboard/screen. Only interact reads the remote session during handoff.
+  def self.verify(session, user:)
+    master, slave = PTY.open
+    source = Expect.open(slave)
+    screen = Expect.open(master, write_timeout: 3)
+    source.on_sequence("ORIGINAL_ESCAPE") { false }
+    source.log_listeners = false
+    source.log_stdout = false
+    terminal_state = configuration(source)
+    remote_state = configuration(session)
+    source_settings = settings(source)
+    remote_settings = settings(session)
+    results = []
+    checks = []
+
+    run_cycle = lambda do |number, &actions|
+      nonce = SecureRandom.hex(8)
+      marker = "HANDOFF_#{nonce}"
+      session.write("printf '\\n%s%s\\n' 'HANDOFF_' '#{nonce}'\n")
+      worker = Thread.new do
+        ScriptProbe.check(screen.expect(/#{Regexp.escape(marker)}\r?\n/, timeout: 5),
+                          "handoff output did not reach local terminal")
+        ScriptProbe.check(screen.expect(ScriptProbe::PROMPT, timeout: 5), "handoff prompt missing")
+        ScriptProbe.check(!slave.echo?, "local input terminal did not disable echo")
+        runner = ScriptProbe::Runner.new(screen)
+        actions.call(runner)
+        screen.write(ESCAPE + TAIL)
+        runner.results
+      rescue Exception # rubocop:disable Lint/RescueException -- Clean up terminal drivers even on Interrupt or SystemExit.
+        begin
+          screen.write(ESCAPE)
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+      worker.report_on_exception = false
+      begin
+        returned = session.interact(input: source, escape: ESCAPE, output: slave, timeout: 20)
+        ScriptProbe.check(worker.join(2), "keyboard driver did not finish")
+        results.concat(worker.value)
+        ScriptProbe.check(returned.equal?(source), "interact did not return on the local escape")
+        ScriptProbe.check(source.clear_buffer == TAIL, "escape tail was lost or forwarded to remote")
+        ScriptProbe.check(session.alive?, "local escape closed the remote process")
+        ScriptProbe.check(configuration(source) == terminal_state, "local terminal settings were not restored")
+        ScriptProbe.check(configuration(session) == remote_state,
+                          "remote transport terminal settings were not restored")
+        ScriptProbe.check(settings(source) == source_settings, "local groups/flags/escape handlers were not restored")
+        ScriptProbe.check(settings(session) == remote_settings, "remote groups/flags/escape handlers were not restored")
+        checks << "cycle_#{number}_escape_tail_and_restore"
+      ensure
+        worker.kill.join if worker.alive?
+      end
+    end
+
+    run_cycle.call(1) do |runner|
+      runner.run("interactive_identity", "printf 'USER='; id -un; test -t 0 && printf 'TTY_OK\\n'",
+                 expected_status: 0, expected_output: "USER=#{user}\nTTY_OK\n")
+      runner.run_file(
+        File.join(ScriptProbe::FIXTURES, "02_output.sh"),
+        expected_status: 0,
+        expected_output: "STDOUT_FIRST\nSTDERR_SECOND\n中文输出：日志验证\nSTDOUT_LAST\n"
+      )
+      nonce = SecureRandom.hex(8)
+      # An actual foreground shell handles the forwarded Ctrl-C. Readiness is
+      # acknowledged before sending the control byte, without a timing guess.
+      script = "trap 'printf \"INT_HANDLED_#{nonce}\\n\"; exit 0' INT; " \
+               "printf 'INT_READY_#{nonce}\\n'; while :; do sleep 1; done"
+      screen.write("/bin/sh -c #{Shellwords.escape(script)}\n")
+      ScriptProbe.check(screen.expect(/INT_READY_#{nonce}\r?\n/, timeout: 5), "foreground command did not become ready")
+      screen.write("\x03")
+      ScriptProbe.check(screen.expect(/INT_HANDLED_#{nonce}\r?\n/, timeout: 5),
+                        "Ctrl-C did not reach remote foreground process")
+      ScriptProbe.check(screen.expect(ScriptProbe::PROMPT, timeout: 5), "shell did not recover after Ctrl-C")
+      checks << "ctrl_c_forwarded_to_remote"
+    end
+
+    resumed = ScriptProbe::Runner.new(session)
+    resumed.run("expect_after_interact", "printf 'AUTOMATION_RESUMED\\n'", expected_status: 0,
+                                                                           expected_output: "AUTOMATION_RESUMED\n")
+    results.concat(resumed.results)
+    run_cycle.call(2) do |runner|
+      runner.run("interact_again", "printf 'SECOND_HANDOFF_OK\\n'", expected_status: 0,
+                                                                    expected_output: "SECOND_HANDOFF_OK\n")
+    end
+    checks.push("keyboard_to_remote", "remote_to_screen", "utf8_stdout_stderr",
+                "raw_mode_during_interact", "expect_resume", "reenter_interact")
+    { cases: results, checks: checks,
+      local_tty: slave.path, local_terminal_restored: true, transport_terminal_restored: true }
+  ensure
+    source&.close
+    screen&.close
+    [master, slave].compact.each { |io| io.close unless io.closed? }
+  end
+end

data/test/support/kibitz_probe.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative "interact_probe"
+
+# Drive the actual host and join CLIs through two independent local terminals.
+# No Minitest dependency, SSH service, password, or external user is needed.
+module KibitzProbe
+  EXAMPLE = File.expand_path("../../examples/kibitz/kibitz.rb", __dir__)
+
+  class Pair
+    attr_reader :host, :guest, :socket_path, :log_path
+
+    def initialize(directory, noproc: false, host_flags: [], guest_flags: [])
+      @sessions = []
+      @terminal_modes = {}
+      @log_path = File.join(directory, "session.log")
+      command = noproc ? ["--noproc"] : ["--", "env", "ENV=", "PS1=#{ScriptProbe::PROMPT}", "LC_ALL=C", "/bin/sh", "-i"]
+      @host = spawn_cli("--timeout", "15", "--log", log_path, *host_flags, *command)
+      invitation = host.expect_result(%r{--join (/tmp/expect-kibitz-[^\r\n ]+/peer\.sock)}, timeout: 5)
+      ScriptProbe.check(invitation.matched?, "host did not print the join command")
+      @socket_path = invitation.captures.first
+      ScriptProbe.check(File.stat(File.dirname(socket_path)).mode & 0o777 == 0o700, "socket directory is not private")
+      ScriptProbe.check(File.stat(socket_path).mode & 0o777 == 0o600, "socket is not private")
+      @guest = spawn_cli("--join", socket_path, "--timeout", "15", *guest_flags)
+      [host, guest].each { |terminal| expect(terminal, /Kibitz connected\.[^\r\n]*\r?\n/) }
+      ScriptProbe.check(!host.to_io.echo? && !guest.to_io.echo?, "connected banner preceded terminal readiness")
+    rescue Exception # rubocop:disable Lint/RescueException -- Clean up terminal drivers even on Interrupt or SystemExit.
+      close
+      raise
+    end
+
+    def spawn_cli(*)
+      terminal = Expect.new(log_stdout: false, write_timeout: 3)
+      @sessions << terminal
+      @terminal_modes[terminal] = InteractProbe.configuration(terminal)
+      terminal.spawn(RbConfig.ruby, EXAMPLE, *)
+      terminal
+    end
+
+    def expect(terminal, pattern)
+      result = terminal.expect_result(pattern, timeout: 5)
+      ScriptProbe.check(result.matched?,
+                        "#{terminal.equal?(host) ? "host" : "guest"} missing #{pattern.inspect} (#{result.error})")
+      result
+    end
+
+    def both(pattern)
+      [host, guest].map { |terminal| expect(terminal, pattern) }
+    end
+
+    def prepare_shell
+      ScriptProbe::Runner.new(host).ready!
+      host.write("printf '\\n%s%s\\n' 'KIBITZ_' 'READY'\n")
+      both(/\r?\nKIBITZ_READY\r?\n/)
+      both(ScriptProbe::PROMPT)
+    end
+
+    def command(terminal, command, output)
+      terminal.write(command, "\n")
+      both(output)
+      both(ScriptProbe::PROMPT)
+    end
+
+    def finish!(expected_host_status: 0)
+      [host, guest].each do |terminal|
+        result = terminal.expect_result(:eof, timeout: 5)
+        ScriptProbe.check(result.eof?, "kibitz did not reach EOF")
+        status = terminal.wait(timeout: 2)
+        expected = terminal.equal?(host) ? expected_host_status : 0
+        ScriptProbe.check(status && status.exitstatus == expected,
+                          "kibitz exit status was #{status&.exitstatus.inspect}, expected #{expected}")
+        ScriptProbe.check(InteractProbe.configuration(terminal) == @terminal_modes.fetch(terminal),
+                          "terminal mode was not restored")
+      end
+      ScriptProbe.check(!File.exist?(File.dirname(socket_path)), "socket directory was not cleaned up")
+      ScriptProbe.check(File.stat(log_path).mode & 0o777 == 0o600, "log permissions changed")
+      self
+    end
+
+    def close
+      @sessions&.reverse_each(&:close)
+    end
+  end
+
+  def self.shared_shell(directory)
+    pair = Pair.new(directory)
+    # With local terminals raw, the process's terminal supplies typed echo.
+    pair.both(ScriptProbe::PROMPT)
+    pair.host.write("printf 'VISIBLE_TYPING\\n'")
+    pair.both("printf 'VISIBLE_TYPING\\n'")
+    pair.host.write("\n")
+    pair.both(/\r?\nVISIBLE_TYPING\r?\n/)
+    pair.both(ScriptProbe::PROMPT)
+    # ready! expects an outstanding prompt; use a fresh one after the echo check.
+    pair.host.write("\n")
+    pair.prepare_shell
+    pair.command(pair.host, "shared_value=42; printf 'HOST_SET\\n'", /HOST_SET\r?\n/)
+    pair.command(pair.guest, "printf 'SHARED=%s\\n' \"$shared_value\"", /SHARED=42\r?\n/)
+    pair.command(pair.guest, "printf '中文输出\\n'; printf 'GUEST_STDERR\\n' >&2", /中文输出\r?\nGUEST_STDERR\r?\n/)
+    pair.command(pair.host, "/bin/sh -c 'exit 7'; printf 'RECOVERED=%s\\n' \"$?\"", /RECOVERED=7\r?\n/)
+    script = "trap 'printf \"INT_HANDLED\\n\"; exit 0' INT; printf 'INT_READY\\n'; while :; do sleep 1; done"
+    pair.host.write("/bin/sh -c #{Shellwords.escape(script)}\n")
+    pair.both(/INT_READY\r?\n/)
+    pair.guest.write("\x03")
+    pair.both(/INT_HANDLED\r?\n/)
+    pair.both(ScriptProbe::PROMPT)
+    pair.guest.write("printf 'FINAL_TAIL\\n'; exit 0\n")
+    pair.both(/FINAL_TAIL\r?\n/)
+    pair.finish!
+    log = ScriptProbe.normalize(File.binread(pair.log_path))
+    %w[HOST_SET SHARED=42 GUEST_STDERR RECOVERED=7 INT_READY INT_HANDLED FINAL_TAIL].each do |line|
+      # With echo disabled the output can follow a prompt on the same line.
+      ScriptProbe.check(log.scan("#{line}\n").length == 1, "#{line} missing or duplicated in log")
+    end
+    { name: "shared_shell", passed: true,
+      checks: %w[visible_typing both_keyboards shared_shell_state broadcast_stdout_stderr utf8 nonzero_recovery
+                 guest_ctrl_c process_eof final_tail unique_log terminal_restore socket_cleanup] }
+  ensure
+    pair&.close
+  end
+
+  def self.direct(directory, ending: :host)
+    custom = ending == :host ? ["--escape", "STOP"] : []
+    pair = Pair.new(directory, noproc: true, host_flags: custom)
+    pair.host.write("HOST_MESSAGE")
+    pair.expect(pair.guest, "HOST_MESSAGE")
+    ScriptProbe.check(pair.host.expect("HOST_MESSAGE", timeout: 0.02).nil?, "noproc echoed the sender's input")
+    pair.guest.write("中文回信")
+    pair.expect(pair.host, "中文回信")
+    ScriptProbe.check(pair.guest.expect("中文回信", timeout: 0.02).nil?, "noproc echoed the guest's input")
+    if ending == :host
+      pair.host.write("prefixST")
+      pair.expect(pair.guest, "prefix")
+      ScriptProbe.check(pair.guest.expect("ST", timeout: 0.02).nil?, "split escape prefix leaked to peer")
+      pair.host.write("OPLOCAL_TAIL")
+    else
+      pair.guest.write(InteractProbe::ESCAPE)
+    end
+    pair.finish!
+    ScriptProbe.check(!pair.guest.before.include?("LOCAL_TAIL") && !pair.guest.before.include?("STOP"),
+                      "local escape leaked to peer")
+    { name: "noproc_#{ending}_escape", passed: true,
+      checks: %w[two_way_bytes utf8 no_local_echo escape peer_eof terminal_restore socket_cleanup] }
+  ensure
+    pair&.close
+  end
+
+  def self.noescape(directory)
+    pair = Pair.new(directory, noproc: true, host_flags: ["--noescape"])
+    pair.host.write("before\x1dafter")
+    pair.expect(pair.guest, "before\x1dafter")
+    pair.guest.write(InteractProbe::ESCAPE)
+    pair.finish!
+    { name: "noescape", passed: true, checks: %w[control_byte_forwarded peer_eof terminal_restore socket_cleanup] }
+  ensure
+    pair&.close
+  end
+
+  def self.process_failure(directory)
+    pair = Pair.new(directory)
+    pair.prepare_shell
+    pair.host.write("exit 7\n")
+    pair.finish!(expected_host_status: 7)
+    { name: "process_failure", passed: true, checks: %w[nonzero_exit_status peer_eof terminal_restore socket_cleanup] }
+  ensure
+    pair&.close
+  end
+
+  def self.relay_timeout(directory)
+    pair = Pair.new(directory, noproc: true, host_flags: ["--timeout", "1"])
+    pair.finish!(expected_host_status: 1)
+    ScriptProbe.check(pair.host.before.include?("Kibitz ended (timeout)."), "relay did not report its timeout")
+    { name: "relay_timeout", passed: true, checks: %w[timeout_status peer_eof terminal_restore socket_cleanup] }
+  ensure
+    pair&.close
+  end
+end

data/test/support/script_probe.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+require "shellwords"
+require_relative "../../lib/expect/pty"
+
+# Shared by the real SSH check and the automatic local-PTY tests. This is a
+# test harness for a POSIX shell, not a network-device command abstraction.
+module ScriptProbe
+  PROMPT = "EXPECT_SCRIPT_PROMPT> "
+  FIXTURES = File.expand_path("../fixtures/ssh_scripts", __dir__)
+  class Failure < StandardError; end
+
+  def self.check(condition, message)
+    raise Failure, message unless condition
+  end
+
+  def self.normalize(bytes)
+    bytes.gsub("\r\n", "\n").b
+  end
+
+  class Runner
+    attr_reader :session, :results
+
+    def initialize(session, timeout: 5)
+      @session = session
+      @timeout = timeout
+      @results = []
+    end
+
+    def ready!
+      result = session.expect_result(PROMPT, timeout: @timeout)
+      ScriptProbe.check(result.matched?, "shell prompt missing (#{result.error})")
+      # Avoid terminal echo being mistaken for script output or leaking the
+      # test's wrapper command into the output we verify.
+      # Interactive shells may interpret high-bit bytes as readline commands
+      # in a C locale. Disable editing for literal script transmission.
+      session.write("stty -echo; set +o emacs; set +o vi\n")
+      result = session.expect_result(PROMPT, timeout: @timeout)
+      ScriptProbe.check(result.matched?, "shell setup failed (#{result.error})")
+      session.clear_buffer
+      self
+    end
+
+    def run_file(path, expected_status:, expected_output:)
+      run(File.basename(path), File.binread(path), expected_status: expected_status, expected_output: expected_output)
+    end
+
+    def run(name, script, expected_status:, expected_output:)
+      nonce = SecureRandom.hex(12)
+      start_marker = "PROBE_BEGIN_#{nonce}"
+      end_marker = "PROBE_END_#{nonce}"
+      digest = Digest::SHA256.hexdigest(script)
+      # Quote once for the remote shell without inserting backslashes between
+      # UTF-8 bytes (File.binread returns an ASCII-8BIT string).
+      quoted_script = "'#{script.gsub("'", %q('"'"'))}'"
+      # Inputs are logged deliberately as metadata: Expect's automatic log
+      # records received bytes, not sends. Never include authentication here.
+      session.write_log("\n[SEND] #{name} sha256=#{digest}\n")
+      command = "printf '\\n%s%s\\n' 'PROBE_BEGIN_' '#{nonce}'; " \
+                "/bin/sh -c #{quoted_script}; probe_status=$?; " \
+                "printf '\\n%s%s:%s\\n' 'PROBE_END_' '#{nonce}' \"$probe_status\"\n"
+      session.write(command)
+      started = session.expect_result(/(?:\A|\r?\n)#{Regexp.escape(start_marker)}\r?\n/, timeout: @timeout)
+      ScriptProbe.check(started.matched?, "#{name}: begin marker missing (#{started.error})")
+      ended = session.expect_result(/(?:\A|\r?\n)#{Regexp.escape(end_marker)}:(\d+)\r?\n/, timeout: @timeout)
+      ScriptProbe.check(ended.matched?, "#{name}: script did not finish (#{ended.error})")
+      output = ScriptProbe.normalize(ended.before)
+      status = Integer(ended.captures.fetch(0), 10)
+      # Wait for the shell before starting another script, including when the
+      # prior script exited nonzero. Each script runs in its own subshell.
+      prompt = session.expect_result(PROMPT, timeout: @timeout)
+      ScriptProbe.check(prompt.matched?, "#{name}: shell did not recover (#{prompt.error})")
+      session.write_log("\n[EXIT] #{name} status=#{status}\n")
+      passed = status == expected_status && output == expected_output.b
+      result = { name: name, sha256: digest, status: status, expected_status: expected_status,
+                 output: output.dup.force_encoding(Encoding::UTF_8), passed: passed }
+      results << result
+      ScriptProbe.check(status == expected_status, "#{name}: exit #{status}, expected #{expected_status}")
+      ScriptProbe.check(output == expected_output.b, "#{name}: output differs from fixture expectation")
+      result
+    end
+
+    def finish!
+      # The last bytes arrive while soft_close drains the session. No expect
+      # call is made after this send, so the log proves shutdown draining.
+      session.write("sleep 0.1; printf '%s%s\\n' 'SESSION_' 'FINAL_TAIL'; exit 0\n")
+      session.soft_close(timeout: 3)
+      ScriptProbe.check(session.closed? && session.exit_code&.zero?, "shell did not exit cleanly")
+    end
+  end
+
+  # Run all script fixtures in one session, then verify the persisted log.
+  # An explicit nonzero fixture is an expected success of the test harness.
+  def self.verify_file_session(runner, path, user:)
+    session = runner.session
+    # With SSH, the remote TTY differs from the local PTY. Obtain it using an
+    # independent command, then demand an exact identity fixture response.
+    session.write("printf '\\n%s' 'TTY_PROBE='; tty\n")
+    tty = session.expect_result(%r{(?:\A|\n)TTY_PROBE=(/dev/[^\r\n]+)\r?\n}, timeout: 5)
+    check(tty.matched?, "remote TTY probe failed")
+    terminal = tty.captures.fetch(0)
+    check(session.expect(PROMPT, timeout: 5), "TTY probe did not return to shell")
+
+    # The caller allocates a fresh private directory; exercise truncation only
+    # on this new test file, never on an existing user's log.
+    File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write("OLD_TEST_CONTENT\n") }
+    log = session.log_to(path, mode: "w")
+    cases = [
+      ["01_identity.sh", 0, "USER=#{user}\nTTY=#{terminal}\nIDENTITY_OK\n"],
+      ["02_output.sh", 0, "STDOUT_FIRST\nSTDERR_SECOND\n中文输出：日志验证\nSTDOUT_LAST\n"],
+      ["03_delayed.sh", 0, "DELAY_BEGIN\nDELAY_MIDDLE\nDELAY_END\n"],
+      ["04_failure.sh", 7, "EXPECTED_FAILURE\n"],
+      ["05_recovery.sh", 0, "RECOVERY_OK\nVALUE=42\n"]
+    ]
+    cases.each do |name, status, output|
+      runner.run_file(File.join(FIXTURES, name), expected_status: status, expected_output: output)
+      # Read while the logger is open to prove writes are immediately visible.
+      live = normalize(File.binread(path))
+      check(live.include?(output.b), "#{name}: live log is missing output")
+      check(live.include?("[EXIT] #{name} status=#{status}\n"), "#{name}: live exit annotation missing")
+    end
+    session.log_output = nil
+    check(log.closed?, "owned log was not closed")
+    before_disabled = File.binread(path)
+    runner.run("logging_disabled", "printf 'UNLOGGED_OUTPUT\\n'\n", expected_status: 0,
+                                                                    expected_output: "UNLOGGED_OUTPUT\n")
+    check(File.binread(path) == before_disabled, "disabled logger still wrote data")
+
+    # The default mode must append, retaining every preceding command.
+    appended = session.log_to(path)
+    runner.run("logging_resumed", "printf 'APPEND_OK\\n'\n", expected_status: 0, expected_output: "APPEND_OK\n")
+    runner.finish!
+    check(appended.closed?, "close did not close the owned log")
+    bytes = File.binread(path)
+    check(bytes.start_with?(before_disabled), "append mode overwrote previous log bytes")
+    text = normalize(bytes)
+    check(!text.include?("OLD_TEST_CONTENT") && !text.include?("UNLOGGED_OUTPUT"),
+          "truncated or disabled data leaked into log")
+    position = -1
+    cases.each do |name, status, output|
+      sent = text.index("[SEND] #{name} ")
+      exited = text.index("[EXIT] #{name} status=#{status}\n")
+      check(sent && exited && sent > position && exited > sent, "#{name}: incorrect log execution order")
+      check(text.scan(Regexp.new(Regexp.escape(output.b), Regexp::NOENCODING)).length == 1,
+            "#{name}: output missing or duplicated")
+      position = exited
+    end
+    check(text.include?("APPEND_OK\n"), "resumed logging lost output")
+    check(text.scan("SESSION_FINAL_TAIL\n").length == 1, "shutdown lost or duplicated final output")
+    { cases: runner.results, remote_tty: terminal, log_bytes: bytes.bytesize,
+      log_sha256: Digest::SHA256.hexdigest(bytes),
+      checks: %w[exact_output execution_order live_flush stdout_stderr utf8 nonzero_recovery
+                 truncate disable append eof_drain] }
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "timeout"
+require "stringio"
+require "tempfile"
+require "tmpdir"
+require "socket"
+require_relative "../lib/expect"
+
+class ExpectTest < Minitest::Test
+  def setup
+    @sessions = []
+    @ios = []
+    @threads = []
+    @configuration = Expect.configuration
+  end
+
+  def teardown
+    @threads.each { |thread| thread.kill.join if thread.alive? }
+    @sessions.reverse_each { |session| session.hard_close(timeout: 0.03) }
+    @ios.each { |io| io.close unless io.closed? }
+    Expect.configure(**@configuration.to_h)
+  end
+
+  def child(script, **)
+    session = Expect.spawn(RbConfig.ruby, "--disable-gems", "-e", "STDOUT.sync = true; STDERR.sync = true; #{script}",
+                           log_stdout: false, **)
+    @sessions << session
+    session
+  end
+
+  def pipe_session(**)
+    reader, writer = IO.pipe
+    @ios.push(reader, writer)
+    session = Expect.open(reader, **)
+    @sessions << session
+    [session, writer]
+  end
+
+  def background(&)
+    @threads << Thread.new(&)
+    @threads.last
+  end
+
+  def bounded(seconds = 5, &)
+    Timeout.timeout(seconds, &)
+  end
+
+  def terminal_configuration(session)
+    state = session.stty
+    return state unless RUBY_PLATFORM.include?("darwin")
+
+    # Darwin marks pending-input retyping after tcsetattr. PENDIN is a kernel
+    # state bit (sys/termios.h), not a changed terminal configuration.
+    state.sub(/lflag=([0-9a-f]+)/) { "lflag=#{(Regexp.last_match(1).to_i(16) & ~0x20000000).to_s(16)}" }
+  end
+end

data/test/timeout_test.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TimeoutTest < ExpectTest
+  def test_default_timeout_and_explicit_infinite_timeout
+    session, writer = pipe_session
+    session.timeout = 0.01
+    assert_nil session.expect("ready")
+    background do
+      sleep 0.04
+      writer.write("ready")
+    end
+    assert_equal(1, bounded { session.expect("ready", timeout: nil) })
+  end
+
+  def test_zero_timeout_polls_existing_data_without_waiting
+    session, writer = pipe_session
+    writer.write("ready")
+    assert_equal 1, session.expect("ready", timeout: 0)
+    start = Expect.monotonic
+    assert_nil session.expect("missing", timeout: 0)
+    assert_operator Expect.monotonic - start, :<, 0.1
+  end
+
+  def test_continue_resets_timeout
+    session, writer = pipe_session
+    number = with_timed_input(writer, [[7, "A"], [16, "B"]]) do
+      session.expect(timeout: 13) do
+        on("A") { Expect.continue }
+        on("B")
+      end
+    end
+    assert_equal 2, number
+  end
+
+  def test_continue_timeout_preserves_deadline
+    session, writer = pipe_session
+    number = with_timed_input(writer, [[7, "A"], [19, "B"]]) do
+      result = session.expect(timeout: 14) do
+        on("A") { Expect.continue(reset_timeout: false) }
+        on("B")
+      end
+      assert_equal 14, Expect.monotonic
+      result
+    end
+    assert_nil number
+    assert_equal :timeout, session.error
+  end
+
+  def test_restart_timeout_on_receive
+    session, writer = pipe_session
+    session.reset_timeout_on_read = true
+    number = with_timed_input(writer, [[6, "."], [12, "."], [18, "."], [24, ".done"]]) do
+      session.expect("done", timeout: 10)
+    end
+    assert_equal 1, number
+  end
+
+  def test_receive_keeps_deadline_without_reset
+    session, writer = pipe_session
+    result = with_timed_input(writer, [[6, "."], [12, "done"]]) do
+      session.expect_result("done", timeout: 10)
+    end
+    assert result.timeout?
+    assert_equal ".", session.buffer
+  end
+
+  def test_timeout_callback_receives_group_and_can_retry
+    session, = pipe_session
+    count = 0
+    groups = []
+    argument = :value
+    number = session.expect(timeout: 0.01) do
+      timeout do |objects|
+        groups << [objects, argument]
+        count += 1
+        count < 3 ? Expect.continue : nil
+      end
+    end
+    assert_nil number
+    assert_equal 3, count
+    assert_equal [[[session], :value]] * 3, groups
+  end
+
+  def test_callback_exception_propagates
+    session, = pipe_session
+    session.buffer = "ready"
+    assert_raises(RuntimeError) do
+      session.expect(timeout: 0) { on("ready") { raise "handler failed" } }
+    end
+    assert_equal "ready", session.match
+  end
+
+  def test_continuation_through_buffered_states
+    session, = pipe_session
+    session.buffer = "A B C D End"
+    states = []
+    number = session.expect(timeout: 1) do
+      on(/[ABCD]/) do |connection|
+        states << connection.match
+        connection.continue
+      end
+      on("End")
+    end
+    assert_equal 2, number
+    assert_equal %w[A B C D], states
+  end
+
+  def test_absolute_timeout_even_with_continuous_unmatched_output
+    session = child('loop { print "x" * 16384 }', raw_pty: true, buffer_limit: 1024)
+    start = Expect.monotonic
+    result = bounded(2) { session.expect_result("missing", timeout: 0.05) }
+    assert result.timeout?
+    assert_operator Expect.monotonic - start, :<, 0.4
+  end
+
+  def test_repeated_select_interruptions_do_not_extend_the_deadline
+    session, = pipe_session
+    interrupted = lambda do |*|
+      sleep 0.01
+      raise Errno::EINTR
+    end
+    result = bounded(1) do
+      IO.stub(:select, interrupted) { session.expect_result("missing", timeout: 0.02) }
+    end
+    assert result.timeout?
+  end
+
+  def test_interrupted_read_retries_without_losing_input
+    session, writer = pipe_session
+    writer.write("ready")
+    original = session.to_io.method(:read_nonblock)
+    interrupted = true
+    read = lambda do |*args, **options|
+      if interrupted
+        interrupted = false
+        raise Errno::EINTR
+      end
+      original.call(*args, **options)
+    end
+    session.to_io.stub(:read_nonblock, read) do
+      assert_equal 1, session.expect("ready", timeout: 1)
+    end
+    assert_equal "ready", session.match
+  end
+
+  private
+
+  # 按虚拟时间向真实管道写入数据；select 仍按调用方给定的期限决定就绪或超时。
+  # 这样可精确检查期限是否重置，不依赖 CI 线程能否在几十毫秒内获得调度。
+  def with_timed_input(writer, events, &block)
+    now = 0.0
+    pending = events.dup
+    select = lambda do |readers, _writers, _errors, timeout|
+      deadline = now + timeout
+      if pending.any? && pending.first[0] <= deadline
+        now, data = pending.shift
+        writer.write(data)
+        [readers, [], []]
+      else
+        now = deadline
+        nil
+      end
+    end
+    Expect.stub(:monotonic, -> { now }) do
+      IO.stub(:select, select, &block)
+    end
+  end
+end