ttytest 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d0175fa2266c1f56f709051162f3419862a24355
-  data.tar.gz: 949439a6f922cd8b71c8c92e10a9721161c152b7
+SHA256:
+  metadata.gz: 6c4131b6211dfccc9feb932f2e3eafa11e2d63aeb5f73243b87dd2d5d805b3cd
+  data.tar.gz: 8a0c0e1fd412c1d44744833775c1a21ac519ad20e5970ab55eadae372b1b420d
 SHA512:
-  metadata.gz: 8af22aa0fb0f3896c113c7e5cb5d929c82e642c44d93e03f5b75729fc3d1e2a2eb5f796f6e09300f6d21bc4d5bc1b70e6a7c3676e0dd0f5bc4ff7d6e91a52c8d
-  data.tar.gz: 7871021b99ebef74812db882e8ada619135697c114c6df31c19ed282dec13a155237d6162c467cab6f440887ebbf76d43a93eedd9812d3eef139ca47acf00c65
+  metadata.gz: 4d2202449e0e68bdf2b796a9102fdaf9b0e95c4465b84c7e670a6154451e9238110b405ff687b84bbb188e0cbcaa2b58096e600e9b5e8d777bc2cbf18ef933a8
+  data.tar.gz: 96eed73a08289bbb511e6fc0a7af4171f123087a4673c64430bc2105b70e32cd28d11272de762238570e7e9472dfce0a5ae93bbd0b79452490861dbea270b44c

data/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on: [push]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Ruby 2.6
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.x
+    - name: Build and test with Rake
+      run: |
+        gem install bundler
+        bundle install --jobs 4 --retry 3
+        bundle exec rake

data/.gitignore

@@ -1,2 +1,4 @@
 Gemfile.lock
 pkg/
+.yardoc/
+doc/

data/README.md

@@ -1,8 +1,8 @@
-TTYtest is an integration test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
+TTYtest is an acceptance test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
 
 It works by running commands inside a tmux session, capturing the pane, and comparing the content. The assertions will wait a specified amount of time (default 2 seconds) for the expected content to appear.
 
-[![Build Status](https://travis-ci.org/jhawthorn/ttytest.svg?branch=master)](https://travis-ci.org/jhawthorn/ttytest)
+[![Gem Version](https://badge.fury.io/rb/ttytest.svg)](https://rubygems.org/gems/ttytest)
 
 ## Requirements
 
@@ -11,6 +11,8 @@ It works by running commands inside a tmux session, capturing the pane, and comp
 
 ## Usage
 
+### Example
+
 ``` ruby
 @tty = TTYtest.new_terminal(%{PS1='$ ' /bin/sh}, width: 80, height: 24)
 @tty.assert_row(0, '$')
@@ -18,8 +20,11 @@ It works by running commands inside a tmux session, capturing the pane, and comp
 
 @tty.send_keys(%{echo "Hello, world"\n})
 
-@tty.assert_row(0, '$ echo "Hello, world"')
-@tty.assert_row(1, 'Hello, world')
+@tty.assert_contents <<TTY
+$ echo "Hello, world"
+Hello, world
+$
+TTY
 @tty.assert_cursor_position(x: 2, y: 2)
 
 p @tty.rows # => ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ...]
@@ -27,6 +32,17 @@ p @tty.rows # => ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ..
 
 See also [fzy's integration test](https://github.com/jhawthorn/fzy/blob/master/test/integration/integration_test.rb) for a full example.
 
+### Assertions
+
+The main way to use TTYtest is through assertions. When called on a `TTYtest::Terminal`, each of these will be retried (for up to 2 seconds by default).
+
+Available assertions:
+* `assert_row(row_number, expected_text)`
+* `assert_cursor_position(x: x, y: y)`
+* `assert_cursor_visible`
+* `assert_cursor_hidden`
+* `assert_contents(lines_of_terminal)`
+
 ## TravisCI
 
 TTYtest can run on [TravisCI](https://travis-ci.org/), but the version of tmux made available with their default ubuntu 12.04 environment is too old. However the TravisCI ubuntu 14.04 "trusty" image provides tmux 1.8, which works great.

data/Rakefile

@@ -1,5 +1,6 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "yard"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -7,6 +8,10 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end
+
 task :console do
   system 'irb -Ilib -rttytest'
 end

data/lib/ttytest/capture.rb

@@ -1,10 +1,17 @@
 module TTYtest
+  # Represents the complete state of a {TTYtest::Terminal} at the time it was captured (contents, cursor position, etc).
+  # @attr_reader [Integer] width the number of columns in the captured terminal
+  # @attr_reader [Integer] height the number of rows in the captured terminal
+  # @attr_reader [Integer] cursor_x the cursor's column (starting at 0) in the captured terminal
+  # @attr_reader [Integer] cursor_y the cursor's row (starting at 0) in the captured terminal
   class Capture
     include TTYtest::Matchers
 
     attr_reader :cursor_x, :cursor_y
     attr_reader :width, :height
 
+    # Used internally by drivers when called by {Terminal#capture}
+    # @api private
     def initialize(contents, cursor_x: 0, cursor_y: 0, width: nil, height: nil, cursor_visible: true)
       @rows = (contents+"\nEND").split("\n")[0...-1].map do |row|
         row || ""
@@ -16,26 +23,33 @@ module TTYtest
       @cursor_visible = cursor_visible
     end
 
+    # @return [Array<String>] An array of each row's contend from the captured terminal
     def rows
       @rows
     end
 
-    def row(row)
-      rows[row]
+    # @param [Integer] the row to return
+    # @return [String] the content of the row from the captured terminal
+    def row(row_number)
+      rows[row_number]
     end
 
+    # @return [true,false] Whether the cursor is visible in the captured terminal
     def cursor_visible?
       @cursor_visible
     end
 
+    # @return [true,false] Whether the cursor is hidden in the captured terminal
     def cursor_hidden?
       !cursor_visible?
     end
 
+    # @return [Capture] returns self
     def capture
       self
     end
 
+    # @return [String] All rows of the captured terminal, separated by newlines
     def to_s
       rows.join("\n")
     end

data/lib/ttytest/matchers.rb

@@ -1,12 +1,21 @@
 module TTYtest
   module Matchers
+    # Asserts the contents of a single row
+    # @param [Integer] row_number the row (starting from 0) to test against
+    # @param [String] expected the expected value of the row. Any trailing whitespace is ignored
+    # @raise [MatchError] if the row doesn't match
     def assert_row(row_number, expected)
+      expected = expected.rstrip
       actual = row(row_number)
       if actual != expected
         raise MatchError, "expected row #{row_number} to be #{expected.inspect} but got #{actual.inspect}\nEntire screen:\n#{to_s}"
       end
     end
 
+    # Asserts that the cursor is in the expected position
+    # @param [Integer] x cursor x (row) position, starting from 0
+    # @param [Integer] y cursor y (column) position, starting from 0
+    # @raise [MatchError] if the cursor position doesn't match
     def assert_cursor_position(x:, y:)
       expected = [x, y]
       actual = [cursor_x, cursor_y]
@@ -15,19 +24,24 @@ module TTYtest
       end
     end
 
+    # @raise [MatchError] if the cursor is hidden
     def assert_cursor_visible
       if !cursor_visible?
         raise MatchError, "expected cursor to be visible was hidden\nEntire screen:\n#{to_s}"
       end
     end
 
+    # @raise [MatchError] if the cursor is visible
     def assert_cursor_hidden
       if !cursor_hidden?
         raise MatchError, "expected cursor to be hidden was visible\nEntire screen:\n#{to_s}"
       end
     end
 
-    def assert_matches(expected)
+    # Asserts the full contents of the terminal
+    # @param [String] expected the full expected contents of the terminal. Trailing whitespace on each line is ignored
+    # @raise [MatchError] if the terminal doesn't match the expected content
+    def assert_contents(expected)
       expected_rows = expected.split("\n")
       diff = []
       matched = true
@@ -46,6 +60,7 @@ module TTYtest
         raise MatchError, "screen did not match expected content:\n--- expected\n+++ actual\n#{diff.join("\n")}"
       end
     end
+    alias_method :assert_matches, :assert_contents
 
     METHODS = public_instance_methods
   end

data/lib/ttytest/terminal.rb

@@ -3,25 +3,57 @@ require 'ttytest/matchers'
 require 'ttytest/capture'
 
 module TTYtest
+  # @attr [Integer] max_wait_time the maximum amount of time (in seconds) to retry assertions before failing.
   class Terminal
     extend Forwardable
 
+    attr_accessor :max_wait_time
+
+    # @api private
+    # @see TTYtest.new_terminal
     def initialize(driver_terminal, max_wait_time: nil)
       @driver_terminal = driver_terminal
-      @max_wait_time = max_wait_time
+      @max_wait_time = max_wait_time || TTYtest.default_max_wait_time
     end
 
-    def max_wait_time
-      @max_wait_time || TTYtest.default_max_wait_time
-    end
+    # @!method send_keys(*keys)
+    #   Simulate typing keys into the terminal
+    #   @param [String] keys keys to send to the terminal
+    # @!method capture
+    #   Capture the current state of the terminal
+    #   @return [Capture] instantaneous state of the terminal when called
+    def_delegators :@driver_terminal, :send_keys, :capture
 
-    def_delegators :@driver_terminal, :send_keys, :send_raw, :capture
-    def_delegators :capture, :rows, :row, :width, :height, :cursor_visible?, :cursor_hidden?
+    # @!method rows
+    #   @return [Array<String>]
+    #   @see Capture#rows
+    # @!method row(row)
+    #   @return [String]
+    #   @see Capture#row
+    # @!method width
+    #   @see Capture#width
+    #   @return [Integer]
+    # @!method height
+    #   @see Capture#height
+    #   @return [Integer]
+    # @!method cursor_x
+    #   @see Capture#cursor_x
+    #   @return [Integer]
+    # @!method cursor_y
+    #   @see Capture#cursor_y
+    #   @return [Integer]
+    # @!method cursor_visible?
+    #   @see Capture#cursor_visible?
+    #   @return [true,false]
+    # @!method cursor_hidden?
+    #   @see Capture#cursor_hidden?
+    #   @return [true,false]
+    def_delegators :capture, :rows, :row, :width, :height, :cursor_x, :cursor_y, :cursor_visible?, :cursor_hidden?
 
     TTYtest::Matchers::METHODS.each do |matcher_name|
-      define_method matcher_name do |*args|
+      define_method matcher_name do |*args, **kwargs|
         synchronize do
-          capture.public_send(matcher_name, *args)
+          capture.public_send(matcher_name, *args, **kwargs)
         end
       end
     end

data/lib/ttytest/tmux/driver.rb

@@ -12,51 +12,67 @@ module TTYtest
       COMMAND = 'tmux'
       SOCKET_NAME = 'ttytest'
       REQUIRED_TMUX_VERSION = '1.8'
-      CONF_PATH = File.expand_path('../tmux.conf', __FILE__)
+      DEFAULT_CONFING_FILE_PATH = File.expand_path('../tmux.conf', __FILE__)
       SLEEP_INFINITY = 'read x < /dev/fd/1'
 
       class TmuxError < StandardError; end
 
-      def initialize(debug: false, command: COMMAND, socket_name: SOCKET_NAME)
+      def initialize(
+        debug: false,
+        command: COMMAND,
+        socket_name: SOCKET_NAME,
+        config_file_path: DEFAULT_CONFING_FILE_PATH
+      )
         @debug = debug
         @tmux_cmd = command
         @socket_name = socket_name
+        @config_file_path = config_file_path
       end
 
       def new_terminal(cmd, width: 80, height: 24)
         cmd = "#{cmd}\n#{SLEEP_INFINITY}"
 
         session_name = "ttytest-#{SecureRandom.uuid}"
-        tmux(*%W[-f #{CONF_PATH} new-session -s #{session_name} -d -x #{width} -y #{height} #{cmd}])
+        tmux(*%W[-f #{@config_file_path} new-session -s #{session_name} -d -x #{width} -y #{height} #{cmd}])
         session = Session.new(self, session_name)
         Terminal.new(session)
       end
 
+      # @api private
       def tmux(*args)
         ensure_available
         puts "tmux(#{args.inspect[1...-1]})" if debug?
 
-        stdout, stderr, status = Open3.capture3(@tmux_cmd, '-L', SOCKET_NAME, *args)
-        raise TmuxError, "tmux(#{args.inspect[1...-1]}) failed\n#{stderr}" unless status.success?
-        stdout
+        cmd = [@tmux_cmd, '-L', SOCKET_NAME, *args]
+        output = nil
+        status = nil
+        IO.popen(cmd, err: [:child, :out]) do |io|
+          output = io.read
+          io.close
+          status = $?
+        end
+
+        raise TmuxError, "tmux(#{args.inspect[1...-1]}) failed\n#{output}" unless status&.success?
+        output
       end
 
       def available?
+        return false unless tmux_version
         @available ||= (Gem::Version.new(tmux_version) >= Gem::Version.new(REQUIRED_TMUX_VERSION))
       end
 
+      private
+
       def debug?
         @debug
       end
 
-      private
-
       def ensure_available
         if !available?
           if !tmux_version
-            raise TmuxError, "tmux doesn't seem to be unstalled" unless available?
+            raise TmuxError, "Running `tmux -V` to determine version failed. Is tmux installed?"
           else
-            raise TmuxError, "tmux version #{tmux_version} does not meet requirement >= #{REQUIRED_TMUX_VERSION}" unless available?
+            raise TmuxError, "tmux version #{tmux_version} does not meet requirement >= #{REQUIRED_TMUX_VERSION}"
           end
         end
       end

data/lib/ttytest/tmux/session.rb

@@ -3,8 +3,7 @@
 module TTYtest
   module Tmux
     class Session
-      attr_reader :driver, :name
-
+      # @api private
       def initialize(driver, name)
         @driver = driver
         @name = name
@@ -12,14 +11,20 @@ module TTYtest
         ObjectSpace.define_finalizer(self, self.class.finalize(driver, name))
       end
 
+      # @api private
       def self.finalize(driver, name)
         proc { driver.tmux(*%W[kill-session -t #{name}]) }
       end
 
       def capture
         contents = driver.tmux(*%W[capture-pane -t #{name} -p])
-        str = driver.tmux(*%W[display-message -t #{name} -p #\{cursor_x},#\{cursor_y},#\{cursor_flag},#\{pane_width},#\{pane_height}])
-        x, y, cursor_flag, width, height = str.split(',')
+        str = driver.tmux(*%W[display-message -t #{name} -p #\{cursor_x},#\{cursor_y},#\{cursor_flag},#\{pane_width},#\{pane_height},#\{pane_dead},#\{pane_dead_status},])
+        x, y, cursor_flag, width, height, pane_dead, pane_dead_status, _newline = str.split(',')
+
+        if pane_dead == "1"
+          raise Driver::TmuxError, "Tmux pane has died\nCommand exited with status: #{pane_dead_status}\nEntire screen:\n#{contents}"
+        end
+
         TTYtest::Capture.new(
           contents.chomp("\n"),
           cursor_x: x.to_i,
@@ -33,6 +38,10 @@ module TTYtest
       def send_keys(*keys)
         driver.tmux(*%W[send-keys -t #{name} -l], *keys)
       end
+
+      private
+
+      attr_reader :driver, :name
     end
   end
 end

data/lib/ttytest/tmux/tmux.conf

@@ -1 +1,3 @@
 set -g status off
+set -g remain-on-exit on
+set -g default-shell /bin/sh

data/lib/ttytest/version.rb

@@ -1,3 +1,3 @@
 module TTYtest
-  VERSION = '0.4.0'
+  VERSION = '0.6.0'
 end

data/lib/ttytest.rb

@@ -8,6 +8,12 @@ module TTYtest
     attr_accessor :default_max_wait_time
 
     extend Forwardable
+    # @!method new_terminal(command, width: 80, height: 24)
+    #   Create a new terminal through the current driver.
+    #   @param [String] command a valid shell command to run
+    #   @param [Integer] width width of the new terminal
+    #   @param [Integer] height height of the new terminal
+    #   @return [Terminal] a new terminal running the specified command
     def_delegators :driver, :new_terminal
   end
 

data/ttytest.gemspec

@@ -23,7 +23,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.1.0'
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "yard"
 end

metadata

@@ -1,43 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: ttytest
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - John Hawthorn
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: TTYtest allows running applications inside of a terminal emulator (like
   tmux) and making assertions on the output.
 email:
@@ -60,14 +73,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/test.yml"
 - ".gitignore"
-- ".travis.yml"
 - Gemfile
 - README.md
 - Rakefile
 - lib/ttytest.rb
 - lib/ttytest/capture.rb
-- lib/ttytest/dummy.rb
 - lib/ttytest/matchers.rb
 - lib/ttytest/terminal.rb
 - lib/ttytest/tmux/driver.rb
@@ -79,7 +91,6 @@ homepage: https://github.com/jhawthorn/ttytest
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -94,9 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.8
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: TTYtest is an integration test framework for interactive tty applications
 test_files: []

data/.travis.yml

@@ -1,14 +0,0 @@
-dist: trusty
-language: ruby
-cache: bundler
-sudo: false
-before_script:
-  - tmux -V
-rvm:
-  - 2.2.6
-  - 2.3.3
-  - 2.4.0
-addons:
-  apt:
-    packages:
-    - tmux

data/lib/ttytest/dummy.rb

@@ -1,13 +0,0 @@
-module TTYtest
-  class Dummy
-    attr_accessor :contents
-
-    def initialize
-      @contents = "\n"*23
-    end
-
-    def capture
-      Capture.new(contents)
-    end
-  end
-end