ttytest2 0.8.6 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5813f48d629bc3029c7c486652b5badcedbbac19b4c24946f50f8aa9df579c8
-  data.tar.gz: 86adb037b39d0da7cdcc9920d71f1655e8864e0171ae3fabfcb7301774908102
+  metadata.gz: da8ddbaf4a49037e8dda3fb31986824c75819abbee94fb7954263c36a8e63414
+  data.tar.gz: 7091feb0fdac4857c1c0bf47a7c8158d8c90bd48d1ff321fec53aeab185443ec
 SHA512:
-  metadata.gz: e6fe94d8ef4c818a94b487f01efee8ab8d2c1ed828b30679eed643e4388c9e77178d00c25e761881098b47512a51f696c597a82fabfa68d9e6a569ea52b0e15e
-  data.tar.gz: 0ce32ed7e12445f1c9d4fee55ec2f9b5c27a3890c73a1a3a52b45c39c5c1931ebc08bcc6f04bf5e55d372a03b82e4b19a2ccfee4a487a427d52047d92f3fec84
+  metadata.gz: baab5b496e22d73a133084b2a4d58fc2fb83c95325c02227a50847adcbb876fe23f7a71e80efd69c12c2730aff64866222004db102b21613c4e4301455c15cd8
+  data.tar.gz: d66c05f581f565f33c9305ec9c484346790184d64ca5bdfb4b9718d95c22b842dbd2f689634548863f93cdcaced2dc94f4048dc66e6101dba8d2ef4f4856bae9

data/README.md

@@ -20,22 +20,34 @@ It works by running commands inside a tmux session, capturing the pane, and comp
 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).
 
 Available assertions:
-* `assert_row(row_number, expected_text)`
-* `assert_row_like(row_number, expected_text)`
-* `assert_row_starts_with(row_number, expected_text)`
-* `assert_row_ends_with(row_number, expected_text)`
-* `assert_cursor_position(x: x, y: y)`
-* `assert_cursor_visible`
-* `assert_cursor_hidden`
-* `assert_contents(lines_of_terminal)`
-
-### Sending output
+* specify row matches expected text exactly: `assert_row(row_number, expected_text) `
+* specify expected position of expected text: `assert_row_at(row_number, column_start_position, column_end_position, expected_text)`
+* specify row contains expected text: `assert_row_like(row_number, expected_text)`
+* specify row starts with expected text: `assert_row_starts_with(row_number, expected_text)`
+* specify row ends with expected text: `assert_row_ends_with(row_number, expected_text)`
+* specify the current cursor position matches expected: `assert_cursor_position(x: x, y: y)`
+* specify the cursor is currently visible: `assert_cursor_visible`
+* specify the cursor is currently hidden: `assert_cursor_hidden`
+* specify the contents of the entire terminal window: `assert_contents(lines_of_terminal)`
+
+### Sending Output
 
 You can send output to the terminal with the following calls.
 
-* `send_keys(output)`
+* `send_keys(output) # for canonical shells/cli's (or multi-character keys for noncanonical shells/cli's)`
+* `send_keys_one_at_a_time(output) # for noncanonical shells/cli's`
+* `send_keys_exact(output) # for sending tmux specific keys (DC for delete, Escape for ESC, etc.)`
+
+### Output Helpers
+
+Helper functions to make sending output easier! They use the methods above under 'Sending Output' section under the hood.
+
 * `send_newline # equivalent to @tty.send_keys(%(\n))`
-* `send_keys_one_at_a_time(output)`
+* `send_newlines(number_of_times) # equivalent to calling send_newline number_of_times`
+* `send_backspace # equivalent to @tty.send_keys(TTYtest::BACKSPACE)`
+* `send_backspaces(number_of_times) # equivalent to calling send_backspace number_of_times`
+* `send_delete # equivalent to calling send_keys_exact(%(DC))`
+* `send_deletes # equivalent to calling send_delete number_of_times`
 
 ### Example Canonical CLI/Shell
 
@@ -80,6 +92,10 @@ require 'ttytest'
 @tty.send_keys_one_at_a_time('ps')
 @tty.assert_row_ends_with(0, 'ps')
 @tty.send_keys(TTYtest:NEWLINE) # can use constants instead
+
+@tty.assert_row_starts_with(0, ENV['USER'])
+@tty.assert_row_ends_with(0, '$')
+@tty.send_newline # an alternative to the 2 above methods to send \n to the terminal
 ```
 
 ### Constants
@@ -88,7 +104,6 @@ There are some commonly used keys available as constants to make interacting wit
 
 ``` ruby
   TTYtest::BACKSPACE
-  TTYtest::DELETE
   TTYtest::TAB
   TTYtest::CTRLF
   TTYtest::CTRLC

data/examples/canonical_integration_tests.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'ttytest'
+
+START_COL = 19
+
+def assert_check_new_row(row)
+  @tty.assert_row_starts_with(row, "#{ENV['USER']}:")
+  @tty.assert_row_like(row, 'ncsh')
+  @tty.assert_row_ends_with(row, '$')
+  @tty.assert_cursor_position(START_COL, row)
+end
+
+@tty = TTYtest.new_terminal(%(PS1='$ ' ./bin/ncsh), width: 80, height: 24)
+
+row = 0
+
+# # # # Basic Tests # # # #
+puts 'Starting basic tests'
+
+@tty.assert_row_starts_with(row, 'ncsh: startup time: ')
+row += 1
+
+assert_check_new_row(row)
+@tty.send_keys(%(ls))
+@tty.assert_cursor_position(START_COL + 2, 1)
+@tty.send_newline
+@tty.assert_row_ends_with(row, 'ls')
+row += 1
+@tty.assert_row_starts_with(row, 'LICENSE')
+row = 9
+
+assert_check_new_row(row)
+@tty.send_keys(%(echo hello))
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')
+row += 1
+
+assert_check_new_row(row)
+@tty.send_keys(%(lss)) # send a bad command
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'ncsh: Could not find command or directory: No such file or directory')
+row += 1
+
+puts 'Starting backspace tests'
+
+# end of line backspace
+assert_check_new_row(row)
+@tty.send_keys(%(l))
+@tty.send_backspace
+assert_check_new_row(row)
+
+# multiple end of line backspaces
+@tty.send_keys(%(lsssss))
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_row_ends_with(row, '$ ls')
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_keys(%(echo hello)) # make sure buffer is properly formed after backspaces
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')
+row += 1
+
+# midline backspace
+assert_check_new_row(row)
+@tty.send_keys(%(lsssss))
+@tty.assert_cursor_position(START_COL + 6, row)
+@tty.send_keys(TTYtest::LEFT_ARROW)
+@tty.send_keys(TTYtest::LEFT_ARROW)
+@tty.assert_cursor_position(START_COL + 4, row)
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_cursor_position(START_COL, row)
+@tty.assert_row_ends_with(row, '$ ss')
+@tty.send_keys(TTYtest::RIGHT_ARROW)
+@tty.send_keys(TTYtest::RIGHT_ARROW)
+@tty.assert_cursor_position(START_COL + 2, row)
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_cursor_position(START_COL, row)
+@tty.send_keys(%(echo hello)) # make sure buffer is properly formed after backspaces
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')

data/examples/noncanonical_integration_tests.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'ttytest'
+
+START_COL = 19
+
+def assert_check_new_row(row)
+  @tty.assert_row_starts_with(row, "#{ENV['USER']}:")
+  @tty.assert_row_like(row, 'ncsh')
+  @tty.assert_row_ends_with(row, '$')
+  @tty.assert_cursor_position(START_COL, row)
+end
+
+@tty = TTYtest.new_terminal(%(PS1='$ ' ./bin/ncsh), width: 80, height: 24)
+
+row = 0
+
+# # # # Basic Tests # # # #
+puts 'Starting basic tests'
+
+@tty.assert_row_starts_with(row, 'ncsh: startup time: ')
+row += 1
+
+assert_check_new_row(row)
+@tty.send_keys_one_at_a_time(%(ls))
+@tty.assert_cursor_position(START_COL + 2, 1)
+@tty.send_newline
+@tty.assert_row_ends_with(row, 'ls')
+row += 1
+@tty.assert_row_starts_with(row, 'LICENSE')
+row = 9
+
+assert_check_new_row(row)
+@tty.send_keys_one_at_a_time(%(echo hello))
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')
+row += 1
+
+assert_check_new_row(row)
+@tty.send_keys_one_at_a_time(%(lss)) # send a bad command
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'ncsh: Could not find command or directory: No such file or directory')
+row += 1
+
+puts 'Starting backspace tests'
+
+# end of line backspace
+assert_check_new_row(row)
+@tty.send_keys_one_at_a_time(%(l))
+@tty.send_backspace
+assert_check_new_row(row)
+
+# multiple end of line backspaces
+@tty.send_keys_one_at_a_time(%(lsssss))
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_row_ends_with(row, '$ ls')
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_keys_one_at_a_time(%(echo hello)) # make sure buffer is properly formed after backspaces
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')
+row += 1
+
+# midline backspace
+assert_check_new_row(row)
+@tty.send_keys_one_at_a_time(%(lsssss))
+@tty.assert_cursor_position(START_COL + 6, row)
+@tty.send_keys(TTYtest::LEFT_ARROW)
+@tty.send_keys(TTYtest::LEFT_ARROW)
+@tty.assert_cursor_position(START_COL + 4, row)
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_cursor_position(START_COL, row)
+@tty.assert_row_ends_with(row, '$ ss')
+@tty.send_keys(TTYtest::RIGHT_ARROW)
+@tty.send_keys(TTYtest::RIGHT_ARROW)
+@tty.assert_cursor_position(START_COL + 2, row)
+@tty.send_backspace
+@tty.send_backspace
+@tty.assert_cursor_position(START_COL, row)
+@tty.send_keys_one_at_a_time(%(echo hello)) # make sure buffer is properly formed after backspaces
+@tty.send_newline
+row += 1
+@tty.assert_row(row, 'hello')

data/lib/ttytest/constants.rb

@@ -3,7 +3,6 @@
 # some constants that can be used with send_keys, just to help out people creating tests
 module TTYtest
   BACKSPACE = 127.chr
-  DELETE = '^[[3~'
   TAB = 9.chr
   CTRLF = 6.chr
   CTRLC = 3.chr

data/lib/ttytest/matchers.rb

@@ -3,10 +3,10 @@
 module TTYtest
   # Assertions for ttytest2.
   module Matchers
-    # Asserts the contents of a single row
+    # Asserts the contents of a single row match the value expected
     # @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
+    # @raise [MatchError] if the row doesn't match exactly
     def assert_row(row_number, expected)
       expected = expected.rstrip
       actual = row(row_number)
@@ -16,7 +16,25 @@ module TTYtest
             "expected row #{row_number} to be #{expected.inspect} but got #{actual.inspect}\nEntire screen:\n#{self}"
     end
 
-    # Asserts the contents of a single row contains expected
+    # Asserts the contents of a single row contains the expected string at a specific position
+    # @param [Integer] row_number the row (starting from 0) to test against
+    # @param [Integer] column_start the column position to start comparing expected against
+    # @param [Integer] columns_end the column position to end comparing expected against
+    # @param [String] expected the expected value that the row starts with. Any trailing whitespace is ignored
+    # @raise [MatchError] if the row doesn't match
+    def assert_row_at(row_number, column_start, column_end, expected)
+      expected = expected.rstrip
+      actual = row(row_number)
+      column_end += 1 if column_end.positive?
+      return if actual[column_start, column_end].eql?(expected)
+
+      raise MatchError,
+            "expected row #{row_number} to contain #{expected[column_start,
+                                                              column_end]} at #{column_start}-#{column_end} and got #{actual[column_start,
+                                                                                                                             column_end]}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the contents of a single row contains the value expected
     # @param [Integer] row_number the row (starting from 0) to test against
     # @param [String] expected the expected value contained in the row. Any trailing whitespace is ignored
     # @raise [MatchError] if the row doesn't match
@@ -29,7 +47,7 @@ module TTYtest
             "expected row #{row_number} to be like #{expected.inspect} but got #{actual.inspect}\nEntire screen:\n#{self}"
     end
 
-    # Asserts the contents of a single row start with expected
+    # Asserts the contents of a single row starts with expected string
     # @param [Integer] row_number the row (starting from 0) to test against
     # @param [String] expected the expected value that the row starts with. Any trailing whitespace is ignored
     # @raise [MatchError] if the row doesn't match

data/lib/ttytest/terminal.rb

@@ -21,13 +21,27 @@ module TTYtest
     # @!method send_keys(*keys)
     #   Simulate typing keys into the terminal. For canonical cli's/shells which read line by line.
     #   @param [String] keys keys to send to the terminal
-    # @!method send_keys_one_at_a_time(*keys)
+    # @!method send_keys_one_at_a_time(keys)
     #   Simulate typing keys into the terminal. For noncanonical cli's/shells which read character by character.
     #   @param [String] keys keys to send to the terminal
+    # @!method send_newline
+    #   Simulate typing enter by sending newline character to the terminal.
+    # @!method send_delete
+    #   Simulate typing the delete key in the terminal.
+    # @!method send_backspace
+    #   Simulate typing the backspace key in the terminal.
+    # @!method send_keys_exact
+    #   Send tmux send-keys command to the terminal, such as DC or Enter, to simulate pressing that key in 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, :send_keys_one_at_a_time, :send_newline, :capture
+    def_delegators :@driver_terminal,
+                   :send_keys, :send_keys_one_at_a_time,
+                   :send_newline, :send_newlines,
+                   :send_delete, :send_deletes,
+                   :send_backspace, :send_backspaces,
+                   :send_keys_exact,
+                   :capture
 
     # @!method rows
     #   @return [Array<String>]

data/lib/ttytest/tmux/session.rb

@@ -38,10 +38,15 @@ module TTYtest
         )
       end
 
+      # Send the array of keys as a string literal to tmux.
+      # Will not be interpreted as send-keys values like Enter, Escape, DC for Delete, etc.
+      # @param [%w()] keys the keys to send to tmux
       def send_keys(*keys)
         driver.tmux(*%W[send-keys -t #{name} -l], *keys)
       end
 
+      # Send a string of keys one character at a time as literals to tmux.
+      # @param [String] keys the keys to send one at a time to tmux
       def send_keys_one_at_a_time(keys)
         keys.split('').each do |key|
           driver.tmux(*%W[send-keys -t #{name} -l], key)
@@ -52,6 +57,43 @@ module TTYtest
         driver.tmux(*%W[send-keys -t #{name} -l], %(\n))
       end
 
+      def send_newlines(number_of_times)
+        while number_of_times.positive?
+          send_newline
+          number_of_times -= 1
+        end
+      end
+
+      def send_delete
+        send_keys_exact(%(DC))
+      end
+
+      def send_deletes(number_of_times)
+        while number_of_times.positive?
+          send_delete
+          number_of_times -= 1
+        end
+      end
+
+      def send_backspace
+        send_keys_exact(%(BSpace))
+      end
+
+      def send_backspaces(number_of_times)
+        while number_of_times.positive?
+          send_backspace
+          number_of_times -= 1
+        end
+      end
+
+      # Useful to send send-keys commands to tmux without sending them as a string literal.
+      # So you can send Escape for escape key, DC for delete, etc.
+      # Uses the same key bindings as bind-key as well. C-c represents Ctrl + C keys, F1 is F1 key, etc.
+      # @param [String] keys the keys to send to tmux
+      def send_keys_exact(keys)
+        driver.tmux(*%W[send-keys -t #{name}], keys)
+      end
+
       private
 
       attr_reader :driver, :name

data/lib/ttytest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TTYtest
-  VERSION = '0.8.6'
+  VERSION = '0.9.1'
 end

data/notes.txt

@@ -1,7 +1,7 @@
-to push new version to github,
-git tag v0.8.6
+to push new version to github
+git tag v0.9.1
 git push origin --tags
 
 to push new version to rubygems.org
 gem build ttytest2.gemspec
-gem push ttytest2-0.8.6.gem
+gem push ttytest2-0.9.1.gem

data/ttytest2.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['alexeski@gmail.com']
 
   spec.summary       = 'ttytest2 is an integration test framework for interactive tty applications. Based on TTYtest!'
-  spec.description   = 'ttytest2 allows running shell and/or cli applications inside of tmux and then making assertions on the output.'
+  spec.description   = 'ttytest2 allows running shell/cli applications inside of tmux and then making assertions on the output.'
   spec.homepage      = 'https://github.com/a-eski/ttytest2'
   spec.license       = 'MIT'
 
@@ -24,8 +24,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.2.3'
 
-  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'bundler', '~> 2.5'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ttytest2
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.9.1
 platform: ruby
 authors:
 - Alex Eski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-15 00:00:00.000000000 Z
+date: 2024-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -56,18 +56,18 @@ dependencies:
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: ttytest2 allows running shell and/or cli applications inside of tmux
-  and then making assertions on the output.
+        version: '0.9'
+description: ttytest2 allows running shell/cli applications inside of tmux and then
+  making assertions on the output.
 email:
 - alexeski@gmail.com
 executables: []
@@ -79,6 +79,8 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- examples/canonical_integration_tests.rb
+- examples/noncanonical_integration_tests.rb
 - lib/ttytest.rb
 - lib/ttytest/capture.rb
 - lib/ttytest/constants.rb