RubyGems - ttytest - Versions diffs - 0.4.0 → 0.5.0 - Mend

ttytest 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

checksums.yaml CHANGED

@@ -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 CHANGED

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

data/README.md CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

@@ -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 CHANGED

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

data/lib/ttytest/version.rb CHANGED

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

data/ttytest.gemspec CHANGED

@@ -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 CHANGED

@@ -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 DELETED

@@ -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