jet_black 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a21eedaa0beebe53a809bb73bd3f264f4993d0eb4d6040e6521b6ef7d044b4b7
-  data.tar.gz: 1c805ee9c3c4921e3978caced024e3c9332dcc50ef215dd10b1e3cacc366e807
+  metadata.gz: c389c6caddb4fe0d3b8874f96a50f9c0e4217c3e1af903b6ca9f19bca24065c5
+  data.tar.gz: 5c1775b10ac55262d4291a9748858776a618400dfb4fa4561357147802822ce3
 SHA512:
-  metadata.gz: ac2904ee5ebf833094905c22ef0e8064bbc6618fab3f7319ee80feecdaf78fdb05ee7ba5e29f657221fff2fc16e8a05ac88717eee3ab9380e6e90b847aa1db20
-  data.tar.gz: e29ddc28dfc5cb2b450a4b61bfeb037b56d34c297fde88844558168191d15166d2e4405168da10768c93f6e51eac6737158c4874a27ae7d4d210d596b86893c3
+  metadata.gz: 9ddb6513193a3395baef52fab1bf86b3cf1de9f5d04091b82f52cd35e8bc97c2a3e21ca7549855e7d9db7947cb1af3b5f7263ce1b9929382dd7743ceb05d7d91
+  data.tar.gz: eac5b131ecce2f9b5aff51b1220d3276f320972bbf712f2e1efc7794265972c72f1e6fa5197f3c69548d574ac0f1bbae5193cf16961c9daa2b382c7a652d88b6

data/.circleci/config.yml

@@ -61,9 +61,15 @@ jobs:
       - image: circleci/ruby:2.7
     environment:
       ENABLE_COVERAGE: 1
+  ruby-3.0:
+    <<: *base_job
+    docker:
+      - image: circleci/ruby:3.0
 
 #-------------------------------------------------------------------------------
 
+# TODO: Migrate to CircleCI matrix
+
 workflows:
   version: 2
   multiple-rubies:
@@ -72,3 +78,4 @@ workflows:
       - ruby-2.5
       - ruby-2.6
       - ruby-2.7
+      - ruby-3.0

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.7.0
+
+- Adds `run_interactive` to allow pseudo-terminal interaction
+
 ## v0.6.0
 
 - Freeze string literals

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jet_black (0.6.0)
+    jet_black (0.7.0)
 
 GEM
   remote: https://rubygems.org/
@@ -15,7 +15,7 @@ GEM
       tins (~> 1.6)
     diff-lcs (1.3)
     docile (1.3.1)
-    json (2.1.0)
+    json (2.3.1)
     method_source (0.9.0)
     pry (0.11.3)
       coderay (~> 1.1.0)
@@ -60,4 +60,4 @@ DEPENDENCIES
   simplecov
 
 BUNDLED WITH
-   2.1.2
+   2.1.4

data/README.md

@@ -11,6 +11,7 @@ with [RSpec] in mind. Features:
 - Synchronously [run commands](#running-commands) then write assertions on:
   - The `stdout` / `stderr` content
   - The exit status of the process
+- Exercise [interactive command line interfaces](#running-interactive-commands)
 - Manipulate files in the temporary directory:
   - [Create files](#file-manipulation)
   - [Create executable files](#file-manipulation)
@@ -85,6 +86,38 @@ session = JetBlack::Session.new
 session.run("./hello-world", stdin: "Alice")
 ```
 
+### Running interactive commands
+
+```ruby
+session = JetBlack::Session.new
+
+result = session.run_interactive("./hello-world") do |terminal|
+  terminal.expect("What's your name?", reply: "Alice")
+  terminal.expect("What's your location?", reply: "Wonderland")
+end
+
+expect(result.exit_status).to eq 0
+expect(result.stdout).to eq <<~TXT
+  What's your name?
+  Alice
+  What's your location?
+  Wonderland
+  Hello Alice in Wonderland
+TXT
+```
+
+If you don't want to wait for a process to finish, you can end the interactive
+session early:
+
+```ruby
+session = JetBlack::Session.new
+
+result = session.run_interactive("./long-cli-flow") do |terminal|
+  terminal.expect("Question 1", reply: "Y")
+  terminal.end_session(signal: "INT")
+end
+```
+
 ### File manipulation
 
 ```ruby

data/lib/jet_black/errors.rb

@@ -33,4 +33,17 @@ module JetBlack
       MSG
     end
   end
+
+  class TerminalSessionTimeoutError < Error
+    attr_reader :terminal
+
+    def initialize(terminal, expected_value, timeout)
+      @terminal = terminal
+
+      super <<~MSG
+        Interactive terminal session timed out after #{timeout} second(s).
+        Waiting for: '#{expected_value}'
+      MSG
+    end
+  end
 end

data/lib/jet_black/interactive_command.rb

@@ -0,0 +1,24 @@
+require_relative "environment"
+require_relative "terminal_session"
+
+module JetBlack
+  class InteractiveCommand
+    def call(raw_command:, raw_env:, directory:, block:)
+      env = Environment.new(raw_env).to_h
+      terminal = TerminalSession.new(raw_command, env: env, directory: directory)
+
+      unless block.nil?
+        block.call(terminal)
+      end
+
+      terminal.wait_for_finish
+
+      ExecutedCommand.new(
+        raw_command: raw_command,
+        stdout: terminal.stdout,
+        stderr: terminal.stderr,
+        exit_status: terminal.exit_status,
+      )
+    end
+  end
+end

data/lib/jet_black/non_interactive_command.rb

@@ -0,0 +1,21 @@
+require "open3"
+require_relative "environment"
+
+module JetBlack
+  class NonInteractiveCommand
+    def call(raw_command:, stdin:, raw_env:, directory:)
+      env = Environment.new(raw_env).to_h
+
+      stdout, stderr, exit_status = Open3.capture3(
+        env, raw_command, chdir: directory, stdin_data: stdin
+      )
+
+      ExecutedCommand.new(
+        raw_command: raw_command,
+        stdout: stdout,
+        stderr: stderr,
+        exit_status: exit_status,
+      )
+    end
+  end
+end

data/lib/jet_black/session.rb

@@ -3,12 +3,12 @@
 require "bundler"
 require "fileutils"
 require "forwardable"
-require "open3"
 require "tmpdir"
-require_relative "environment"
 require_relative "errors"
 require_relative "executed_command"
 require_relative "file_helper"
+require_relative "non_interactive_command"
+require_relative "interactive_command"
 
 module JetBlack
   class Session
@@ -27,33 +27,38 @@ module JetBlack
     end
 
     def run(command, stdin: nil, env: {}, options: {})
-      combined_options = session_options.merge(options)
-      executed_command = exec_command(command, stdin, env, combined_options)
-      commands << executed_command
-      executed_command
+      exec_non_interactive(raw_command: command, stdin: stdin, raw_env: env, options: options).tap do |executed_command|
+        commands << executed_command
+      end
+    end
+
+    def run_interactive(command, env: {}, options: {}, &block)
+      exec_interactive(raw_command: command, raw_env: env, options: options, block: block).tap do |executed_command|
+        commands << executed_command
+      end
     end
 
     private
 
     attr_reader :session_options, :file_helper
 
-    def exec_command(raw_command, stdin, raw_env, options)
-      env = Environment.new(raw_env).to_h
+    def exec_non_interactive(raw_command:, stdin:, raw_env:, options:)
+      combined_options = session_options.merge(options)
 
-      command_context(options) do
-        stdout, stderr, exit_status =
-          Open3.capture3(env, raw_command, chdir: directory, stdin_data: stdin)
+      execution_context(combined_options) do
+        NonInteractiveCommand.new.call(raw_command: raw_command, stdin: stdin, raw_env: raw_env, directory: directory)
+      end
+    end
+
+    def exec_interactive(raw_command:, raw_env:, options:, block:)
+      combined_options = session_options.merge(options)
 
-        ExecutedCommand.new(
-          raw_command: raw_command,
-          stdout: stdout,
-          stderr: stderr,
-          exit_status: exit_status,
-        )
+      execution_context(combined_options) do
+        InteractiveCommand.new.call(raw_command: raw_command, raw_env: raw_env, directory: directory, block: block)
       end
     end
 
-    def command_context(options)
+    def execution_context(options)
       if options[:clean_bundler_env]
         Bundler.public_send(bundler_clean_environment_method) { yield }
       else

data/lib/jet_black/terminal_session.rb

@@ -0,0 +1,91 @@
+require "pty"
+require "expect"
+require_relative "errors"
+
+module JetBlack
+  class TerminalSession
+    DEFAULT_TIMEOUT = 10
+
+    attr_reader :exit_status
+
+    def initialize(raw_command, env:, directory:)
+      @stderr_reader, @stderr_writer = IO.pipe
+      @output, @input, @pid = PTY.spawn(env, raw_command, chdir: directory, err: stderr_writer.fileno)
+      self.raw_stdout = []
+    end
+
+    def expect(expected_value, reply: nil, timeout: DEFAULT_TIMEOUT, signal_on_timeout: "KILL")
+      output_matches = output.expect(expected_value, timeout)
+
+      if output_matches.nil?
+        end_session(signal: signal_on_timeout)
+        raise TerminalSessionTimeoutError.new(self, expected_value, timeout)
+      end
+
+      raw_stdout.concat(output_matches)
+
+      if reply != nil
+        input.puts(reply)
+      end
+    end
+
+    def stdout
+      raw_stdout.join.gsub("\r", "")
+    end
+
+    def stderr
+      raw_std_err
+    end
+
+    def wait_for_finish
+      return if finished?
+
+      finalize_io
+
+      self.exit_status = wait_for_exit_status
+    end
+
+    def end_session(signal: "INT")
+      Process.kill(signal, pid)
+      finalize_io
+
+      self.exit_status = wait_for_exit_status
+    end
+
+    def finished?
+      !exit_status.nil?
+    end
+
+    private
+
+    attr_accessor :raw_stdout, :raw_std_err
+    attr_reader :input, :output, :pid, :stderr_reader, :stderr_writer
+    attr_writer :exit_status
+
+    def finalize_io
+      drain_stdout
+      drain_stderr
+    end
+
+    def wait_for_exit_status
+      _, pty_status = Process.waitpid2(pid)
+      pty_status.exitstatus || pty_status.termsig
+    end
+
+    def drain_stdout
+      until output.eof? do
+        raw_stdout << output.readline
+      end
+
+      input.close
+      output.close
+    rescue Errno::EIO => e # https://github.com/ruby/ruby/blob/57fb2199059cb55b632d093c2e64c8a3c60acfbb/ext/pty/pty.c#L521
+      warn("Rescued #{e.message}") if ENV.key?("DEBUG")
+    end
+
+    def drain_stderr
+      stderr_writer.close
+      self.raw_std_err = stderr_reader.read
+    end
+  end
+end

data/lib/jet_black/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JetBlack
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jet_black
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Oli Peate
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2021-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,8 +114,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
-email: 
+description:
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -141,15 +141,18 @@ files:
 - lib/jet_black/errors.rb
 - lib/jet_black/executed_command.rb
 - lib/jet_black/file_helper.rb
+- lib/jet_black/interactive_command.rb
+- lib/jet_black/non_interactive_command.rb
 - lib/jet_black/rspec.rb
 - lib/jet_black/rspec/matchers.rb
 - lib/jet_black/session.rb
+- lib/jet_black/terminal_session.rb
 - lib/jet_black/version.rb
 homepage: https://github.com/odlp/jet_black
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -164,8 +167,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Black box testing
 test_files: []