exsys 0.5 → 0.6

data/test/support/fake_hub.rb

@@ -0,0 +1,139 @@
+# A model of the ExSYS managed hub's serial protocol, faithful enough
+# to drive ExSYS::ManagedUSB end to end without hardware.
+#
+# The wire encoding here is written out independently of the library's
+# own pack/unpack, so that a disagreement between the two shows up as a
+# test failure rather than both sharing the same mistake.
+class FakeHub
+    DEFAULT_PASSWORD = 'pass'.ljust(8)
+
+    attr_reader   :log, :opens, :locks, :line, :speed, :mode
+    attr_accessor :password, :silent, :lockable, :garbage
+
+    # @param state    [Integer] initial port bitmap
+    # @param path     [String]  file backing the state, so that separate
+    #                            processes share one hub
+    # @param lock     [String]  file used for a real flock, so that the
+    #                            locking is genuinely exercised
+    # @param delay    [Float]   pause inside a write, widening the
+    #                            window a concurrent process could slip
+    #                            into
+    def initialize(password: DEFAULT_PASSWORD, state: 0x0000,
+                   path: nil, lock: nil, delay: 0)
+        @password = password
+        @state    = state
+        @flash    = state
+        @path     = path
+        @lock     = lock
+        @delay    = delay
+        @log      = []
+        @opens    = 0
+        @locks    = 0
+        @silent   = false     # hub answers nothing at all
+        @lockable = true      # platform allows locking the line
+        @garbage  = nil       # hub answers this instead, when set
+
+        # Attach to the hub the file already describes, so that a test
+        # can inspect what its subprocesses did; seed it otherwise.
+        if @path && File.exist?(@path) then load
+        else                                save
+        end
+    end
+
+    # Build from the environment, for the executable's subprocesses.
+    def self.from_env(env = ENV)
+        new(path:     env['EXSYS_TEST_HUB'],
+            lock:     env['EXSYS_TEST_LOCK'],
+            delay:    env['EXSYS_TEST_DELAY'].to_f).tap do |hub|
+            hub.silent   = !env['EXSYS_TEST_SILENT'].nil?
+            hub.lockable =  env['EXSYS_TEST_NOLOCK'].nil?
+            hub.garbage  =  env['EXSYS_TEST_GARBAGE']
+        end
+    end
+
+    def state = (load; @state)
+    def flash = (load; @flash)
+
+    # Ports currently powered, as a sorted list -- the oracle the tests
+    # compare against.
+    def ports_on
+        1.upto(16).select {|p| state & (1 << (p-1)) != 0 }
+    end
+
+    # Record how the line was opened, so a test can check the library
+    # asks for the device and the speed the hub actually needs.
+    def opened(line, speed, mode)
+        @line, @speed, @mode = line, speed, mode
+        @opens += 1
+    end
+
+    def flock(mode)
+        raise Errno::ENOTSUP unless @lockable
+        @locks += 1
+        return 0 if @lock.nil?
+
+        @lockfh = File.open(@lock, File::RDWR|File::CREAT, 0o600)
+        @lockfh.flock(mode)
+    end
+
+    def unlock
+        @lockfh&.close
+        @lockfh = nil
+    end
+
+    # Answer one command, as the hub would.
+    def command(cmd)
+        @log << cmd
+        return ''       if @silent
+        return @garbage if @garbage
+
+        load
+        reply = dispatch(cmd)
+        save
+        reply
+    end
+
+    private
+
+    def dispatch(cmd)
+        code = cmd[0, 2]
+        args = cmd[2..].to_s
+
+        # GP is the one command the hub answers unauthenticated, with a
+        # bare 8-digit payload rather than a G/E status.
+        return encode(@state) + 'FFFF' if code == 'GP'
+
+        return 'E01' unless args.start_with?(@password)
+        rest = args[@password.size..]
+
+        sleep @delay if @delay.positive?
+
+        case code
+        when 'SP' then @state = decode(rest)             ; 'G'
+        when 'FP' then @state = @flash = decode(rest)    ; 'G'
+        when 'WP' then @flash = @state                   ; 'G'
+        when 'RD' then @state = @flash                   ; 'G'
+        when 'RH' then @state = @flash                   ; nil
+        when 'CP' then @password = rest                  ; 'G'
+        else           'E02'
+        end
+    end
+
+    # Little-endian 16-bit, spelled out rather than packed.  Upper case
+    # because that is what a real hub answers -- observed on an ExSYS
+    # 16-port unit, which replies to GP with e.g. "C4FFFFFF".
+    def encode(v) = format('%02X%02X', v & 0xff, (v >> 8) & 0xff)
+    def decode(s) = s[0, 2].to_i(16) | (s[2, 2].to_i(16) << 8)
+
+    def load
+        return if @path.nil? || !File.exist?(@path)
+        @state, @flash, @password = File.read(@path).split("\n", 3)
+        @state = @state.to_i(16)
+        @flash = @flash.to_i(16)
+    end
+
+    def save
+        return if @path.nil?
+        File.write(@path, "%04x\n%04x\n%s" % [ @state, @flash, @password ])
+    end
+end

data/test/support/uart.rb

@@ -0,0 +1,40 @@
+# Test double for the `uart` gem.
+#
+# test/helper.rb puts this directory on the load path ahead of the real
+# gem, so `require "uart"` inside ExSYS::ManagedUSB picks this up and
+# the suite runs against FakeHub.  That is what lets the tests run with
+# no hub attached and with neither the uart nor the termios gem
+# installed.
+require_relative 'fake_hub'
+
+module UART
+    class << self
+        attr_writer :hub
+
+        # In-process tests set the hub directly; the subprocesses the
+        # executable's tests spawn build theirs from the environment.
+        def hub = @hub ||= FakeHub.from_env
+
+        def reset! = @hub = nil
+    end
+
+    # Stands in for the File that UART.open normally yields.
+    class Serial
+        def initialize(hub) = @hub = hub
+        def flock(mode)     = @hub.flock(mode)
+        def write(cmd)      = @reply = @hub.command(cmd.chomp("\r"))
+        def read            = @reply.nil? ? '' : "#{@reply}\r"
+    end
+
+    def self.open(line, speed = 9600, mode = '8N1')
+        hub.opened(line, speed, mode)
+        serial = Serial.new(hub)
+        return serial unless block_given?
+
+        begin
+            yield serial
+        ensure
+            hub.unlock
+        end
+    end
+end

data/test/test_exsys_usb.rb

@@ -0,0 +1,230 @@
+require_relative 'helper'
+
+# Behaviour of the bin/exsys-usb executable, run as a subprocess so
+# that its exit status -- what a calling script actually reads -- is
+# part of what is asserted.
+class TestExsysUsb < Minitest::Test
+    include CLI
+
+    ## Switching #########################################################
+
+    def test_on_and_off_reach_the_hub
+        _, _, st = exsys_usb('on', '1', '2')
+        assert_predicate st, :success?
+        assert_equal [ 1, 2 ], hub.ports_on
+
+        exsys_usb('off', '1')
+        assert_equal [ 2 ], hub.ports_on
+    end
+
+    def test_bare_on_and_off_cover_every_port
+        exsys_usb('on')
+        assert_equal ExSYS::ManagedUSB::PORTS, hub.ports_on
+        exsys_usb('off')
+        assert_empty hub.ports_on
+    end
+
+    def test_toggle
+        exsys_usb('on', '1', '3')
+        exsys_usb('toggle', '3', '4')
+        assert_equal [ 1, 4 ], hub.ports_on
+    end
+
+    def test_set_pairs
+        exsys_usb('on', '5')
+        _, _, st = exsys_usb('set', '3:on', '5:off')
+        assert_predicate st, :success?
+        assert_equal [ 3 ], hub.ports_on
+    end
+
+    def test_set_accepts_every_documented_spelling
+        exsys_usb('set', '1:on', '2:ON', '3:true', '4:t', '5:1')
+        assert_equal [ 1, 2, 3, 4, 5 ], hub.ports_on
+        exsys_usb('set', '1:off', '2:OFF', '3:false', '4:f', '5:0')
+        assert_empty hub.ports_on
+    end
+
+    def test_default_flag_forces_the_unlisted_ports
+        exsys_usb('on', '8')
+        exsys_usb('-D', 'false', 'set', '3:on')
+        assert_equal [ 3 ], hub.ports_on
+    end
+
+    def test_commit_and_restore
+        exsys_usb('on', '1')
+        exsys_usb('commit')
+        exsys_usb('on', '2')
+        exsys_usb('restore')
+        assert_equal [ 1 ], hub.ports_on
+    end
+
+    def test_commit_flag_writes_through
+        exsys_usb('-c', 'on', '4')
+        exsys_usb('on', '5')
+        exsys_usb('restore')
+        assert_equal [ 4 ], hub.ports_on
+    end
+
+    ## Exit status -- regression.  Every failure used to be printed and
+    ## then exited 0, so that `exsys-usb off 3 || alert` never fired.
+    ######################################################################
+
+    def test_a_refused_command_exits_non_zero
+        seed_hub(password: 'other')
+        _, err, st = exsys_usb('off', '3')
+        refute_predicate st, :success?
+        assert_equal 1, st.exitstatus
+        assert_match(/exsys-usb: 01/, err)
+    end
+
+    def test_a_silent_hub_exits_non_zero
+        _, err, st = exsys_usb('off', '3', env: { 'EXSYS_TEST_SILENT' => '1' })
+        assert_equal 1, st.exitstatus
+        assert_match(/exsys-usb:/, err)
+    end
+
+    def test_a_successful_command_exits_zero
+        _, _, st = exsys_usb('on', '1')
+        assert_equal 0, st.exitstatus
+    end
+
+    ## Argument handling #################################################
+
+    # Regression: a port outside 1..16, or a word that to_i turned into
+    # 0, used to be accepted and quietly do nothing.
+    def test_an_out_of_range_port_is_refused
+        [ '0', '17', '99' ].each do |p|
+            _, err, st = exsys_usb('on', p)
+            assert_equal 1, st.exitstatus, "port #{p} should be refused"
+            assert_match(/invalid port: #{p}/, err)
+        end
+    end
+
+    def test_a_port_that_is_not_a_number_is_refused
+        _, err, st = exsys_usb('off', 'usb3')
+        assert_equal 1, st.exitstatus
+        assert_match(/invalid port/, err)
+    end
+
+    def test_a_refused_port_leaves_the_hub_alone
+        exsys_usb('on', '1')
+        exsys_usb('on', '17')
+        assert_equal [ 1 ], hub.ports_on
+    end
+
+    # Regression: an action the case did not know fell through it, so
+    # the tool exited 0 having done nothing at all.
+    def test_an_unknown_action_is_refused
+        _, err, st = exsys_usb('onn', '1')
+        assert_equal 1, st.exitstatus
+        assert_match(/unknown action: onn/, err)
+    end
+
+    def test_a_malformed_set_pair_is_refused
+        [ 'foo', '3:maybe', ':on', '3:' ].each do |a|
+            _, err, st = exsys_usb('set', a)
+            assert_equal 1, st.exitstatus, "#{a} should be refused"
+            assert_match(/invalid argument/, err)
+        end
+    end
+
+    ## Startup failures -- regression.  Option parsing, the debug file
+    ## and the hub were all built before the rescue, so their failures
+    ## escaped as a Ruby backtrace.
+    ######################################################################
+
+    def test_an_over_long_password_is_reported_not_dumped
+        _, err, st = exsys_usb('-p', 'verylongpassword', 'on', '1')
+        assert_equal 1, st.exitstatus
+        assert_equal "exsys-usb: password too long\n", err
+    end
+
+    def test_an_unopenable_debug_file_is_reported_not_dumped
+        _, err, st = exsys_usb('--debug=/nonexistent-dir/x.log', 'on', '1')
+        assert_equal 1, st.exitstatus
+        assert_match(/\Aexsys-usb: /, err)
+        refute_match(/\.rb:\d+:in/, err)
+    end
+
+    def test_a_bad_option_value_is_reported_not_dumped
+        _, err, st = exsys_usb('-D', '0', 'set', '3:on')
+        assert_equal 1, st.exitstatus
+        assert_match(/\Aexsys-usb: /, err)
+        refute_match(/\.rb:\d+:in/, err)
+    end
+
+    ## Help ##############################################################
+
+    def test_no_action_prints_the_usage
+        out, _, st = exsys_usb
+        assert_equal 0, st.exitstatus
+        assert_match(/Usage: exsys-usb ACTION/, out)
+    end
+
+    def test_help_and_version
+        out, _, st = exsys_usb('-h')
+        assert_equal 0, st.exitstatus
+        assert_match(/--device/, out)
+
+        out, _, st = exsys_usb('-V')
+        assert_equal 0, st.exitstatus
+        assert_match(/#{ExSYS::VERSION}/, out)
+    end
+
+    ## Debug file ########################################################
+
+    # Regression: opened RDWR without truncating, so a shorter session
+    # left the tail of a longer previous one in place, reading as if the
+    # hub had sent it.
+    def test_the_debug_file_is_appended_to
+        log = File.join(@tmp, 'debug.log')
+        File.write(log, "PREVIOUS SESSION#{'.' * 200}\n")
+        exsys_usb("--debug=#{log}", 'on', '1')
+        assert_match(/\APREVIOUS SESSION/, File.read(log))
+        assert_match(/<-- GP/,             File.read(log))
+        refute_match(/\.{20}\z/,           File.read(log).lines.last)
+    end
+
+    def test_two_runs_both_survive_in_the_debug_file
+        log = File.join(@tmp, 'debug.log')
+        exsys_usb("--debug=#{log}", 'on', '1')
+        exsys_usb("--debug=#{log}", 'off', '1')
+        assert_equal 2, File.read(log).scan(/<-- GP/).size
+    end
+
+    # Regression: the trace carries the password, in a file that used to
+    # be created world-readable.
+    def test_the_debug_file_is_private_and_redacted
+        log = File.join(@tmp, 'debug.log')
+        seed_hub(password: 's3cret')
+        exsys_usb('-p', 's3cret', "--debug=#{log}", 'on', '1')
+        assert_equal 0o600, File.stat(log).mode & 0o777
+        refute_match(/s3cret/,      File.read(log))
+        assert_match(/<-- SP\*{8}/, File.read(log))
+    end
+
+    ## Concurrency #######################################################
+
+    # Regression: the GP and the SP were separate openings of the line,
+    # so two processes could both read the old state and the second
+    # write would drop the first one's port.
+    def test_two_concurrent_invocations_do_not_lose_an_update
+        env = { 'EXSYS_TEST_LOCK'  => File.join(@tmp, 'lock'),
+                'EXSYS_TEST_DELAY' => '0.2' }
+
+        results = [ '1', '2' ].map do |port|
+            Thread.new { exsys_usb('on', port, env: env) }
+        end.map(&:value)
+
+        results.each {|(_, err, st)| assert_equal 0, st.exitstatus, err }
+        assert_equal [ 1, 2 ], hub.ports_on
+    end
+
+    ## Packaging #########################################################
+
+    # Regression: the file carried a shebang but no execute bit, so a
+    # fresh clone could not run the examples in the README.
+    def test_the_executable_is_executable
+        assert_predicate File.stat(EXE).mode & 0o111, :positive?
+    end
+end

data/test/test_managed_usb.rb

@@ -0,0 +1,291 @@
+require_relative 'helper'
+
+# Library-level behaviour of ExSYS::ManagedUSB, driven against FakeHub.
+class TestManagedUSB < Minitest::Test
+    def setup
+        UART.reset!
+        UART.hub = @hub = FakeHub.new
+        @dbg     = StringIO.new
+        @usb     = ExSYS::ManagedUSB.new('/dev/null', debug: @dbg)
+    end
+
+    ## Switching #########################################################
+
+    def test_on_without_argument_powers_every_port
+        @usb.on
+        assert_equal ExSYS::ManagedUSB::PORTS, @hub.ports_on
+    end
+
+    def test_off_without_argument_powers_nothing
+        @usb.on
+        @usb.off
+        assert_empty @hub.ports_on
+    end
+
+    def test_on_and_off_are_restricted_to_the_named_ports
+        @usb.on(1, 2, 16)
+        assert_equal [ 1, 2, 16 ], @hub.ports_on
+        @usb.off(2)
+        assert_equal [ 1, 16 ], @hub.ports_on
+    end
+
+    def test_toggle_inverts_the_named_ports_only
+        @usb.on(1, 3)
+        @usb.toggle(3, 4)
+        assert_equal [ 1, 4 ], @hub.ports_on
+    end
+
+    def test_switching_returns_self_so_calls_chain
+        assert_same @usb, @usb.on
+        @usb.on.off(4, 5, 6)
+        assert_equal ExSYS::ManagedUSB::PORTS - [ 4, 5, 6 ], @hub.ports_on
+    end
+
+    ## Port validation -- regression, ports outside 1..16 used to be
+    ## accepted and then silently shifted or truncated away, so that the
+    ## hub was rewritten with its existing state and the caller was told
+    ## the switch had happened.
+    ######################################################################
+
+    def test_port_zero_is_rejected_by_every_entry_point
+        [ ->{ @usb.on(0)  }, ->{ @usb.off(0) },
+          ->{ @usb.toggle(0) }, ->{ @usb.set({ :on => [ 0 ] }) } ].each do |op|
+            assert_raises(ArgumentError, &op)
+        end
+    end
+
+    def test_port_above_the_last_one_is_rejected
+        [ 17, 99, 1_000 ].each do |p|
+            err = assert_raises(ArgumentError) { @usb.on(p) }
+            assert_match(/invalid port/, err.message)
+        end
+    end
+
+    def test_negative_port_is_rejected
+        assert_raises(ArgumentError) { @usb.on(-1) }
+    end
+
+    def test_a_rejected_port_leaves_the_hub_untouched
+        @usb.on(1)
+        assert_raises(ArgumentError) { @usb.on(17) }
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    def test_set_rejects_an_out_of_range_port_in_either_notation
+        assert_raises(ArgumentError) { @usb.set({ 99 => :on }) }
+        assert_raises(ArgumentError) { @usb.set({ :on => [ 99 ] }) }
+        assert_raises(ArgumentError) { @usb.set({ :off => [ 0 ] }) }
+    end
+
+    ## set ###############################################################
+
+    def test_set_by_port_value
+        @usb.set({ 1 => true, 2 => false, 3 => :on, 4 => :OFF, 5 => 1 })
+        assert_equal [ 1, 3, 5 ], @hub.ports_on
+    end
+
+    def test_set_by_port_state
+        @usb.set({ :on => [ 1, 3 ], :off => 4 })
+        assert_equal [ 1, 3 ], @hub.ports_on
+    end
+
+    def test_set_leaves_unlisted_ports_alone_without_a_default
+        @usb.on(8)
+        @usb.set({ 1 => true })
+        assert_equal [ 1, 8 ], @hub.ports_on
+    end
+
+    def test_set_applies_the_default_to_unlisted_ports
+        @usb.on(8)
+        @usb.set({ 1 => true }, false)
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    def test_set_treats_an_explicit_nil_as_leave_as_is
+        @usb.on(8)
+        @usb.set({ 1 => true, 8 => nil }, false)
+        assert_equal [ 1, 8 ], @hub.ports_on
+    end
+
+    def test_set_refuses_a_port_named_both_on_and_off
+        err = assert_raises(ArgumentError) do
+            @usb.set({ :on => [ 1 ], :off => [ 1 ] })
+        end
+        assert_match(/overlap/, err.message)
+    end
+
+    def test_set_refuses_a_mixed_or_unknown_notation
+        assert_raises(ArgumentError) { @usb.set({ :on => [ 1 ], 2 => :off }) }
+        assert_raises(ArgumentError) { @usb.set({ :bogus => [ 1 ] })        }
+        assert_raises(ArgumentError) { @usb.set({ 1 => :perhaps })          }
+    end
+
+    ## get ###############################################################
+
+    def test_get_ports
+        @usb.on(2)
+        assert_equal true,  @usb.get[2]
+        assert_equal false, @usb.get[3]
+        assert_equal ExSYS::ManagedUSB::PORTS, @usb.get.keys
+    end
+
+    def test_get_on_and_off_lists
+        @usb.on(2, 5)
+        assert_equal [ 2, 5 ], @usb.get(:on)
+        assert_equal ExSYS::ManagedUSB::PORTS - [ 2, 5 ], @usb.get(:off)
+    end
+
+    # Regression: the :on_off hash used to grow a key only for a state
+    # that actually occurred, so a hub with every port alike answered
+    # with one key and a caller reading the other got nil.
+    def test_get_on_off_always_carries_both_keys
+        assert_equal({ :on => [], :off => ExSYS::ManagedUSB::PORTS },
+                     @usb.get(:on_off))
+        @usb.on
+        assert_equal({ :on => ExSYS::ManagedUSB::PORTS, :off => [] },
+                     @usb.get(:on_off))
+        @usb.off(1)
+        assert_equal [ 1 ], @usb.get(:on_off)[:off]
+    end
+
+    # A real hub answers in upper case; accept either, since the reply
+    # is only ever fed to pack('H4'), which does not care.
+    def test_a_lower_case_reply_decodes_the_same
+        @hub.garbage = 'c4ffffff'
+        assert_equal [ 3, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], @usb.get(:on)
+        @hub.garbage = 'C4FFFFFF'
+        assert_equal [ 3, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], @usb.get(:on)
+    end
+
+    def test_get_refuses_an_unknown_type
+        assert_raises(ArgumentError) { @usb.get(:bogus) }
+    end
+
+    ## Flash and reset ###################################################
+
+    def test_commit_saves_and_restore_brings_back
+        @usb.on(1)
+        @usb.commit
+        @usb.on(2)
+        assert_equal [ 1, 2 ], @hub.ports_on
+        @usb.restore
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    def test_on_with_commit_writes_through_to_flash
+        @usb.on(3, commit: true)
+        @usb.on(4)
+        @usb.restore
+        assert_equal [ 3 ], @hub.ports_on
+    end
+
+    def test_reset_expects_no_reply
+        assert_same @usb, @usb.reset
+    end
+
+    ## Password ##########################################################
+
+    def test_default_password_is_padded_to_eight
+        @usb.on(1)
+        assert_equal 'SPpass    0100FFFF', @hub.log.last
+    end
+
+    def test_password_longer_than_eight_is_refused
+        assert_raises(ArgumentError) do
+            ExSYS::ManagedUSB.new('/dev/null', 'verylongpassword')
+        end
+    end
+
+    def test_wrong_password_raises_with_the_hub_code
+        usb = ExSYS::ManagedUSB.new('/dev/null', 'nope')
+        err = assert_raises(ExSYS::ManagedUSB::Error) { usb.on(1) }
+        assert_equal '01', err.message
+    end
+
+    def test_password_change_is_accepted_by_the_hub
+        @usb.password('secret')
+        assert_equal 'secret'.ljust(8), @hub.password
+        @usb.on(1)                       # still authenticated afterwards
+        assert_equal [ 1 ], @hub.ports_on
+    end
+
+    ## Debug output ######################################################
+
+    def test_debug_traces_both_directions
+        @usb.on(1)
+        assert_match(/<-- GP/,       @dbg.string)
+        assert_match(/--> 0000FFFF/, @dbg.string)
+    end
+
+    # Regression: the password used to be traced verbatim, putting it in
+    # a file that was also created world-readable.
+    def test_debug_never_carries_the_password
+        usb = ExSYS::ManagedUSB.new('/dev/null', 's3cret', debug: @dbg)
+        @hub.password = 's3cret'.ljust(8)
+        usb.on(1)
+        usb.commit
+        usb.password('other')
+        refute_match(/s3cret/, @dbg.string)
+        refute_match(/other/,  @dbg.string)
+        assert_match(/<-- SP\*{8}/, @dbg.string)
+    end
+
+    ## Malformed replies #################################################
+
+    def test_error_reply_to_a_read_is_raised_with_its_code
+        @hub.garbage = 'E42'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.get }
+        assert_equal '42', err.message
+    end
+
+    # Regression: a reply of an unexpected length used to raise a bare
+    # Error, whose message was just the class name.
+    def test_unexpected_reply_length_says_what_arrived
+        @hub.garbage = 'wat'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.get }
+        assert_match(/unexpected reply/, err.message)
+        assert_match(/wat/,              err.message)
+    end
+
+    def test_silent_hub_is_an_error_not_a_hang
+        @hub.silent = true
+        assert_raises(ExSYS::ManagedUSB::Error) { @usb.get }
+    end
+
+    ## The serial line ###################################################
+
+    # Regression: a read-modify-write used to close the line between the
+    # GP and the SP, letting another process slip in between the two.
+    def test_read_modify_write_holds_the_line_open
+        @usb.on(1)
+        assert_equal 1, @hub.opens
+        assert_equal 2, @hub.log.size          # GP then SP, one session
+    end
+
+    def test_set_holds_the_line_open_too
+        @usb.set({ 1 => true })
+        assert_equal 1, @hub.opens
+    end
+
+    def test_the_line_is_opened_as_the_hub_expects
+        @usb.on(1)
+        assert_equal '/dev/null',              @hub.line
+        assert_equal ExSYS::ManagedUSB::SPEED, @hub.speed
+        assert_equal 9600,                     @hub.speed
+        assert_equal '8N1',                    @hub.mode
+    end
+
+    def test_the_line_is_locked_while_held
+        @usb.on(1)
+        assert_equal 1, @hub.locks
+    end
+
+    # A platform that will not lock a character device must not make the
+    # tool unusable; it degrades to unlocked and says so.
+    def test_an_unlockable_line_degrades_rather_than_failing
+        @hub.lockable = false
+        @usb.on(1)
+        assert_equal [ 1 ], @hub.ports_on
+        assert_match(/not lockable/, @dbg.string)
+    end
+end