ttytest2 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e01162a84bf95dce1f5694dfc57daa77decd5c7136af567c469d4e2148daa6
-  data.tar.gz: e29d3aae969a70b6bb0ba1003a87b4da7e2b819c0e80595f6a9604b11c52f7a8
+  metadata.gz: 360be4f6d7358f00c2462a247939072ab8e93e1b64f9465112c62b6f9a22a484
+  data.tar.gz: 7ede22ea96c9ce32546111761d730c008da042b997914e59b6d63bf1e4b06d69
 SHA512:
-  metadata.gz: dd61cb3a8e293c928e1d3b5fcb3637273bd6a27a55ecae96ea737b1f0b6959df44c223aae366131175411320d0c185d3b3a339a128c519e43a4d75dbe8990147
-  data.tar.gz: 38a1a8dfa89b91b8209fb033fe2a7b3af161f4bfdc87dd07bc2f30154c1f925cf48b1c4697eef25a11773e1a65eb0422edd6811ffcef56559167709e85e63180
+  metadata.gz: 739fde4fb24d1a2a2a6179c5433be0191587f6e6f4aad92c495880991140569ad82821e8e3285bca1cd908f067adb3d404fd70c696b8cb1d973ee4d3fbb8349a
+  data.tar.gz: 7c4472bb3d2cebfbbcf29edb62cbee8f16c8ae84bcd59e8263c108f71e0db89da1ab7fdd1c9c8dfa06f2047b9bae8d7e9e0016718a9ddcfb2ac89d91407efe10

data/README.md

@@ -4,13 +4,13 @@
 <img src="images/ttytest2.png" alt="ttytest2 logo" style="width:70%; height:auto;">
 </a>
 
-ttytest2 is a user acceptance test framework for CLI & shell applications.
+ttytest2 is a integration test framework for CLI, TUI, & shell applications.
 
 ttytest2 is a fork and a drop-in replacement for [ttytest](https://github.com/jhawthorn/ttytest).
 
 It works by creating a tmux session behind the scenes, running the specified commands, capturing the pane, and then comparing the actual content to the expected content based on the assertions made.
 
-The assertions will wait a specified amount of time (configurable, default 2 seconds) for the expected content to appear.
+The assertions will wait a configuable amount of time (default 2 seconds) for the expected content to appear before failing.
 
 [![Gem Version](https://badge.fury.io/rb/ttytest2.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/ttytest2)
 
@@ -38,6 +38,8 @@ The assertions will wait a specified amount of time (configurable, default 2 sec
 * Download the [gem](https://rubygems.org/gems/ttytest2) here.
 * More documentation available at [ttytest2 docs](https://www.rubydoc.info/gems/ttytest2).
 * There are more examples in the examples folder.
+* Synchronous example: [ncsh synchronous tests](https://github.com/a-eski/ncsh/blob/main/acceptance_tests/tests/acceptance_tests.rb)
+* Concurrent & generated example: [ncsh concurrent tests](https://github.com/a-eski/ncsh/blob/main/acceptance_tests/minitest/tests.rb)
 
 ### Simple Example
 
@@ -77,11 +79,11 @@ TTY
 
 Call one of these methods to initialize an instance of ttytest2.
 
-* `new_terminal(cmd, width, height)`: initialize new tmux terminal instance and run cmd.
+* `new_terminal(cmd, width, height, max_wait_time, use_return_for_newline)`: initialize new tmux terminal instance and run cmd.
 
 * `new_default_sh_terminal()`: intialize new tmux terminal instance using sh, width of 80, height of 24.
 
-* `new_sh_terminal(width, height)`: intialize new tmux terminal instance using sh and width and height parameters.
+* `new_sh_terminal(width, height, max_wait_time, use_return_for_newline)`: intialize new tmux terminal instance using sh.
 
 ``` ruby
 require 'ttytest'
@@ -96,6 +98,8 @@ require 'ttytest'
 # you can also use other shells, like bash
 @tty = TTYtest.new_terminal('/bin/bash')
 @tty = TTYtest.new_terminal('/bin/bash', width: 80, height: 24)
+
+# you can specify further options, see section Configurables.
 ```
 
 ## Assertions
@@ -128,6 +132,12 @@ If you are reading this on github, the ruby docs accessible from [RubyDoc.Info](
 
 * `assert_rows_each_match_regexp(row_start, row_end, regexp_str)`
 
+* `assert_column(col_number, expected_text)`
+
+* `assert_column_is_empty(col_number)`
+
+* `assert_column_at(col_number, row_start, row_end, expected_str)`
+
 * `assert_cursor_position(x: x, y: y)`
 
 * `assert_cursor_visible`
@@ -162,17 +172,17 @@ Note: Most of the time send_line has the best ergonomics.
 
 ### Base Functions
 
-These functions form the basis of interacting with the tmux pane. They power all other functions, but you can use them directly when needed.
+These functions form the basis of interacting with the tmux pane. Internally they power the other functions, but you can also use them directly.
 
-* `send_keys(output)`: for canonical shells/CLI's (or multi-character keys for noncanonical shells/CLI's).
+* `send_keys(output)`: for canonical apps (or multi-character keys for noncanonical apps).
 
-* `send_keys_one_at_a_time(output)`: for noncanonical shells/CLI's.
+* `send_keys_one_at_a_time(output)`: for noncanonical apps.
 
-* `send_keys_exact(output)`: sends keys as is, exactly. Also useful for sending tmux specific keys (any supported tmux send-keys arguments like: DC for delete, Escape for ESC, etc.)
+* `send_keys_exact(output)`: sends keys as is, exactly. Also useful for sending tmux specific keys (any tmux send-keys arguments like: DC (delete), Escape (ESC), etc.)
 
 ### Ergonomic Functions
 
-The base functions work great, but these functions build upon the base functions to provide more functionality and better ergonomics in most cases.
+The base functions work great, but these functions build upon the base functions to provide more functionalities and better ergonomics.
 
 For example, `send_line(line)` makes sure that the enter key (newline character) is sent after the `line` so you don't have to worry about adding it to `line` or calling send_newline after.
 
@@ -188,8 +198,14 @@ For example, `send_line(line)` makes sure that the enter key (newline character)
 
 * `send_line_exact`: send line exactly as is to tmux. Certain special characters may not work with send_line. You can also include tmux send-keys arguments like DC for delete, etc.
 
+* `send_line_exact_then_sleep(line, sleep_time)`: simulate typing in a command in the terminal and hitting enter using send_line_exact semantics, then wait for sleep_time seconds.
+
 * `send_lines_exact`: send lines exactly are they are to tmux. Similar semantics to send_line_exact.
 
+* `send_lines_exact_then_sleep(lines, sleep_time)`: for each line in lines, simulate sending the line and hitting enter using send_line_exact semantics. After sending all the lines, sleep for sleep_time.
+
+* `send_line_exact_then_sleep_and_repeat(lines, sleep_time)`: for each line in lines, simulate sending the line and hitting enter using send_line_exact, then sleep before sending the next line.
+
 ### Output Helpers
 
 Helper functions to make sending output easier! They use the methods above under 'Sending Output' section under the hood.
@@ -200,7 +216,6 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_return` # simulate hitting enter, equivalent to @tty.send_keys(%(\r))
 * `send_returns(number_of_times)` # equivalent to calling send_return number_of_times
 
-
 * `send_backspace` # simulate hitting backspace, equivalent to @tty.send_keys(TTYtest::BACKSPACE)
 * `send_backspaces(number_of_times)` # equivalent to calling send_backspace number_of_times
 
@@ -246,9 +261,12 @@ Send F keys like F1, F2, etc. as shown below:
 
 ### Constants
 
-There are some commonly used keys available as constants to make interacting with your shell/CLI easy.
+Commonly used keys are available as constants to simplify use.
 
 ``` ruby
+# can use like:
+  send_keys_exact(TTYtest::CTRLA)
+
   TTYtest::CTRLA
   TTYtest::CTRLB
   TTYtest::CTRLC
@@ -287,7 +305,7 @@ There are 2 main configurations for ttytest2: max_wait_time, and use_return_for_
 
 ### Max wait time
 
-Max wait time represents the amount of time in seconds that ttytest2 will keep retrying an assertion before failing.
+Max wait time represents the amount of time in seconds that ttytest2 will keep retrying an assertion before failing that assertion.
 
 You can configure max wait time as shown below.
 
@@ -301,7 +319,7 @@ You can configure max wait time as shown below.
 
 ### Use return for newline
 
-Use return for newline tells ttytest2 to use return ('//r') instead of newline ('//n') for methods like send_line.
+Use return for newline tells ttytest2 to use return ('/r') instead of newline ('/n') for methods like send_line, send_line_exact, etc.
 
 Some line readers may interpreter return and newline differently, so this can be useful in those cases.
 
@@ -346,11 +364,11 @@ p "\n#{@tty.capture}" # this is equivalent to above statement @tty.print
 
 ## 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.
+If you are using ttyest2 to test your CLI, using sh can be easier than bash because you don't have to worry about user, current working directory, etc. as shown in the examples.
 
-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.
+The assertions like `assert_row_like`, `assert_row_starts_with`, and `assert_row_ends_with` are usually extremely helpful, especially if trying to test your application in different environments or using a docker container with a shell that is not sh.
 
-Most line readers use '\n' for newline, but some may interpret it differently and expect '\r'.
+Most line readers use '\n' for newline, but some may interpret newline and return differently or expect '\r' for the enter key.
 
 ## Docker
 

data/lib/ttytest/assertions/column_assertions.rb

@@ -37,5 +37,36 @@ module TTYtest
               "expected column #{col_number} to be empty\nEntire screen:\n#{self}"
       end
     end
+
+    # Asserts the contents of a column contain the expected string at the specified position
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @param [Integer] row_start the row position to start comparing expected against
+    # @param [Integer] row_end the row position to end comparing expected against (inclusive)
+    # @param [String] expected the expected value that the row starts with. Any trailing whitespace is ignored
+    # @raise [MatchError] if the column doesn't match
+    def assert_column_at(col_number, row_start, row_end, expected)
+      validate(col_number)
+      expected = expected.rstrip
+      actual = []
+
+      rows.each_with_index do |row, i|
+        next if i < row_start
+        break if i > row_end || row.nil? || row == ''
+
+        actual[i - row_start] = row[col_number]
+        next if row[col_number] == expected[i - row_start]
+
+        raise MatchError,
+              "expected column #{col_number} to be #{expected.inspect}\n
+            Entire screen:\n#{self}"
+      end
+
+      return if !actual.nil? && actual.join.eql?(expected)
+
+      inspection = get_inspection(actual.join)
+
+      raise MatchError,
+            "expected column #{col_number} to contain #{expected} at #{row_start}-#{row_end} and got #{inspection}\nEntire screen:\n#{self}"
+    end
   end
 end

data/lib/ttytest/assertions/row_assertions.rb

@@ -34,7 +34,7 @@ module TTYtest
     end
     alias assert_line_is_empty assert_row_is_empty
 
-    # Asserts the contents of a single row contains the expected string at a specific position
+    # Asserts the contents of a row contain the expected string at the specified 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
@@ -51,8 +51,7 @@ module TTYtest
       inspection = get_inspection_bounded(actual, column_start, column_end)
 
       raise MatchError,
-            "expected row #{row_number} to contain #{expected[column_start,
-                                                              column_end]} at #{column_start}-#{column_end} and got #{inspection}\nEntire screen:\n#{self}"
+            "expected row #{row_number} to contain #{expected} at #{column_start}-#{column_end} and got #{inspection}\nEntire screen:\n#{self}"
     end
     alias assert_line_at assert_row_at
 

data/lib/ttytest/tmux/session.rb

@@ -78,6 +78,19 @@ module TTYtest
         end
       end
 
+      def send_lines_then_sleep(*lines, sleep_time)
+        lines.each do |line|
+          send_line(line)
+        end
+        sleep sleep_time
+      end
+
+      def send_line_then_sleep_and_repeat(*lines, sleep_time)
+        lines.each do |line|
+          send_line_then_sleep(line, sleep_time)
+        end
+      end
+
       def send_line_exact(line)
         send_keys_exact(line)
         if @use_return_for_newline
@@ -87,22 +100,28 @@ module TTYtest
         send_newline unless line[-1] == '\n'
       end
 
+      # Send line then sleep for sleep_time
+      def send_line_exact_then_sleep(line, sleep_time)
+        send_line_exact(line)
+        sleep sleep_time
+      end
+
       def send_lines_exact(*lines)
         lines.each do |line|
           send_line_exact(line)
         end
       end
 
-      def send_lines_then_sleep(*lines, sleep_time)
+      def send_lines_exact_then_sleep(*lines, sleep_time)
         lines.each do |line|
-          send_line(line)
+          send_line_exact(line)
         end
         sleep sleep_time
       end
 
-      def send_line_then_sleep_and_repeat(*lines, sleep_time)
+      def send_line_exact_then_sleep_and_repeat(*lines, sleep_time)
         lines.each do |line|
-          send_line_then_sleep(line, sleep_time)
+          send_line_exact_then_sleep(line, sleep_time)
         end
       end
 

data/lib/ttytest/version.rb

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

data/lib/ttytest.rb

@@ -22,12 +22,12 @@ module TTYtest
 
     # @!method new_default_sh_terminal
     #   Create a new terminal using '/bin/sh' with width: 80 and height: 24.
-    #   Useful for Unixes.
+    #   Useful for applications like shells which may show user or the cwd.
     #   @return [Terminal] a new sh terminal
 
     # @!method new_sh_terminal(width: 80, height: 24)
     #   Create a new terminal using '/bin/sh' with ability to set width and height.
-    #   Useful for Unixes.
+    #   Useful for applications like shells which may show user or the cwd.
     #   @param [Integer] max_wait_time max time to wait for screen to update before an assertion fails
     #   @param [bool] use_return_for_newline use return instead of newline for functions like send_line
     #   @return [Terminal] a new sh terminal with specified width and height
@@ -35,8 +35,6 @@ module TTYtest
     def_delegators :driver
 
     def new_terminal(cmd, width: 80, height: 24, max_wait_time: 2, use_return_for_newline: false)
-      # @max_wait_time = max_wait_time
-      # @use_return_for_newline = use_return_for_newline
       driver.new_terminal(cmd, width: width, height: height, max_wait_time: max_wait_time,
                                use_return_for_newline: use_return_for_newline)
     end

data/notes.txt

@@ -1,7 +1,7 @@
 to push new version to github
-git tag v1.3.0
+git tag v1.4.0
 git push origin --tags
 
 to push new version to rubygems.org
 gem build ttytest2.gemspec
-gem push ttytest2-1.3.0.gem
+gem push ttytest2-1.4.0.gem

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ttytest2
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Alex Eski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-12 00:00:00.000000000 Z
+date: 2025-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler