ttytest2 0.9.11 → 0.9.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ee6dc964334b3c1a099faf8a5f4701b8a594fc0e948f02ae11f233d612c55bd
-  data.tar.gz: e27455bec4bbb72e73b264ccf4261c3ff75a47a6ae52459cc7d302fcb789c3a5
+  metadata.gz: fd614376f0369112c875543a1d8cc498b0de69dd436e6158fd6d8f06bd4ee87f
+  data.tar.gz: 59373cd7e5699a8e6c96a3c0071efc4164d09ddfb71365291cf4a5d086b69bd1
 SHA512:
-  metadata.gz: 8d15dba3585a6a82a3d6f67749bc90ad58d750ecf6c30971ab3b99df8be56343f03488dba2161c3ee299a4cfc6b9c3362b013e7c6e6b7870cf663defbac90ece
-  data.tar.gz: 49d7505801519f03ecd0b6dc2c0dadf8ed0cb7b3c203ddac23b25f1739942e21206a0aed6603443aadfa38e1d8bd86a38c01b64165e6bf0d4900b8a00ad64bf7
+  metadata.gz: 77eb7d0d56818eaa11b3f0ac84230f5100a50bfc0ccf45c67c34a0389005b55317b5a85d23ed68f5b65c923fe8a51efe620304dcc345c7cd4cf902ff80b8e8d4
+  data.tar.gz: 2a3d270669408488cd1e636231b336cd62e3606d1cd20dfd267858ca3e0a544ded977ecc657df82f2833a2a2a77c9f8d422428b84715377314e6c7faf57b81e7

data/README.md

@@ -2,9 +2,9 @@
 
 ttytest2 is an acceptance test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
 
-A drop-in replacement for [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), because I had some features I needed for my own project.
 
-It works by running commands inside a tmux session, capturing the pane, and comparing the content.
+It works by running commands inside a tmux session, capturing the pane, and comparing the content to your assertions.
 
 The assertions will wait a specified amount of time (default 2 seconds) for the expected content to appear.
 
@@ -14,17 +14,16 @@ The assertions will wait a specified amount of time (default 2 seconds) for the
 
 1. [Minimum Requirements](#minimum-requirements)
 2. [Usage](#usage)
-3. [Example for Canonical CLI or Shell](#example-for-canonical-cli-or-shell)
-4. [Example for Noncanonical CLI or Shell](#example-for-noncanonical-cli-or-shell)
-5. [Assertions](#assertions)
-6. [Output](#output)
-7. [Output Helpers](#output-helpers)
-8. [Troubleshooting](#troubleshooting)
-9. [Constants](#constants)
-10. [Tips](#tips)
-11. [Docker](#docker)
-12. [Contributing](#contributing)
-13. [License](#license)
+3. [Simple Example](#simple-example)
+4. [Assertions](#assertions)
+5. [Output](#output)
+6. [Output Helpers](#output-helpers)
+7. [Troubleshooting](#troubleshooting)
+8. [Constants](#constants)
+9. [Tips](#tips)
+10. [Docker](#docker)
+11. [Contributing](#contributing)
+12. [License](#license)
 
 ## Minimum Requirements
 
@@ -33,29 +32,25 @@ The assertions will wait a specified amount of time (default 2 seconds) for the
 
 ## Usage
 
-More documentation available at [ttytest2 docs](https://www.rubydoc.info/gems/ttytest2).
+* More documentation available at [ttytest2 docs](https://www.rubydoc.info/gems/ttytest2).
+* There are more examples in the examples folder.
 
-There are more examples in the examples folder.
-
-### Example for Canonical CLI or Shell
-
-Most people should use send_keys, if you are writing or working with a noncanonical shell/CLI, you will probably know it! Most shell/CLI applications are canonical.
+### Simple Example
 
 ``` ruby
 require 'ttytest'
-
-@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/sh}, width: 80, height: 24)
+@tty = TTYtest.new_terminal(%(PS1='$ ' /bin/sh), width: 80, height: 7)
 @tty.assert_row(0, '$')
-@tty.assert_cursor_position(x: 2, y: 0)
+@tty.assert_cursor_position(2, 0)
 
-@tty.send_keys(%{echo "Hello, world"\n})
+@tty.send_line('echo "Hello, world"'))
 
-@tty.assert_contents <<TTY
-$ echo "Hello, world"
-Hello, world
-$
+@tty.assert_contents <<~TTY
+  $ echo "Hello, world"
+  Hello, world
+  $
 TTY
-@tty.assert_cursor_position(x: 2, y: 2)
+@tty.assert_cursor_position(2, 2)
 
 @tty.assert_contents_at(0, 0, '$ echo "Hello, world"')
 
@@ -64,44 +59,20 @@ TTY
 @tty.assert_row_starts_with(1, 'Hello')
 @tty.assert_row_ends_with(1, ', world')
 
-@tty.print_rows # => ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ...]
+@tty.print_rows # prints out the contents of the terminal as an array:
+# ["$ echo \"Hello, world\"", "Hello, world", "$", "", "", "", ""]
 
-@tty.print # prints out the contents of the terminal
-```
-
-### Example for Noncanonical CLI or Shell
-
-If you are working with a noncanonical shell, you need to use send_keys_one_at_a_time to have your shell/CLI process the input correctly.
-
-Also useful if you need to send input one character at a time for whatever reason.
-
-'Multi-character' characters like '\n' need to be sent with send-keys, though.
-
-``` ruby
-require 'ttytest'
-
-@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/noncanonical-sh}, width: 80, height: 24)
-@tty.assert_row_starts_with(0, ENV['USER'])
-@tty.assert_row_ends_with(0, '$')
-
-@tty.send_keys_one_at_a_time('ls')
-@tty.assert_row_ends_with(0, 'ls')
-@tty.send_newline # builtins for common outputs line newline
-
-@tty.send_keys_one_at_a_time('ps')
-@tty.assert_row_ends_with(1, 'ps')
-@tty.send_keys(TTYtest:NEWLINE) # can use constants instead
-
-@tty.assert_row_starts_with(2, ENV['USER'])
-@tty.assert_row_ends_with(2, '$')
-@tty.send_newline
-
-puts "\n#{@tty.capture}" # prints out the contents of the terminal, equivalent to @tty.print
+@tty.print # prints out the contents of the terminal:
+# $ echo "Hello, world"
+# Hello, world
+# $
 ```
 
 ### Assertions
 
-The main way to use TTYtest is through assertions. When called on a `TTYtest::Terminal`, each of these will be retried (for up to 2 seconds).
+The main way to use TTYtest is through assertions.
+
+Assertions will be retried for up to 2 seconds when called through TTYtest::Terminal.
 
 Available assertions:
 
@@ -110,6 +81,7 @@ Available assertions:
 * `assert_row_like(row_number, expected_text)`
 * `assert_row_starts_with(row_number, expected_text)`
 * `assert_row_ends_with(row_number, expected_text)`
+* `assert_row_regexp(row_number, regexp_str)`
 * `assert_cursor_position(x: x, y: y)`
 * `assert_cursor_visible`
 * `assert_cursor_hidden`
@@ -120,19 +92,35 @@ Available assertions:
 
 You can send output to the terminal with the following calls.
 
-* `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) # for sending tmux specific keys (DC for delete, Escape for ESC, etc.)`
+Note: Most of the time send_line has the best ergonomics.
+
+* `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.
+
+* `send_lines(lines)`: for each line in lines, simulate sending the line and hitting enter.
+
+* `send_lines_then_sleep(lines, sleep_time)`: for each line in lines, simulate sending the line and hitting enter. After sending all the lines, sleep for sleep_time.
+
+* `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_keys_exact(output)`: for sending tmux specific keys (any supported send-keys arguments like: DC for delete, Escape for ESC, etc.)
 
 ### Output Helpers
 
 Helper functions to make sending output easier! They use the methods above under 'Sending Output' section under the hood.
 
-* `send_newline` # equivalent to @tty.send_keys(%(\n))
+* `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_backspace` # equivalent to @tty.send_keys(TTYtest::BACKSPACE)
+* `send_enter` # alias for send_newline
+* `send_enters(number_of_times)` # alias for send_newlines
+* `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
-* `send_delete` # equivalent to calling send_keys_exact(%(DC))
+* `send_delete` # simulate hitting delete, equivalent to calling send_keys_exact(%(DC))
 * `send_deletes` # equivalent to calling send_delete number_of_times
 * `send_right_arrow`
 * `send_right_arrows(number_of_times)`
@@ -145,6 +133,8 @@ Helper functions to make sending output easier! They use the methods above under
 * `send_home` # simulate pressing the Home key
 * `send_end` # simulate pressing the End key
 * `send_clear` # clear the screen by sending clear ascii code
+* `send_escape`
+* `send_escapes`
 
 ### F keys?
 
@@ -180,15 +170,24 @@ You can configure max wait time as shown below.
 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('')
+@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.
-p @tty.rows # prints out the contents of the terminal as a array.
-@tty.print_rows # equivalent to above, just for ease of use.
+@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.
-p "\n#{@tty.capture}" # prints out the contents of the terminal
-@tty.print # equivalent to above, just for ease of use.
+@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
 ```
 
 ### Constants
@@ -196,6 +195,8 @@ p "\n#{@tty.capture}" # prints out the contents of the terminal
 There are some commonly used keys available as constants to make interacting with your shell/CLI easy.
 
 ``` ruby
+  TTYtest::CTRLA
+  TTYtest::CTRLB
   TTYtest::CTRLC
   TTYtest::CTRLD
   TTYtest::CTRLF
@@ -203,10 +204,16 @@ There are some commonly used keys available as constants to make interacting wit
   TTYtest::BACKSPACE
   TTYtest::TAB
   TTYtest::NEWLINE # \n
-  TTYtest::VERTICAL_TAB
+  TTYtest::ENTER # \n
+  TTYtest::VERTICAL_TAB # \v
+  TTYtest::SHIFT_ENTER # \v
   TTYtest::FORM_FEED # \f or New Page NP
+  TTYtest::CTRLL
   TTYtest::CARRIAGE_RETURN # \r
+  TTYtest::CTRLU
+  TTYtest::CTRLW
   TTYtest::ESCAPE # 27 decimal or ^[ or /033
+  TTYtest::CTRL_
   TTYtest::DELETE
 
   TTYtest::UP_ARROW
@@ -222,7 +229,7 @@ There are some commonly used keys available as constants to make interacting wit
 
 ### Tips
 
-If you are using ttyest2 to test your CLI, using sh is easier than bash because you don't have to worry about user, current working directory, etc. as shown in the examples above.
+If you are using 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.