ttytest 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d0175fa2266c1f56f709051162f3419862a24355
-  data.tar.gz: 949439a6f922cd8b71c8c92e10a9721161c152b7
+  metadata.gz: 91adbf5abccf48f1626c908ebbccc8ad13bcc67b
+  data.tar.gz: f244bd9c2970b4af1704ac84f6bf1a6fb2b8975e
 SHA512:
-  metadata.gz: 8af22aa0fb0f3896c113c7e5cb5d929c82e642c44d93e03f5b75729fc3d1e2a2eb5f796f6e09300f6d21bc4d5bc1b70e6a7c3676e0dd0f5bc4ff7d6e91a52c8d
-  data.tar.gz: 7871021b99ebef74812db882e8ada619135697c114c6df31c19ed282dec13a155237d6162c467cab6f440887ebbf76d43a93eedd9812d3eef139ca47acf00c65
+  metadata.gz: fe2ec46d18232b2e0e16c54d827a8efba1628d114cc4c42a78254a114cfd9eb8e9ec009074d298de95fafb8820a2ee283b816b1cce59ab0f1eea4070b57e0025
+  data.tar.gz: 5e23a41408ff1cc4840e33a4049258434b16f17c3614994c4850df1e9adafda0dc9c1cdb57430035b3ebdf1d504b75d43df8301e32a53ebe7d2706ed03fe0f5b

data/.gitignore

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

data/README.md

@@ -1,8 +1,9 @@
-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 +12,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 +21,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 +33,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.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/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,20 +3,52 @@ 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|

data/lib/ttytest/tmux/driver.rb

@@ -12,26 +12,33 @@ 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?
@@ -45,18 +52,18 @@ module TTYtest
         @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.5.0'
 end

data/ttytest.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "yard"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ttytest
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - John Hawthorn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-31 00:00:00.000000000 Z
+date: 2017-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,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:
@@ -67,7 +81,6 @@ files:
 - 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

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