ttytest2 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a0efe35a9376c501403b55279be2f4d1945cd11fa6daf56df854f1883d432df
-  data.tar.gz: 8663d5d7aad9d17067733670cec372fe6d9ea0c1e384956a4e899da9b0322054
+  metadata.gz: b1878cb00bec4cb2ad2213c6659212cbef7dfc0c1dab31e445e07b1fcbf088e7
+  data.tar.gz: 2298de4d8674e11cf0c23e520176ca3aa9a33ce1ec75e24e712be7a269b79840
 SHA512:
-  metadata.gz: 7962a743edd2522bfe4d5278f2ef014dde6f2b086d022ed9a9193101b30e4eea27dcbb986db43e24032e0beb51380b27724d3c50323b8f0df9c143e1f09d6110
-  data.tar.gz: 91d8b71eead9a642318f10ef2209cc3775d3fb82f14456e4976955fd868fe85e33a34e271f5e5d39fd80577be23a85fcc3279e9c8d831a3907513eabd8112b70
+  metadata.gz: 73d59c8dbfab01db1c6305b4f3ad6c8f6a44698c83cf969516a3accf33422005b18377d1a809d883834b8e0b11fdd729096460c90de7742417c65f9bd5c79303
+  data.tar.gz: '09c46d90a2776c1fb36d0b896b46c4b1d6b537382b41eb33784326cf99134bf68eac9f89e3dd910a16c3938d188ea1c3a66674e36b8387729f09d4a4b0216e24'

data/README.md

@@ -1,10 +1,10 @@
 # ttytest2
 
-ttytest2 is an acceptance test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
+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), because I had some features I needed for my own project.
+ttytest2 is a fork and a drop-in replacement for [ttytest](https://github.com/jhawthorn/ttytest).
 
-It works by running commands inside a tmux session, capturing the pane, and comparing the content to your assertions.
+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.
 
@@ -14,16 +14,15 @@ The assertions will wait a specified amount of time (configurable, default 2 sec
 
 1. [Minimum Requirements](#minimum-requirements)
 2. [Usage](#usage)
-3. [Simple Example](#simple-example)
+3. [Initializing](#initializing)
 4. [Assertions](#assertions)
 5. [Output](#output)
-6. [Output Helpers](#output-helpers)
+6. [Configurables](#configurables)
 7. [Troubleshooting](#troubleshooting)
-8. [Constants](#constants)
-9. [Tips](#tips)
-10. [Docker](#docker)
-11. [Contributing](#contributing)
-12. [License](#license)
+8. [Tips](#tips)
+9. [Docker](#docker)
+10. [Contributing](#contributing)
+11. [License](#license)
 
 ## Minimum Requirements
 
@@ -69,7 +68,7 @@ TTY
 # $
 ```
 
-### Initializing
+## Initializing
 
 Call one of these methods to initialize an instance of ttytest2.
 
@@ -94,13 +93,19 @@ require 'ttytest'
 @tty = TTYtest.new_terminal('/bin/bash', width: 80, height: 24)
 ```
 
-### Assertions
+## Assertions
 
-The main way to use TTYtest is through assertions.
+The main way to use ttytest2 is through assertions.
 
-Assertions will be retried for up to 2 seconds when called through TTYtest::Terminal.
+Assertions will be retried for up to 2 seconds when called through TTYtest::Terminal, unless you specify otherwise (see [Configurables](#configurables)).
 
-Available assertions:
+### Aliases
+
+Some assertions have aliases, like `assert_matches_at` has the alias `assert_rows`.
+
+If you are reading this on github, the ruby docs accessible from [RubyDoc.Info](https://www.rubydoc.info/gems/ttytest2/) document all of the aliases.
+
+### Available Assertions
 
 * `assert_row(row_number, expected_text)`
 
@@ -126,12 +131,28 @@ Available assertions:
 
 * `assert_contents_at(row_start, row_end, expected_text)`
 
-### Output
+## Output
 
 You can send output to the terminal with the following calls.
 
 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.
+
+* `send_keys(output)`: for canonical shells/CLI's (or multi-character keys for noncanonical shells/CLI's).
+
+* `send_keys_one_at_a_time(output)`: for noncanonical shells/CLI's.
+
+* `send_keys_exact(output)`: 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.)
+
+### 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.
+
+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.
+
 * `send_line(line)`: simulate typing in a command in the terminal and hitting enter!
 
 * `send_line_then_sleep(line, sleep_time)`: simulate typing in a command in the terminal and hitting enter, then wait for sleep_time seconds.
@@ -142,11 +163,9 @@ Note: Most of the time send_line has the best ergonomics.
 
 * `send_line_then_sleep_and_repeat(lines, sleep_time)`: for each line in lines, simulate sending the line and hitting enter, then sleep before sending the next line.
 
-* `send_keys(output)`: for canonical shells/CLI's (or multi-character keys for noncanonical shells/CLI's).
-
-* `send_keys_one_at_a_time(output)`: for noncanonical shells/CLI's.
+* `send_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_keys_exact(output)`: for sending tmux specific keys (any supported send-keys arguments like: DC for delete, Escape for ESC, etc.)
+* `send_lines_exact`: send lines exactly are they are to tmux. Similar semantics to send_line_exact.
 
 ### Output Helpers
 
@@ -161,7 +180,7 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_backspaces(number_of_times)` # equivalent to calling send_backspace number_of_times
 
 * `send_delete` # simulate hitting delete, equivalent to calling send_keys_exact(%(DC))
-* `send_deletes` # equivalent to calling send_delete number_of_times
+* `send_deletes(number_of_times)` # equivalent to calling send_delete number_of_times
 
 * `send_right_arrow`
 * `send_right_arrows(number_of_times)`
@@ -181,7 +200,7 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_clear` # clear the screen by sending clear ascii code
 
 * `send_escape`
-* `send_escapes`
+* `send_escapes(number_of_times)`
 
 ### F keys?
 
@@ -193,48 +212,8 @@ Send F keys like F1, F2, etc. as shown below:
 @tty.send_keys_exact(%(F1))
 @tty.send_keys_exact(%(F2))
 # ...
-@tty.send_keys_exact(%(F11))
-@tty.send_keys_exact(%(F12))
-```
-
-### Configurables
-
-Currently the only configuration for ttytest2 is max wait time.
-
-Max wait time represents the amount of time in seconds that ttytest2 will keep retrying an assertion before failing.
-
-You can configure max wait time as shown below.
-
-``` ruby
-@tty = TTYtest::new_terminal('')
-@tty.max_wait_time = 1 # sets the max wait time to 1 second
-
-@tty.assert_row(0, 'echo Hello, world') # this assertion would fail after 1 second
-```
-
-### 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
-@tty = TTYtest.new_terminal(%(PS1='$ ' /bin/sh), width: 80, height: 7)
-@tty.send_line('echo "Hello, world"'))
-
-# you can use @tty.rows to access the entire pane, split by line into an array.
-@tty.print_rows # prints out the contents of the terminal as an array:
-# ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ""]
-
-# if you want to programatically access the rows, you can do so using @tty.rows
-p @tty.rows # is equivalent to above statement @tty.print_rows
-
-# you can use @tty.capture to access the entire pane.
-@tty.print # prints out the contents of the terminal:
-# $ echo "Hello, world"
-# Hello, world
-# $
-
-# if you want to programatically access the entire pane, you can do so using @tty.capture
-p "\n#{@tty.capture}" # is equivalent to above statement @tty.print
+@tty.send_keys_exact('F11')
+@tty.send_keys_exact('F12')
 ```
 
 ### Constants
@@ -274,11 +253,53 @@ There are some commonly used keys available as constants to make interacting wit
   TTYtest::CLEAR # clear the screen
 ```
 
+## Configurables
+
+Currently the only configuration for ttytest2 is max wait time.
+
+Max wait time represents the amount of time in seconds that ttytest2 will keep retrying an assertion before failing.
+
+You can configure max wait time as shown below.
+
+``` ruby
+@tty = TTYtest::new_terminal('')
+@tty.max_wait_time = 1 # sets the max wait time to 1 second
+
+@tty.assert_row(0, 'echo Hello, world') # this assertion would fail after 1 second
+```
+
+## 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
+@tty = TTYtest.new_terminal(%(PS1='$ ' /bin/sh), width: 80, height: 7)
+@tty.send_line('echo "Hello, world"'))
+
+# If you want to print the current terminal rows as an array of lines, you can use @tty.print_rows.
+@tty.print_rows # prints out the contents of the terminal as an array:
+# ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ""]
+
+# you can use @tty.rows to access the entire pane, split by line into an array.
+# if you want to programatically access the rows, you can do so using @tty.rows.
+p @tty.rows # this is equivalent to above statement @tty.print_rows.
+
+# If you want to print the current terminal contents, you can use @tty.print.
+@tty.print # prints out the contents of the terminal:
+# $ echo "Hello, world"
+# Hello, world
+# $
+
+# you can use @tty.capture to access the entire pane.
+# if you want to programatically access the entire pane, you can do so using @tty.capture.
+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 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.
+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
 

data/lib/ttytest/capture.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module TTYtest
-  # Represents the complete state of a {TTYtest::Terminal} at the time it was captured (contents, cursor position, etc).
-  # @attr_reader [Integer] width the number of columns in the captured terminal
-  # @attr_reader [Integer] height the number of rows in the captured terminal
-  # @attr_reader [Integer] cursor_x the cursor's column (starting at 0) in the captured terminal
-  # @attr_reader [Integer] cursor_y the cursor's row (starting at 0) in the captured terminal
+  # Represents the complete state of a {TTYtest::Terminal} at the time it was captured, including contents, cursor position, etc.
+  # @attr_reader [Integer] width The number of columns in the captured terminal.
+  # @attr_reader [Integer] height The number of rows in the captured terminal.
+  # @attr_reader [Integer] cursor_x The cursor's column (starting at 0) in the captured terminal.
+  # @attr_reader [Integer] cursor_y The cursor's row (starting at 0) in the captured terminal.
   class Capture
     include TTYtest::Matchers
 
@@ -24,39 +24,41 @@ module TTYtest
       @cursor_visible = cursor_visible
     end
 
-    # @return [Array<String>] An array of each row's contend from the captured terminal
+    # @return [Array<String>] An array of each row's contents from the captured terminal.
     attr_reader :rows
 
-    # @param [Integer] the row to return
-    # @return [String] the content of the row from the captured terminal
+    # @param [Integer] The row to return
+    # @return [String] The content of the row from the captured terminal.
     def row(row_number)
       rows[row_number]
     end
 
-    # @return [true,false] Whether the cursor is visible in the captured terminal
+    # @return [true,false] Whether the cursor is visible in the captured terminal.
     def cursor_visible?
       @cursor_visible
     end
 
-    # @return [true,false] Whether the cursor is hidden in the captured terminal
+    # @return [true,false] Whether the cursor is hidden in the captured terminal.
     def cursor_hidden?
       !cursor_visible?
     end
 
-    # @return [Capture] returns self
+    # @return [Capture] Returns self
     def capture
       self
     end
 
+    # Prints out the current terminal contents.
     def print
       puts "\n#{self}"
     end
 
+    # Prints out the current terminal contents as an array of strings separated by lines.
     def print_rows
       p rows
     end
 
-    # @return [String] All rows of the captured terminal, separated by newlines
+    # @return [String] All rows of the captured terminal, separated by newlines.
     def to_s
       rows.join("\n")
     end

data/lib/ttytest/terminal.rb

@@ -5,14 +5,15 @@ require 'ttytest/matchers'
 require 'ttytest/capture'
 
 module TTYtest
-  # @attr [Integer] max_wait_time the maximum amount of time (in seconds) to retry assertions before failing.
+  # @attr [Integer] max_wait_time The maximum amount of time (in seconds) to retry an assertion before failing and raising a MatchError.
   class Terminal
     extend Forwardable
 
     attr_accessor :max_wait_time
 
     # @api private
-    # @see TTYtest.new_terminal
+    # @see TTYtest.new_terminal, use this or other new_* methods instead.
+    # Internal constructor.
     def initialize(driver_terminal)
       @driver_terminal = driver_terminal
       @max_wait_time = TTYtest.default_max_wait_time
@@ -29,6 +30,7 @@ module TTYtest
     # @!method send_line(line)
     #   Simulate sending a line to the terminal and hitting enter.
     #   Can send multiline input, but if you want to send several commands at once, see send_lines(lines)
+    #   If no newline is at the the line, it will be appended automatically.
     #   @param [String] line the line to send to the terminal
 
     # @!method send_line_then_sleep(line, sleep_time)
@@ -38,6 +40,18 @@ module TTYtest
 
     # @!method send_lines(lines)
     #   Simulate sending a multiple lines to the terminal and hitting enter after each line.
+    #   If no newline is at the end of any of the lines, it will be appended automatically.
+    #   @param [String] lines array of lines to send to the terminal
+
+    # @!method send_line_exact(line)
+    #   Simulate sending a line exactly as is to the terminal and hitting enter.
+    #   Can send multiline input, but if you want to send several commands at once, see send_lines(lines)
+    #   If no newline is at the the line, it will be appended automatically.
+    #   @param [String] line the line to send to the terminal
+
+    # @!method send_lines_exact(lines)
+    #   Simulate sending a multiple lines exactly as is to the terminal and hitting enter after each line.
+    #   If no newline is at the end of any of the lines, it will be appended automatically.
     #   @param [String] lines array of lines to send to the terminal
 
     # @!method send_lines_then_sleep(lines, sleep_time)
@@ -129,12 +143,13 @@ module TTYtest
     #   @param [Integer] number of times to send escape
 
     # @!method capture
-    #   Capture the current state of the terminal
-    #   @return [Capture] instantaneous state of the terminal when called
+    #   Capture represents the current state of the terminal.
+    #   @return [Capture] The current state of the terminal when called
     def_delegators :@driver_terminal,
                    :send_keys, :send_keys_one_at_a_time,
                    :send_line, :send_line_then_sleep,
                    :send_lines, :send_lines_then_sleep, :send_line_then_sleep_and_repeat,
+                   :send_line_exact, :send_lines_exact,
                    :send_newline, :send_newlines,
                    :send_enter, :send_enters,
                    :send_delete, :send_deletes,

data/lib/ttytest/tmux/session.rb

@@ -73,6 +73,17 @@ module TTYtest
         end
       end
 
+      def send_line_exact(line)
+        send_keys_exact(line)
+        send_newline unless line[-1] == '\n'
+      end
+
+      def send_lines_exact(*lines)
+        lines.each do |line|
+          send_line_exact(line)
+        end
+      end
+
       def send_lines_then_sleep(*lines, sleep_time)
         lines.each do |line|
           send_line(line)

data/lib/ttytest/version.rb

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

data/lib/ttytest.rb

@@ -28,6 +28,7 @@ module TTYtest
     def_delegators :driver, :new_terminal, :new_default_sh_terminal, :new_sh_terminal
   end
 
+  # The error type raised when an assertion fails.
   class MatchError < StandardError; end
 
   self.driver = TTYtest::Tmux::Driver.new

data/notes.txt

@@ -1,7 +1,7 @@
 to push new version to github
-git tag v1.0.3
+git tag v1.0.4
 git push origin --tags
 
 to push new version to rubygems.org
 gem build ttytest2.gemspec
-gem push ttytest2-1.0.3.gem
+gem push ttytest2-1.0.4.gem

metadata

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