ttytest2 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15e01162a84bf95dce1f5694dfc57daa77decd5c7136af567c469d4e2148daa6
-  data.tar.gz: e29d3aae969a70b6bb0ba1003a87b4da7e2b819c0e80595f6a9604b11c52f7a8
+  metadata.gz: c7bf4ac747757d3aeaf01d103d15708cf487834ed43b9e3dad90e0d94e5203bc
+  data.tar.gz: 901c844e8719e6652943aae004e5f3deada174c4ab312e2e1c5956f496aa64c0
 SHA512:
-  metadata.gz: dd61cb3a8e293c928e1d3b5fcb3637273bd6a27a55ecae96ea737b1f0b6959df44c223aae366131175411320d0c185d3b3a339a128c519e43a4d75dbe8990147
-  data.tar.gz: 38a1a8dfa89b91b8209fb033fe2a7b3af161f4bfdc87dd07bc2f30154c1f925cf48b1c4697eef25a11773e1a65eb0422edd6811ffcef56559167709e85e63180
+  metadata.gz: '02128e6d6ada7be932b624b5dd48c4d7eef0ace8a3d727629f7c756f4e5b0027b00aa6fe96040a38ff84178e0b74256e644584376e8d6784c48728662e50af3d'
+  data.tar.gz: a2909a072f201511eed7e77b72a67143b0fb9caa2dac07aa583696aa040e88c34a2188644b1a0872d4309cfe8b2ef7e30d271a68b97f298b4334948dd879a3a6

data/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2016-2025 John Hawthorn
+Copyright (c) 2024-2025 Alex Eski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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
@@ -112,6 +116,8 @@ If you are reading this on github, the ruby docs accessible from [RubyDoc.Info](
 
 ### Available Assertions
 
+#### Row Assertions
+
 * `assert_row(row_number, expected_text)`
 
 * `assert_row_is_empty(row_number)`
@@ -128,12 +134,32 @@ 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)`
 
+#### Column Assertions
+
+* `assert_column(col_number, expected_text)`
+
+* `assert_column_is_empty(col_number)`
+
+* `assert_column_at(col_number, row_start, row_end, expected_str)`
+
+* `assert_column_starts_with(col_number, expected_text)`
+
+* `assert_column_ends_with(col_number, expected_text)`
+
+* `assert_column_regexp(col_number, regexp_str)`
+
+* `assert_columns_each_match_regexp(col_start, col_end, regexp_str)`
+
+#### Cursor Assertions
+
 * `assert_cursor_position(x: x, y: y)`
 
 * `assert_cursor_visible`
 
 * `assert_cursor_hidden`
 
+#### Screen Contents Assertions
+
 * `assert_contents(lines_of_terminal)`
 
 * `assert_contents_at(row_start, row_end, expected_text)`
@@ -144,6 +170,8 @@ If you are reading this on github, the ruby docs accessible from [RubyDoc.Info](
 
 * `assert_contents_match_regexp(regexp_str)`
 
+#### File Assertions
+
 * `assert_file_exists(file_path)`
 
 * `assert_file_doesnt_exist(file_path)`
@@ -162,17 +190,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 +216,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 +234,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 +279,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 +323,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 +337,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 +382,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,132 @@ 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 column 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?
+
+        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
+
+    # Asserts the contents of a single column contains the value expected
+    # @param [Integer] col_number the column number (starting from 0) to test against
+    # @param [String] expected the expected value contained in the column. Any trailing whitespace is ignored
+    # @raise [MatchError] if the column doesn't match
+    def assert_column_like(col_number, expected)
+      validate(col_number)
+      expected = expected.rstrip
+      actual = get_column(col_number).join
+
+      return if !actual.nil? && actual.include?(expected)
+
+      raise MatchError,
+            "expected column #{col_number} to be like #{expected.inspect} but got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+    alias assert_column_contains assert_column_like
+
+    # Asserts the contents of a single column starts with expected string
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @param [String] expected the expected value that the column starts with. Any trailing whitespace is ignored
+    # @raise [MatchError] if the column doesn't match
+    def assert_column_starts_with(col_number, expected)
+      validate(col_number)
+      expected = expected.rstrip
+      actual = get_column(col_number).join
+
+      return if !actual.nil? && actual.start_with?(expected)
+
+      raise MatchError,
+            "expected column #{col_number} to start with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the contents of a column ends with expected
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @param [String] expected the expected value that the column starts with. Any trailing whitespace is ignored
+    # @raise [MatchError] if the column doesn't match
+    def assert_column_ends_with(col_number, expected)
+      validate(col_number)
+      expected = expected.rstrip
+      actual = get_column(col_number).join
+
+      return if !actual.nil? && actual.end_with?(expected)
+
+      raise MatchError,
+            "expected column #{col_number} to end with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the contents of a single column match against the passed in regular expression
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @param [String] regexp_str the regular expression as a string that will be used to match with.
+    # @raise [MatchError] if the column doesn't match against the regular expression
+    def assert_column_regexp(col_number, regexp_str)
+      validate(col_number)
+      regexp = Regexp.new(regexp_str)
+      actual = get_column(col_number).join
+
+      return if !actual.nil? && actual.match?(regexp)
+
+      raise MatchError,
+            "expected column #{col_number} to match regexp #{regexp_str} but it did not. Column value #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the contents of a multiple columns each match against the passed in regular expression
+    # @param [Integer] col_start the column (starting from 0) to test against
+    # @param [Integer] col_end the last column to test against
+    # @param [String] regexp_str the regular expression as a string that will be used to match with.
+    # @raise [MatchError] if the column doesn't match against the regular expression
+    def assert_columns_each_match_regexp(col_start, col_end, regexp_str)
+      validate(col_end)
+      regexp = Regexp.new(regexp_str)
+      col_cur = col_start
+      col_end += 1 if col_end.zero?
+
+      while col_cur < col_end
+        actual = get_column(col_cur).join
+        col_cur += 1
+        next if !actual.nil? && actual.match?(regexp)
+
+        raise MatchError,
+              "expected column #{col_cur - 1} to match regexp #{regexp_str} but it did not. Column value #{get_inspection(actual)}\nEntire screen:\n#{self}"
+      end
+    end
+
+    private
+
+    def get_column(col_number)
+      actual = []
+
+      rows.each_with_index do |row, i|
+        break if row.nil?
+
+        actual[i] = row[col_number]
+      end
+
+      actual
+    end
   end
 end

data/lib/ttytest/assertions/exit_code_assertions.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # Exit Code Assertions for ttytest2. Not finished and added yet.
+  module ExitCodeAssertions
+    # Asserts that the exit code of the previous command matches the specified value
+    # Note: if you are tracking current row in your tests, this command will take up 2 lines.
+    # It echos the previous commands exit code to the screen and then reads it from there
+    # @param [Integer] code the expected exit code
+    # @raise [MatchError] if the exit code found does not match specified value
+    def assert_exit_code(code) end
+  end
+end

data/lib/ttytest/assertions/file_assertions.rb

@@ -61,7 +61,7 @@ module TTYtest
 
     # Asserts the specified file has line count specified
     # @param [String] file_path the path to the file
-    # @param [String] expected_count the expected line count of the file
+    # @param [Integer] expected_count the expected line count of the file
     # @raise [MatchError] if the file has a different line count than specified
     def assert_file_has_line_count(file_path, expected_count)
       raise file_not_found_error(file_path) unless File.exist?(file_path)

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
 
@@ -90,7 +89,7 @@ module TTYtest
     end
     alias assert_line_starts_with assert_row_starts_with
 
-    # Asserts the contents of a single row end with expected
+    # Asserts the contents of a single row ends with expected
     # @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/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.5.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.5.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.5.0.gem

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ttytest2
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Alex Eski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-12 00:00:00.000000000 Z
+date: 2025-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -92,6 +92,7 @@ files:
 - ".github/workflows/test.yml"
 - ".gitignore"
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - examples/integration_tests.rb
@@ -100,6 +101,7 @@ files:
 - lib/ttytest/assertions.rb
 - lib/ttytest/assertions/column_assertions.rb
 - lib/ttytest/assertions/cursor_assertions.rb
+- lib/ttytest/assertions/exit_code_assertions.rb
 - lib/ttytest/assertions/file_assertions.rb
 - lib/ttytest/assertions/row_assertions.rb
 - lib/ttytest/assertions/screen_assertions.rb