ttytest2 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9398a6955dc653c2993252568e64f7337c4f2e588a56a1f245ce130f3ec76f17
-  data.tar.gz: ebf03b94062e82e7a619d7b2dc45f07b90969509c92967343d59e91ede273972
+  metadata.gz: 196acc1f485c7ad416fbdbe07c94f0829bfb53a57c852a85bf79d72655f4debb
+  data.tar.gz: a2afc1f836dff32a2e2aa53a90137ce9bd768a20907855defae05da66af821e4
 SHA512:
-  metadata.gz: 342cd8770ec1cfd3f25c9522cc4d2da3a8dd70c51b79b860cb2b49955ae2c3e7b64acc8d2d49148d2b1df0fa512f6e9f02c87c7ffd4f70f59ba7fdfeb5f280f7
-  data.tar.gz: f197052ec70387690621d54fe280a29ab518e5ce40ffc52dbf1e2d45e04cc8401be782eeecd9502170053a49ab943394605c6d00d788f0f113472f2922412a36
+  metadata.gz: 762f9246cadb92d30ef2d8535b135cb9d72270d8e24bc100c8d18e18ecdd949e35560a7ff6fdc3b413a7dffbacbef56cf712c0b459b4cc3f8f7797dbfeca61d3
+  data.tar.gz: 2e099fda420602c981073d9cb39d9be307e261086ac8682ec4b213b6a061eded99a9ccff73df9e6c16a9157676fc4dea03a33d834d643fcfdf63631090807156

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/README.md

@@ -2,12 +2,30 @@
 
 ttytest2 is an acceptance test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
 
-A drop-in replacement for https://github.com/jhawthorn/ttytest, because I had some features I needed for my own project.
+A drop-in replacement for [ttytest](https://github.com/jhawthorn/ttytest), because I had some features I needed for my own project.
 
-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.
+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.
 
 [![Gem Version](https://badge.fury.io/rb/ttytest2.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/ttytest2)
 
+## Table of Contents
+
+1. [Minimum Requirements](#minimum-requirements)
+2. [Usage](#usage)
+3. [Example for Canonical CLI or Shell](#example-for-canonical-cli-or-shell)
+4. [Example for Noncanonical CLI or Shell](#example-for-noncanonical-cli-or-shell)
+5. [Assertions](#assertions)
+6. [Output](#output)
+7. [Output Helpers](#output-helpers)
+8. [Troubleshooting](#troubleshooting)
+9. [Constants](#constants)
+10. [Tips](#tips)
+11. [Docker](#docker)
+12. [Contributing](#contributing)
+13. [License](#license)
+
 ## Minimum Requirements
 
 * tmux >= 1.8
@@ -15,13 +33,72 @@ It works by running commands inside a tmux session, capturing the pane, and comp
 
 ## Usage
 
-More documentation available at [(https://www.rubydoc.info/gems/ttytest2)].
+More documentation available at [ttytest2 docs](https://www.rubydoc.info/gems/ttytest2).
+
+There are more examples in the examples folder.
+
+### Example for Canonical CLI or Shell
+
+Most people should use send_keys, if you are writing or working with a noncanonical shell/CLI, you will probably know it! Most shell/CLI applications are canonical.
+
+``` ruby
+require 'ttytest'
+
+@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/sh}, width: 80, height: 24)
+@tty.assert_row(0, '$')
+@tty.assert_cursor_position(x: 2, y: 0)
+
+@tty.send_keys(%{echo "Hello, world"\n})
+
+@tty.assert_contents <<TTY
+$ echo "Hello, world"
+Hello, world
+$
+TTY
+@tty.assert_cursor_position(x: 2, y: 2)
+
+@tty.print_rows # => ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ...]
+
+@tty.print # prints out the contents of the terminal
+```
+
+### Example for Noncanonical CLI or Shell
+
+If you are working with a noncanonical shell, you need to use send_keys_one_at_a_time to have your shell/CLI process the input correctly.
+
+Also useful if you need to send input one character at a time for whatever reason.
+
+'Multi-character' characters like '\n' need to be sent with send-keys, though.
+
+``` ruby
+require 'ttytest'
+
+@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/noncanonical-sh}, width: 80, height: 24)
+@tty.assert_row_starts_with(0, ENV['USER'])
+@tty.assert_row_ends_with(0, '$')
+
+@tty.send_keys_one_at_a_time('ls')
+@tty.assert_row_ends_with(0, 'ls')
+@tty.send_keys(%(\n)) # make sure to use send_keys for 'multi-character' characters like \n, \r, \t, etc.
+
+@tty.send_keys_one_at_a_time('ps')
+@tty.assert_row_ends_with(1, 'ps')
+@tty.send_keys(TTYtest:NEWLINE) # can use constants instead
+
+
+@tty.assert_row_starts_with(2, ENV['USER'])
+@tty.assert_row_ends_with(2, '$')
+@tty.send_newline # an alternative to the 2 above methods to send \n to the terminal
+
+puts "\n#{@tty.capture}" # prints out the contents of the terminal, equivalent to @tty.print
+```
 
 ### 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).
 
 Available assertions:
+
 * `assert_row(row_number, expected_text)`
 * `assert_row_at(row_number, column_start_position, column_end_position, expected_text)`
 * `assert_row_like(row_number, expected_text)`
@@ -32,7 +109,7 @@ Available assertions:
 * `assert_cursor_hidden`
 * `assert_contents(lines_of_terminal)`
 
-### Sending Output
+### Output
 
 You can send output to the terminal with the following calls.
 
@@ -58,74 +135,27 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_up_arrows(number_of_times)`
 * `send_down_arrow`
 * `send_down_arrows(number_of_times)`
+* `send_home` # simulate pressing the Home key
+* `send_end` # simulate pressing the End key
+* `send_clear` # clear the screen by sending clear ascii code
 
 ### Troubleshooting
 
 You can use the method rows to get all rows of the terminal as an array, of use the method capture to get the contents of the terminal window. This can be useful when troubleshooting.
 
 ``` ruby
-p @tty.rows # prints out the contents of the terminal as a array => ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ...]
-puts "\n#{@tty.capture}" # prints out the contents of the terminal
-```
-
-### Example Canonical CLI/Shell
-
-Most people should use send_keys, if you are writing or working with a noncanonical shell/CLI, you will probably know it! Most shell/CLI applications are canonical.<br /><br />
-There are more examples in the examples folder.
-
-``` ruby
-require 'ttytest'
-
-@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/sh}, width: 80, height: 24)
-@tty.assert_row(0, '$')
-@tty.assert_cursor_position(x: 2, y: 0)
-
-@tty.send_keys(%{echo "Hello, world"\n})
-
-@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", "$", "", "", "", ...]
-
-puts "\n#{@tty.capture}" # prints out the contents of the terminal
-```
-
-### Example Noncanonical CLI/Shell
-
-If you are working with a noncanonical shell, you need to use send_keys_one_at_a_time to have your shell/CLI process the input correctly.<br /><br />
-Also useful if you need to send input one character at a time for whatever reason.<br /><br />
-'Multi-character' characters like '\n' need to be sent with send-keys, though.<br /><br />
-There are more examples in the examples folder.
-
-``` ruby
-require 'ttytest'
-
-@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/noncanonical-sh}, width: 80, height: 24)
-@tty.assert_row_starts_with(0, ENV['USER'])
-@tty.assert_row_ends_with(0, '$')
-
-@tty.send_keys_one_at_a_time('ls')
-@tty.assert_row_ends_with(0, 'ls')
-@tty.send_keys(%(\n)) # make sure to use send_keys for 'multi-character' characters like \n, \r, \t, etc.
-
-@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
+# you can use @tty.rows to access the entire pane, split by line into an array.
+p @tty.rows # prints out the contents of the terminal as a array.
+@tty.print_rows # equivalent to above, just for ease of use.
 
-puts "\n#{@tty.capture}" # prints out the contents of the terminal
+# you can use @tty.capture to access the entire pane.
+p "\n#{@tty.capture}" # prints out the contents of the terminal
+@tty.print # equivalent to above, just for ease of use.
 ```
 
 ### Constants
 
-There are some commonly used keys available as constants to make interacting with your shell/CLI easy. Most of them are self-evident, BACKSPACE is the same as hitting the backspace key on the keyboard.
+There are some commonly used keys available as constants to make interacting with your shell/CLI easy.
 
 ``` ruby
   TTYtest::BACKSPACE
@@ -143,6 +173,12 @@ There are some commonly used keys available as constants to make interacting wit
   TTYtest::CLEAR # clear the screen
 ```
 
+### Tips
+
+If you are using ttyest2 to test your CLI, using sh is easier than bash because you don't have to worry about user, current working directory, etc. as shown in the examples above.
+
+If you are using ttytest2 to test your shell, using assertions like assert_row_like, assert_row_starts_with, and assert_row_ends_with are going to be extremely helpful, especially if trying to test your shell in different environments or using a docker container.
+
 ## Docker
 
 Easy to use from Docker. Add this to your dockerfile to get started.
@@ -158,7 +194,7 @@ RUN apt update && \
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/a-eski/ttytest2.
+Bug reports and pull requests are welcome on GitHub at [ttytest2](https://github.com/a-eski/ttytest2).
 
 ## License
 

data/examples/canonical_integration_tests.rb

@@ -1,6 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# example testing a noncanonical shell, ncsh
+
 require 'ttytest'
 
 START_COL = 19
@@ -55,13 +57,9 @@ 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_backspaces(4)
+@tty.assert_row_ends_with(row, 'ls')
+@tty.send_backspaces(2)
 @tty.send_keys(%(echo hello)) # make sure buffer is properly formed after backspaces
 @tty.send_newline
 row += 1
@@ -72,20 +70,14 @@ row += 1
 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.send_left_arrows(2)
 @tty.assert_cursor_position(START_COL + 4, row)
-@tty.send_backspace
-@tty.send_backspace
-@tty.send_backspace
-@tty.send_backspace
+@tty.send_backspaces(4)
 @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.send_right_arrows(2)
 @tty.assert_cursor_position(START_COL + 2, row)
-@tty.send_backspace
-@tty.send_backspace
+@tty.send_backspaces(2)
 @tty.assert_cursor_position(START_COL, row)
 @tty.send_keys(%(echo hello)) # make sure buffer is properly formed after backspaces
 @tty.send_newline

data/examples/noncanonical_integration_tests.rb

@@ -1,25 +1,24 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# example testing a canonical shell called shl
+
 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_like(row, 'shl')
   @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)
+@tty = TTYtest.new_terminal(%(PS1='$ ' ./bin/shl), width: 80, height: 24)
 
 row = 0
 
-# # # # Basic Tests # # # #
-puts 'Starting basic tests'
-
-@tty.assert_row_starts_with(row, 'ncsh: startup time: ')
+@tty.assert_row_starts_with(row, 'shl: startup time: ')
 row += 1
 
 assert_check_new_row(row)
@@ -42,11 +41,9 @@ 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')
+@tty.assert_row(row, 'shl: 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))
@@ -55,13 +52,9 @@ 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.send_backspaces(4)
 @tty.assert_row_ends_with(row, '$ ls')
-@tty.send_backspace
-@tty.send_backspace
+@tty.send_backspaces(2)
 @tty.send_keys_one_at_a_time(%(echo hello)) # make sure buffer is properly formed after backspaces
 @tty.send_newline
 row += 1
@@ -72,20 +65,14 @@ row += 1
 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.send_left_arrows(2)
 @tty.assert_cursor_position(START_COL + 4, row)
-@tty.send_backspace
-@tty.send_backspace
-@tty.send_backspace
-@tty.send_backspace
+@tty.send_backspaces(4)
 @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.send_right_arrows(2)
 @tty.assert_cursor_position(START_COL + 2, row)
-@tty.send_backspace
-@tty.send_backspace
+@tty.send_backspaces(2)
 @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

data/lib/ttytest/capture.rb

@@ -48,6 +48,14 @@ module TTYtest
       self
     end
 
+    def print
+      puts "\n#{self}"
+    end
+
+    def print_rows
+      puts rows
+    end
+
     # @return [String] All rows of the captured terminal, separated by newlines
     def to_s
       rows.join("\n")

data/lib/ttytest/constants.rb

@@ -14,5 +14,5 @@ module TTYtest
   RIGHT_ARROW = "#{ESCAPE}[C".freeze
   LEFT_ARROW = "#{ESCAPE}[D".freeze
 
-  CLEAR = 'clear'
+  CLEAR = "#{ESCAPE}[2J".freeze
 end

data/lib/ttytest/terminal.rb

@@ -26,15 +26,48 @@ module TTYtest
     #   @param [String] keys keys to send to the terminal
     # @!method send_newline
     #   Simulate typing enter by sending newline character to the terminal.
+    # @!method send_newlines
+    #   Simulates sending newline the specified number of times.
+    #   @param [Integer] number of times to send newline
     # @!method send_delete
     #   Simulate typing the delete key in the terminal.
+    # @!method send_deletes
+    #   Simulates typing delete the specified number of times.
+    #   @param [Integer] number of times to send delete
     # @!method send_backspace
     #   Simulate typing the backspace key in the terminal.
+    # @!method send_backspaces
+    #   Simulates typing backspace the specified number of times.
+    #   @param [Integer] number of times to send backspace
+    # @!method send_left_arrow
+    #   Simulate typing the left arrow key in the terminal.
+    # @!method send_left_arrows
+    #   Simulates typing left arrow the specified number of times.
+    #   @param [Integer] number of times to send left arrow
+    # @!method send_right_arrow
+    #   Simulate typing the right arrow key in the terminal.
+    # @!method send_right_arrows
+    #   Simulates typing right arrow the specified number of times.
+    #   @param [Integer] number of times to send right arrow
+    # @!method send_down_arrow
+    #   Simulate typing the down arrow key in the terminal.
+    # @!method send_down_arrows
+    #   Simulates typing the down arrow the specified number of times.
+    #   @param [Integer] number of times to send down arrow
+    # @!method send_up_arrow
+    #   Simulate typing the up arrow key in the terminal.
+    # @!method send_up_arrows
+    #   Simulates typing the up arrow the specified number of times.
+    #   @param [Integer] number of times to send up arrow
     # @!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
+    # @!method print
+    #   Prints the current state of the terminal to stdout. See capture to get the raw string.
+    # @!method print_rows
+    #   Prints the current state of the terminal as an array to stdout. See rows to get the raw array.
     def_delegators :@driver_terminal,
                    :send_keys, :send_keys_one_at_a_time,
                    :send_newline, :send_newlines,
@@ -42,7 +75,7 @@ module TTYtest
                    :send_backspace, :send_backspaces,
                    :send_left_arrow, :send_left_arrows, :send_right_arrow, :send_right_arrows,
                    :send_down_arrow, :send_down_arrows, :send_up_arrow, :send_up_arrows,
-                   :send_keys_exact,
+                   :send_keys_exact, :send_home, :send_end, :send_clear,
                    :capture
 
     # @!method rows
@@ -69,7 +102,11 @@ module TTYtest
     # @!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?
+    def_delegators :capture, :print, :print_rows,
+                   :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/session.rb

@@ -138,6 +138,19 @@ module TTYtest
         driver.tmux(*%W[send-keys -t #{name}], keys)
       end
 
+      def send_home
+        send_keys_exact(%(Home))
+      end
+
+      def send_end
+        send_keys_exact(%(End))
+      end
+
+      def send_clear
+        send_keys_one_at_a_time(TTYtest::CLEAR)
+        send_newline
+      end
+
       private
 
       attr_reader :driver, :name

data/lib/ttytest/version.rb

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

data/notes.txt

@@ -1,7 +1,7 @@
 to push new version to github
-git tag v0.9.4
+git tag v0.9.6
 git push origin --tags
 
 to push new version to rubygems.org
 gem build ttytest2.gemspec
-gem push ttytest2-0.9.4.gem
+gem push ttytest2-0.9.6.gem

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ttytest2
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.6
 platform: ruby
 authors:
 - Alex Eski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-22 00:00:00.000000000 Z
+date: 2024-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler