ttytest2 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47258d8644be543f645de9e34a17eca3a0e38c5fb764e4e72f4d78a63a888388
-  data.tar.gz: 4aa9221ee6fc4f5e8fda754b2cd3b9c8218d7b8cf1e7e8b67dfe2a36dd9360b8
+  metadata.gz: 15e01162a84bf95dce1f5694dfc57daa77decd5c7136af567c469d4e2148daa6
+  data.tar.gz: e29d3aae969a70b6bb0ba1003a87b4da7e2b819c0e80595f6a9604b11c52f7a8
 SHA512:
-  metadata.gz: f20f297c6b30fb549ade96a5a2644f11e9ad846f0e8950f5e119bcfc83a63228dcbe51b75e635fdcfeb0bd47b17122bf568e574305406582cf4a0e9978356137
-  data.tar.gz: 0ee8c938c0b66151ba208c1769bfd5ac65277d1c62dbc3ede3976926dfef964870a7119b6003601c4f2fb0c7a90cc2d6736e8cffc9df86de81d7f6efc5c2877a
+  metadata.gz: dd61cb3a8e293c928e1d3b5fcb3637273bd6a27a55ecae96ea737b1f0b6959df44c223aae366131175411320d0c185d3b3a339a128c519e43a4d75dbe8990147
+  data.tar.gz: 38a1a8dfa89b91b8209fb033fe2a7b3af161f4bfdc87dd07bc2f30154c1f925cf48b1c4697eef25a11773e1a65eb0422edd6811ffcef56559167709e85e63180

data/README.md

@@ -1,5 +1,9 @@
 # ttytest2
 
+<a href="https://rubygems.org/gems/ttytest2">
+<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 fork and a drop-in replacement for [ttytest](https://github.com/jhawthorn/ttytest).
@@ -31,6 +35,7 @@ The assertions will wait a specified amount of time (configurable, default 2 sec
 
 ## Usage
 
+* 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.
 
@@ -191,8 +196,10 @@ Helper functions to make sending output easier! They use the methods above under
 
 * `send_newline` # simulate hitting enter, equivalent to @tty.send_keys(%(\n))
 * `send_newlines(number_of_times)` # equivalent to calling send_newline number_of_times
-* `send_enter` # alias for send_newline
-* `send_enters(number_of_times)` # alias for send_newlines
+
+* `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
@@ -220,6 +227,9 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_escape`
 * `send_escapes(number_of_times)`
 
+* `send_tab`
+* `send_tab(number_of_times)`
+
 ### F keys?
 
 Send F keys like F1, F2, etc. as shown below:
@@ -253,7 +263,7 @@ There are some commonly used keys available as constants to make interacting wit
   TTYtest::SHIFT_ENTER # \v
   TTYtest::FORM_FEED # \f or New Page NP
   TTYtest::CTRLL
-  TTYtest::CARRIAGE_RETURN # \r
+  TTYtest::RETURN # \r
   TTYtest::CTRLU
   TTYtest::CTRLW
   TTYtest::ESCAPE # 27 decimal or ^[ or /033
@@ -273,7 +283,9 @@ There are some commonly used keys available as constants to make interacting wit
 
 ## Configurables
 
-Currently the only configuration for ttytest2 is max wait time.
+There are 2 main configurations for ttytest2: max_wait_time, and use_return_for_newline.
+
+### Max wait time
 
 Max wait time represents the amount of time in seconds that ttytest2 will keep retrying an assertion before failing.
 
@@ -287,6 +299,24 @@ You can configure max wait time as shown below.
 @tty.assert_row(0, 'echo Hello, world') # this assertion would fail after 3 seconds
 ```
 
+### Use return for newline
+
+Use return for newline tells ttytest2 to use return ('//r') instead of newline ('//n') for methods like send_line.
+
+Some line readers may interpreter return and newline differently, so this can be useful in those cases.
+
+You can still send newline via send_newline when this is enabled.
+
+You can also send return by itself with send_return.
+
+``` ruby
+@tty = TTYtest::new_terminal('', use_return_for_newline: true) # specified to use return in place of newline
+
+@tty.send_line('hello, world!') # will have return sent after 'hello, world!'
+@tty.use_return_for_newline = false
+@tty.assert_row(0, 'echo Hello, world') # will have newline sent after 'echo Hello, world'
+```
+
 ## 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.
@@ -320,6 +350,8 @@ If you are using ttyest2 to test your CLI, using sh is easier than bash because
 
 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.
 
+Most line readers use '\n' for newline, but some may interpret it differently and expect '\r'.
+
 ## Docker
 
 Easy to use from Docker. Add this to your dockerfile to get started.

data/lib/ttytest/assertions/column_assertions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # Column Assertions for ttytest2.
+  module ColumnAssertions
+    # Asserts the contents of a single column match the value expected
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @param [String] expected the expected value of the column. Any trailing whitespace is ignored
+    # @raise [MatchError] if the column doesn't match exactly
+    def assert_column(col_number, expected)
+      validate(col_number)
+      expected = expected.rstrip
+
+      rows.each_with_index do |row, i|
+        break if row.nil?
+
+        next if row[col_number] == expected[i]
+
+        raise MatchError,
+              "expected column #{col_number} to be #{expected.inspect}\n
+            Entire screen:\n#{self}"
+      end
+    end
+
+    # Asserts the specified column is empty
+    # @param [Integer] col_number the column (starting from 0) to test against
+    # @raise [MatchError] if the column isn't empty
+    def assert_column_is_empty(col_number)
+      validate(col_number)
+
+      rows.each do |row|
+        break if row.nil?
+
+        next if row == '' || row.length < col_number + 1 || row[col_number] == ' '
+
+        raise MatchError,
+              "expected column #{col_number} to be empty\nEntire screen:\n#{self}"
+      end
+    end
+  end
+end

data/lib/ttytest/assertions/cursor_assertions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # Cursor Assertions for ttytest2.
+  module CursorAssertions
+    # 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]
+
+      return if actual == expected
+
+      raise MatchError,
+            "expected cursor to be at #{expected.inspect} but was at #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the cursor is currently visible
+    # @raise [MatchError] if the cursor is hidden
+    def assert_cursor_visible
+      return if cursor_visible?
+
+      raise MatchError, "expected cursor to be visible was hidden\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the cursor is currently hidden
+    # @raise [MatchError] if the cursor is visible
+    def assert_cursor_hidden
+      return if cursor_hidden?
+
+      raise MatchError, "expected cursor to be hidden was visible\nEntire screen:\n#{self}"
+    end
+  end
+end

data/lib/ttytest/assertions/file_assertions.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # File Assertions for ttytest2.
+  module FileAssertions
+    # Asserts the specified file exists
+    # @param [String] file_path the path to the file
+    # @raise [MatchError] if the file is not found or is a directory/symlink
+    def assert_file_exists(file_path)
+      raise file_not_found_error(file_path) unless File.exist?(file_path)
+      raise file_is_dir_error(file_path) unless File.file?(file_path)
+    end
+
+    # Asserts the specified file does not exists
+    # @param [String] file_path the path to the file
+    # @raise [MatchError] if the file is found or is a directory/symlink
+    def assert_file_doesnt_exist(file_path)
+      return unless File.exist?(file_path) || File.file?(file_path)
+
+      raise MatchError,
+            "File with path #{file_path} was found or is a directory when it was asserted it did not exist.\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the specified file contains the passed in string value
+    # @param [String] file_path the path to the file
+    # @param [String] needle the value to search for in the file
+    # @raise [MatchError] if the file does not contain value in variable needle
+    def assert_file_contains(file_path, needle)
+      raise file_not_found_error(file_path) unless File.exist?(file_path)
+      raise file_is_dir_error(file_path) unless File.file?(file_path)
+
+      file_contains = false
+      File.foreach(file_path) do |line|
+        if line.include?(needle)
+          file_contains = true
+          break
+        end
+      end
+      return if file_contains
+
+      raise MatchError,
+            "File with path #{file_path} did not contain #{needle}.\nEntire screen:\n#{self}"
+    end
+    alias assert_file_like assert_file_contains
+
+    # Asserts the specified file has the permissions specified
+    # @param [String] file_path the path to the file
+    # @param [String] permissions the expected permissions of the file (in form '644' or '775')
+    # @raise [MatchError] if the file has different permissions than specified
+    def assert_file_has_permissions(file_path, permissions)
+      raise file_not_found_error(file_path) unless File.exist?(file_path)
+      raise file_is_dir_error(file_path) unless File.file?(file_path)
+
+      file_mode = File.stat(file_path).mode
+      perms_octal = format('%o', file_mode)[-3...]
+      return if perms_octal == permissions
+
+      raise MatchError,
+            "File had permissions #{perms_octal}, not #{permissions} as expected.\n Entire screen:\n#{self}"
+    end
+
+    # 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
+    # @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)
+      raise file_is_dir_error(file_path) unless File.file?(file_path)
+
+      actual_count = File.foreach(file_path).count
+      return if actual_count == expected_count
+
+      raise MatchError,
+            "File had #{actual_count} lines, not #{expected_count} lines as expected.\nEntire screen:\n#{self}"
+    end
+
+    private
+
+    def file_not_found_error(file_path)
+      raise MatchError,
+            "File with path #{file_path} was not found when asserted it did exist.\nEntire screen:\n#{self}"
+    end
+
+    def file_is_dir_error(file_path)
+      raise MatchError,
+            "File with path #{file_path} is a directory.\nEntire screen:\n#{self}"
+    end
+  end
+end

data/lib/ttytest/assertions/row_assertions.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # Row Assertions for ttytest2.
+  module RowAssertions
+    # 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 exactly
+    def assert_row(row_number, expected)
+      validate(row_number)
+      expected = expected.rstrip
+      actual = row(row_number)
+
+      return if !actual.nil? && actual == expected
+
+      raise MatchError,
+            "expected row #{row_number} to be #{expected.inspect} but got #{get_inspection(actual)}\n
+            Entire screen:\n#{self}"
+    end
+    alias assert_line assert_row
+
+    # Asserts the specified row is empty
+    # @param [Integer] row_number the row (starting from 0) to test against
+    # @raise [MatchError] if the row isn't empty
+    def assert_row_is_empty(row_number)
+      validate(row_number)
+      actual = row(row_number)
+
+      return if actual == ''
+
+      raise MatchError,
+            "expected row #{row_number} to be empty but got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    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
+    # @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)
+      validate(row_number)
+      expected = expected.rstrip
+      actual = row(row_number)
+      column_end += 1
+
+      return if !actual.nil? && actual[column_start, column_end].eql?(expected)
+
+      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}"
+    end
+    alias assert_line_at assert_row_at
+
+    # 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
+    def assert_row_like(row_number, expected)
+      validate(row_number)
+      expected = expected.rstrip
+      actual = row(row_number)
+
+      return if !actual.nil? && actual.include?(expected)
+
+      raise MatchError,
+            "expected row #{row_number} to be like #{expected.inspect} but got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+    alias assert_row_contains assert_row_like
+    alias assert_line_contains assert_row_like
+    alias assert_line_like assert_row_like
+
+    # 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
+    def assert_row_starts_with(row_number, expected)
+      validate(row_number)
+      expected = expected.rstrip
+      actual = row(row_number)
+
+      return if !actual.nil? && actual.start_with?(expected)
+
+      raise MatchError,
+            "expected row #{row_number} to start with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+    alias assert_line_starts_with assert_row_starts_with
+
+    # Asserts the contents of a single row end 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
+    def assert_row_ends_with(row_number, expected)
+      validate(row_number)
+      expected = expected.rstrip
+      actual = row(row_number)
+
+      return if !actual.nil? && actual.end_with?(expected)
+
+      raise MatchError,
+            "expected row #{row_number} to end with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+    alias assert_line_ends_with assert_row_ends_with
+
+    # Asserts the contents of a single row match against the passed in regular expression
+    # @param [Integer] row_number the row (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 row doesn't match against the regular expression
+    def assert_row_regexp(row_number, regexp_str)
+      validate(row_number)
+      regexp = Regexp.new(regexp_str)
+      actual = row(row_number)
+
+      return if !actual.nil? && actual.match?(regexp)
+
+      raise MatchError,
+            "expected row #{row_number} to match regexp #{regexp_str} but it did not. Row value #{get_inspection(actual)}\nEntire screen:\n#{self}"
+    end
+    alias assert_line_regexp assert_row_regexp
+
+    # Asserts the contents of a multiple rows each match against the passed in regular expression
+    # @param [Integer] row_start the row (starting from 0) to test against
+    # @param [Integer] row_end the last row to test against
+    # @param [String] regexp_str the regular expression as a string that will be used to match with.
+    # @raise [MatchError] if the row doesn't match against the regular expression
+    def assert_rows_each_match_regexp(row_start, row_end, regexp_str)
+      validate(row_end)
+      regexp = Regexp.new(regexp_str)
+      row_end += 1 if row_end.zero?
+
+      rows.slice(row_start, row_end).each_with_index do |actual_row, index|
+        next if !actual_row.nil? && actual_row.match?(regexp)
+
+        raise MatchError,
+              "expected row #{index} to match regexp #{regexp_str} but it did not. Row value #{get_inspection(actual_row)}\nEntire screen:\n#{self}"
+      end
+    end
+    alias assert_lines_each_match_regexp assert_rows_each_match_regexp
+  end
+end

data/lib/ttytest/assertions/screen_assertions.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module TTYtest
+  # Screen Assertions for ttytest2.
+  module ScreenAssertions
+    # 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)
+      matched, diff = get_diff(expected, rows)
+
+      return if matched
+
+      raise MatchError,
+            "screen did not match expected content:\n--- expected\n+++ actual\n#{diff.join("\n")}"
+    end
+    alias assert_matches assert_contents
+    alias assert_screen assert_contents
+
+    # Asserts the contents of the terminal at specified rows
+    # @param [String] expected the expected contents of the terminal at specified rows. Trailing whitespace on each line is ignored
+    # @raise [MatchError] if the terminal doesn't match the expected content
+    def assert_contents_at(row_start, row_end, expected)
+      validate(row_end)
+      row_end += 1 if row_end.zero?
+
+      matched, diff = get_diff(expected, rows.slice(row_start, row_end))
+
+      return if matched
+
+      raise MatchError,
+            "screen did not match expected content:\n--- expected\n+++ actual\n#{diff.join("\n")}"
+    end
+    alias assert_matches_at assert_contents_at
+    alias assert_rows assert_contents_at
+
+    # Asserts the contents of the screen include the passed in string
+    # @param [String] expected the string value expected to be found in the screen contents
+    # @raise [MatchError] if the screen does not contain the expected value
+    def assert_contents_include(expected)
+      found = false
+      rows.each do |row|
+        found = true if row.include?(expected)
+      end
+      return if found
+
+      raise MatchError,
+            "Expected screen contents to include #{expected}, but it was not found.\nEntire screen:\n#{self}"
+    end
+    alias assert_screen_includes assert_contents_include
+
+    # Asserts the contents of the screen are empty
+    # @raise [MatchError] if the screen is not empty
+    def assert_contents_empty
+      return if rows.all? { |s| s.to_s.empty? }
+
+      raise MatchError,
+            "Expected screen to be empty, but found content.\nEntire screen:\n#{self}"
+    end
+    alias assert_screen_empty assert_contents_empty
+
+    # Asserts the contents of the screen as a single string match the passed in regular expression
+    # @param [String] regexp_str the regular expression as a string that will be used to match with
+    # @raise [MatchError] if the screen as a string doesn't match against the regular expression
+    def assert_contents_match_regexp(regexp_str)
+      regexp = Regexp.new(regexp_str)
+      screen = capture.to_s
+
+      return if !screen.nil? && screen.match?(regexp)
+
+      raise MatchError,
+            "Expected screen contents to match regexp #{regexp_str} but they did not\nEntire screen:\n#{self}"
+    end
+    alias assert_screen_matches_regexp assert_contents_match_regexp
+  end
+end

data/lib/ttytest/assertions.rb

@@ -1,316 +1,19 @@
 # frozen_string_literal: true
 
+require 'ttytest/assertions/file_assertions'
+require 'ttytest/assertions/row_assertions'
+require 'ttytest/assertions/column_assertions'
+require 'ttytest/assertions/screen_assertions'
+require 'ttytest/assertions/cursor_assertions'
+
 module TTYtest
   # Assertions for ttytest2.
   module Assertions
-    # 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 exactly
-    def assert_row(row_number, expected)
-      validate(row_number)
-      expected = expected.rstrip
-      actual = row(row_number)
-
-      return if !actual.nil? && actual == expected
-
-      raise MatchError,
-            "expected row #{row_number} to be #{expected.inspect} but got #{get_inspection(actual)}\n
-            Entire screen:\n#{self}"
-    end
-    alias assert_line assert_row
-
-    # Asserts the specified row is empty
-    # @param [Integer] row_number the row (starting from 0) to test against
-    # @raise [MatchError] if the row isn't empty
-    def assert_row_is_empty(row_number)
-      validate(row_number)
-      actual = row(row_number)
-
-      return if actual == ''
-
-      raise MatchError,
-            "expected row #{row_number} to be empty but got #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    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
-    # @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)
-      validate(row_number)
-      expected = expected.rstrip
-      actual = row(row_number)
-      column_end += 1
-
-      return if !actual.nil? && actual[column_start, column_end].eql?(expected)
-
-      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}"
-    end
-    alias assert_line_at assert_row_at
-
-    # 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
-    def assert_row_like(row_number, expected)
-      validate(row_number)
-      expected = expected.rstrip
-      actual = row(row_number)
-
-      return if !actual.nil? && actual.include?(expected)
-
-      raise MatchError,
-            "expected row #{row_number} to be like #{expected.inspect} but got #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    end
-    alias assert_row_contains assert_row_like
-    alias assert_line_contains assert_row_like
-    alias assert_line_like assert_row_like
-
-    # 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
-    def assert_row_starts_with(row_number, expected)
-      validate(row_number)
-      expected = expected.rstrip
-      actual = row(row_number)
-
-      return if !actual.nil? && actual.start_with?(expected)
-
-      raise MatchError,
-            "expected row #{row_number} to start with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    end
-    alias assert_line_starts_with assert_row_starts_with
-
-    # Asserts the contents of a single row end 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
-    def assert_row_ends_with(row_number, expected)
-      validate(row_number)
-      expected = expected.rstrip
-      actual = row(row_number)
-
-      return if !actual.nil? && actual.end_with?(expected)
-
-      raise MatchError,
-            "expected row #{row_number} to end with #{expected.inspect} and got #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    end
-    alias assert_line_ends_with assert_row_ends_with
-
-    # Asserts the contents of a single row match against the passed in regular expression
-    # @param [Integer] row_number the row (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 row doesn't match against the regular expression
-    def assert_row_regexp(row_number, regexp_str)
-      validate(row_number)
-      regexp = Regexp.new(regexp_str)
-      actual = row(row_number)
-
-      return if !actual.nil? && actual.match?(regexp)
-
-      raise MatchError,
-            "expected row #{row_number} to match regexp #{regexp_str} but it did not. Row value #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    end
-    alias assert_line_regexp assert_row_regexp
-
-    # Asserts the contents of a multiple rows each match against the passed in regular expression
-    # @param [Integer] row_start the row (starting from 0) to test against
-    # @param [Integer] row_end the last row to test against
-    # @param [String] regexp_str the regular expression as a string that will be used to match with.
-    # @raise [MatchError] if the row doesn't match against the regular expression
-    def assert_rows_each_match_regexp(row_start, row_end, regexp_str)
-      validate(row_end)
-      regexp = Regexp.new(regexp_str)
-      row_end += 1 if row_end.zero?
-
-      rows.slice(row_start, row_end).each_with_index do |actual_row, index|
-        next if !actual_row.nil? && actual_row.match?(regexp)
-
-        raise MatchError,
-              "expected row #{index} to match regexp #{regexp_str} but it did not. Row value #{get_inspection(actual_row)}\nEntire screen:\n#{self}"
-      end
-    end
-    alias assert_lines_each_match_regexp assert_rows_each_match_regexp
-
-    # 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]
-
-      return if actual == expected
-
-      raise MatchError,
-            "expected cursor to be at #{expected.inspect} but was at #{get_inspection(actual)}\nEntire screen:\n#{self}"
-    end
-
-    # Asserts the cursor is currently visible
-    # @raise [MatchError] if the cursor is hidden
-    def assert_cursor_visible
-      return if cursor_visible?
-
-      raise MatchError, "expected cursor to be visible was hidden\nEntire screen:\n#{self}"
-    end
-
-    # Asserts the cursor is currently hidden
-    # @raise [MatchError] if the cursor is visible
-    def assert_cursor_hidden
-      return if cursor_hidden?
-
-      raise MatchError, "expected cursor to be hidden was visible\nEntire screen:\n#{self}"
-    end
-
-    # 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)
-      matched, diff = get_diff(expected, rows)
-
-      return if matched
-
-      raise MatchError,
-            "screen did not match expected content:\n--- expected\n+++ actual\n#{diff.join("\n")}"
-    end
-    alias assert_matches assert_contents
-    alias assert_screen assert_contents
-
-    # Asserts the contents of the terminal at specified rows
-    # @param [String] expected the expected contents of the terminal at specified rows. Trailing whitespace on each line is ignored
-    # @raise [MatchError] if the terminal doesn't match the expected content
-    def assert_contents_at(row_start, row_end, expected)
-      validate(row_end)
-      row_end += 1 if row_end.zero?
-
-      matched, diff = get_diff(expected, rows.slice(row_start, row_end))
-
-      return if matched
-
-      raise MatchError,
-            "screen did not match expected content:\n--- expected\n+++ actual\n#{diff.join("\n")}"
-    end
-    alias assert_matches_at assert_contents_at
-    alias assert_rows assert_contents_at
-
-    # Asserts the contents of the screen include the passed in string
-    # @param [String] expected the string value expected to be found in the screen contents
-    # @raise [MatchError] if the screen does not contain the expected value
-    def assert_contents_include(expected)
-      found = false
-      rows.each do |row|
-        found = true if row.include?(expected)
-      end
-      return if found
-
-      raise MatchError,
-            "Expected screen contents to include #{expected}, but it was not found.\nEntire screen:\n#{self}"
-    end
-    alias assert_screen_includes assert_contents_include
-
-    # Asserts the contents of the screen are empty
-    # @raise [MatchError] if the screen is not empty
-    def assert_contents_empty
-      return if rows.all? { |s| s.to_s.empty? }
-
-      raise MatchError,
-            "Expected screen to be empty, but found content.\nEntire screen:\n#{self}"
-    end
-    alias assert_screen_empty assert_contents_empty
-
-    # Asserts the contents of the screen as a single string match the passed in regular expression
-    # @param [String] regexp_str the regular expression as a string that will be used to match with
-    # @raise [MatchError] if the screen as a string doesn't match against the regular expression
-    def assert_contents_match_regexp(regexp_str)
-      regexp = Regexp.new(regexp_str)
-      screen = capture.to_s
-
-      return if !screen.nil? && screen.match?(regexp)
-
-      raise MatchError,
-            "Expected screen contents to match regexp #{regexp_str} but they did not\nEntire screen:\n#{self}"
-    end
-    alias assert_screen_matches_regexp assert_contents_match_regexp
-
-    # Asserts the specified file exists
-    # @param [String] file_path the path to the file
-    # @raise [MatchError] if the file is not found or is a directory/symlink
-    def assert_file_exists(file_path)
-      raise file_not_found_error(file_path) unless File.exist?(file_path)
-      raise file_is_dir_error(file_path) unless File.file?(file_path)
-    end
-
-    # Asserts the specified file does not exists
-    # @param [String] file_path the path to the file
-    # @raise [MatchError] if the file is found or is a directory/symlink
-    def assert_file_doesnt_exist(file_path)
-      return unless File.exist?(file_path) || File.file?(file_path)
-
-      raise MatchError,
-            "File with path #{file_path} was found or is a directory when it was asserted it did not exist.\nEntire screen:\n#{self}"
-    end
-
-    # Asserts the specified file contains the passed in string value
-    # @param [String] file_path the path to the file
-    # @param [String] needle the value to search for in the file
-    # @raise [MatchError] if the file does not contain value in variable needle
-    def assert_file_contains(file_path, needle)
-      raise file_not_found_error(file_path) unless File.exist?(file_path)
-      raise file_is_dir_error(file_path) unless File.file?(file_path)
-
-      file_contains = false
-      File.foreach(file_path) do |line|
-        if line.include?(needle)
-          file_contains = true
-          break
-        end
-      end
-      return if file_contains
-
-      raise MatchError,
-            "File with path #{file_path} did not contain #{needle}.\nEntire screen:\n#{self}"
-    end
-    alias assert_file_like assert_file_contains
-
-    # Asserts the specified file has the permissions specified
-    # @param [String] file_path the path to the file
-    # @param [String] permissions the expected permissions of the file (in form '644' or '775')
-    # @raise [MatchError] if the file has different permissions than specified
-    def assert_file_has_permissions(file_path, permissions)
-      raise file_not_found_error(file_path) unless File.exist?(file_path)
-      raise file_is_dir_error(file_path) unless File.file?(file_path)
-
-      file_mode = File.stat(file_path).mode
-      perms_octal = format('%o', file_mode)[-3...]
-      return if perms_octal == permissions
-
-      raise MatchError,
-            "File had permissions #{perms_octal}, not #{permissions} as expected.\n Entire screen:\n#{self}"
-    end
-
-    # 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
-    # @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)
-      raise file_is_dir_error(file_path) unless File.file?(file_path)
-
-      actual_count = File.foreach(file_path).count
-      return if actual_count == expected_count
-
-      raise MatchError,
-            "File had #{actual_count} lines, not #{expected_count} lines as expected.\nEntire screen:\n#{self}"
-    end
+    include TTYtest::FileAssertions
+    include TTYtest::RowAssertions
+    include TTYtest::ColumnAssertions
+    include TTYtest::ScreenAssertions
+    include TTYtest::CursorAssertions
 
     METHODS = public_instance_methods
 
@@ -358,15 +61,5 @@ module TTYtest
 
       [matched, diff]
     end
-
-    def file_not_found_error(file_path)
-      raise MatchError,
-            "File with path #{file_path} was not found when asserted it did exist.\nEntire screen:\n#{self}"
-    end
-
-    def file_is_dir_error(file_path)
-      raise MatchError,
-            "File with path #{file_path} is a directory.\nEntire screen:\n#{self}"
-    end
   end
 end

data/lib/ttytest/capture.rb

@@ -9,7 +9,7 @@ module TTYtest
   class Capture
     include TTYtest::Assertions
 
-    attr_reader :cursor_x, :cursor_y, :width, :height
+    attr_reader :cursor_x, :cursor_y, :width, :height, :max_wait_time, :use_return_for_newline
 
     # Used internally by drivers when called by {Terminal#capture}
     # @api private

data/lib/ttytest/constants.rb

@@ -16,7 +16,8 @@ module TTYtest
   SHIFT_ENTER = 11.chr # \v
   FORM_FEED = 12.chr # \f
   CTRLL = 12.chr
-  CARRIAGE_RETURN = 13.chr # \r
+  CARRIAGE_RETURN = 13.chr # \r, left for backwards compat
+  RETURN = 13.chr # \r, same as CARRIAGE_RETURN
   CTRLU = 21.chr
   CTRLW = 23.chr
   ESCAPE = 27.chr # ^[ or /033 or /e

data/lib/ttytest/terminal.rb

@@ -9,14 +9,15 @@ module TTYtest
   class Terminal
     extend Forwardable
 
-    attr_accessor :max_wait_time
+    attr_accessor :max_wait_time, :use_return_for_newline
 
     # @api private
     # @see TTYtest.new_terminal, use this or other new_* methods instead.
     # Internal constructor.
-    def initialize(driver_terminal)
+    def initialize(driver_terminal, max_wait_time, use_return_for_newline)
+      @max_wait_time = max_wait_time
+      @use_return_for_newline = use_return_for_newline
       @driver_terminal = driver_terminal
-      @max_wait_time = TTYtest.default_max_wait_time
     end
 
     # @!method send_keys(*keys)
@@ -67,17 +68,21 @@ module TTYtest
     #   @param [Integer] sleep_time the amount of time to sleep after sending the line
 
     # @!method send_newline
-    #   Simulate typing enter by sending newline character to the terminal.
+    #   Simulate typing enter by sending newline (ALT + enter) character to the terminal.
+    #   Many line readers interpreter newline as return, but in some cases you may have to use send_return.
 
     # @!method send_newlines(number_of_times)
-    #   Simulates sending newline the specified number of times.
+    #   Simulates sending newline (ALT + enter) the specified number of times.
+    #   Many line readers interpreter newline as return, but in some cases you may have to use send_return.
     #   @param [Integer] number_of_times number of times to send newline
 
-    # @!method send_enter
+    # @!method send_return
     #   Simulate typing enter by sending newline character to the terminal.
+    #   Many line readers interpreter newline as return, but in some cases you may have to use send_return.
 
-    # @!method send_enters(number_of_times)
+    # @!method send_returns(number_of_times)
     #   Simulates sending newline the specified number of times.
+    #   Many line readers interpreter newline as return, but in some cases you may have to use send_return.
     #   @param [Integer] number of times to send newline
 
     # @!method send_delete
@@ -142,6 +147,13 @@ module TTYtest
     #   Simulates typing in the Escape (ESC) key in the terminal the specified number of times.
     #   @param [Integer] number of times to send escape
 
+    # @!method send_tab
+    #   Simulates typing in the Tab (\t) key in the terminal.
+
+    # @!method send_tabs(number_of_times)
+    #   Simulates typing in the Tab (\t) key in the terminal the specified number of times.
+    #   @param [Integer] number of times to send tab
+
     # @!method capture
     #   Capture represents the current state of the terminal.
     #   @return [Capture] The current state of the terminal when called
@@ -152,11 +164,13 @@ module TTYtest
                    :send_line_exact, :send_lines_exact,
                    :send_newline, :send_newlines,
                    :send_enter, :send_enters,
+                   :send_return, :send_returns,
                    :send_delete, :send_deletes,
                    :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_home, :send_end, :send_clear, :send_escape, :send_escapes,
+                   :send_tab, :send_tabs,
                    :capture
 
     # @!method print

data/lib/ttytest/tmux/driver.rb

@@ -31,21 +31,22 @@ module TTYtest
         @config_file_path = config_file_path
       end
 
-      def new_terminal(cmd, width: 80, height: 24)
+      def new_terminal(cmd, width: 80, height: 24, max_wait_time: 2, use_return_for_newline: false)
         cmd = "#{cmd}\n#{SLEEP_INFINITY}"
 
         session_name = "ttytest-#{SecureRandom.uuid}"
         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)
+        session = Session.new(self, session_name, use_return_for_newline)
+        Terminal.new(session, max_wait_time, use_return_for_newline)
       end
 
       def new_default_sh_terminal
-        new_terminal(%(PS1='$ ' /bin/sh), width: 80, height: 24)
+        new_terminal(%(PS1='$ ' /bin/sh), width: 80, height: 24, max_wait_time: 2, use_return_for_newline: false)
       end
 
-      def new_sh_terminal(width: 80, height: 24)
-        new_terminal(%(PS1='$ ' /bin/sh), width: width, height: height)
+      def new_sh_terminal(width: 80, height: 24, max_wait_time: 2, use_return_for_newline: false)
+        new_terminal(%(PS1='$ ' /bin/sh), width: width, height: height, max_wait_time: max_wait_time,
+                                          use_return_for_newline: use_return_for_newline)
       end
 
       # @api private

data/lib/ttytest/tmux/session.rb

@@ -5,10 +5,11 @@ module TTYtest
     # represents a tmux session and how to send output to the current tmux session
     class Session
       # @api private
-      def initialize(driver, name)
+      def initialize(driver, name, use_return_for_newline)
         @id = SecureRandom.uuid
         @driver = driver
         @name = name
+        @use_return_for_newline = use_return_for_newline
 
         ObjectSpace.define_finalizer(@id, proc {
           begin
@@ -58,6 +59,10 @@ module TTYtest
       # Send line to tmux, no need to worry about newline character
       def send_line(line)
         send_keys_one_at_a_time(line)
+        if @use_return_for_newline
+          send_return unless ['\n', '\r'].include?(line[-1])
+          return
+        end
         send_newline unless line[-1] == '\n'
       end
 
@@ -75,6 +80,10 @@ module TTYtest
 
       def send_line_exact(line)
         send_keys_exact(line)
+        if @use_return_for_newline
+          send_return unless ['\n', '\r'].include?(line[-1])
+          return
+        end
         send_newline unless line[-1] == '\n'
       end
 
@@ -100,7 +109,6 @@ module TTYtest
       def send_newline
         driver.tmux(*%W[send-keys -t #{name} -l], %(\n))
       end
-      alias send_enter send_newline
 
       def send_newlines(number_of_times)
         while number_of_times.positive?
@@ -108,7 +116,17 @@ module TTYtest
           number_of_times -= 1
         end
       end
-      alias send_enters send_newlines
+
+      def send_return
+        driver.tmux(*%W[send-keys -t #{name} -l], %(\r))
+      end
+
+      def send_returns(number_of_times)
+        while number_of_times.positive?
+          send_return
+          number_of_times -= 1
+        end
+      end
 
       def send_delete
         send_keys_exact(%(DC))
@@ -194,6 +212,10 @@ module TTYtest
 
       def send_clear
         send_keys_one_at_a_time(TTYtest::CLEAR)
+        if @use_return_for_newline
+          send_return
+          return
+        end
         send_newline
       end
 
@@ -208,6 +230,17 @@ module TTYtest
         end
       end
 
+      def send_tab
+        send_keys_exact(TTYtest::TAB)
+      end
+
+      def send_tabs(number_of_times)
+        while number_of_times.positive?
+          send_tab
+          number_of_times -= 1
+        end
+      end
+
       private
 
       attr_reader :driver, :name

data/lib/ttytest/version.rb

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

data/lib/ttytest.rb

@@ -16,30 +16,38 @@ module TTYtest
     #   @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
+    #   @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 terminal running the specified command
 
     # @!method new_default_sh_terminal
     #   Create a new terminal using '/bin/sh' with width: 80 and height: 24.
     #   Useful for Unixes.
+    #   @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.
+    #   @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
+
     def_delegators :driver
 
-    def new_terminal(cmd, width: 80, height: 24, max_wait_time: 2)
-      @max_wait_time = max_wait_time
-      driver.new_terminal(cmd, width: width, height: height)
+    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
 
-    def new_default_sh_terminal(max_wait_time: 2)
-      @max_wait_time = max_wait_time
+    def new_default_sh_terminal
       driver.new_default_sh_terminal
     end
 
-    def new_sh_terminal(width: 80, height: 24, max_wait_time: 2)
-      @max_wait_time = max_wait_time
-      driver.new_sh_terminal(width: width, height: height)
+    def new_sh_terminal(width: 80, height: 24, max_wait_time: 2, use_return_for_newline: false)
+      driver.new_sh_terminal(width: width, height: height, max_wait_time: max_wait_time,
+                             use_return_for_newline: use_return_for_newline)
     end
   end
 

data/notes.txt

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ttytest2
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Alex Eski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-06 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,8 +95,14 @@ files:
 - README.md
 - Rakefile
 - examples/integration_tests.rb
+- images/ttytest2.png
 - lib/ttytest.rb
 - lib/ttytest/assertions.rb
+- lib/ttytest/assertions/column_assertions.rb
+- lib/ttytest/assertions/cursor_assertions.rb
+- lib/ttytest/assertions/file_assertions.rb
+- lib/ttytest/assertions/row_assertions.rb
+- lib/ttytest/assertions/screen_assertions.rb
 - lib/ttytest/capture.rb
 - lib/ttytest/constants.rb
 - lib/ttytest/terminal.rb