ttytest2 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c87da11ef189a8f5c57cb248f6b141d00d43a64d27f62a2b5d00fb40974c765
+  data.tar.gz: 4dbc8af44a477b2c755c9653eb9411946447a295c1186f6f12a709b84dec3ee9
+SHA512:
+  metadata.gz: 15737416cb6956c0dc04c07d77ba8970f06a38da74321bb888bb3565d60ef04e28b8b1bf1bf7304af3452a3c480ff32998ffcf339f00848782c5251ad0c3b606
+  data.tar.gz: c969a721dc64fec69889482759664b3c7fdba5585292663b470a8903b39336f2e12b6da353f3c40b6080d1c4f1b59e7e35b0c8deb046097dfe59ef5ce1179bc4

data/.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: Test
+
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby 3.2.3
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.2.3
+        bundler-cache: true
+    - name: Build and test with Rake
+      run: |
+        bundle install --jobs 4 --retry 3
+        bundle exec rake

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+pkg/
+.yardoc/
+doc/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,79 @@
+# ttytest2
+
+TTYtest2 is an acceptance test framework for interactive console applications. It's like [capybara](https://github.com/teamcapybara/capybara) for the terminal.
+
+Forked from 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. The assertions will wait a specified amount of time (default 2 seconds) for the expected content to appear.
+
+[![Gem Version](https://badge.fury.io/rb/ttytest.svg)](https://rubygems.org/gems/ttytest)
+
+## Minimum Requirements
+
+* tmux >= 1.8
+* Ruby >= 3.2.3
+
+## Usage
+
+### Example
+
+``` ruby
+@tty = TTYtest.new_terminal(%{PS1='$ ' /bin/sh}, width: 80, height: 24)
+@tty.assert_row(0, '$')
+@tty.assert_cursor_position(x: 2, y: 0)
+
+@tty.send_keys(%{echo "Hello, world"\n})
+
+@tty.assert_contents <<TTY
+$ echo "Hello, world"
+Hello, world
+$
+TTY
+@tty.assert_cursor_position(x: 2, y: 2)
+
+p @tty.rows # => ["$ 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 by default).
+
+Available assertions:
+* `assert_row(row_number, expected_text)`
+* `assert_row_like(row_number, expected_text)`
+* `assert_cursor_position(x: x, y: y)`
+* `assert_cursor_visible`
+* `assert_cursor_hidden`
+* `assert_contents(lines_of_terminal)`
+
+## Docker
+
+Easy to use from Docker. Add this to your dockerfile to get started.
+
+``` dockerfile
+RUN apt update && \
+  apt install gcc make ruby tmux -y && \
+  gem install ttytest2
+```
+
+## TravisCI
+
+TTYtest can run on [TravisCI](https://travis-ci.org/), but the version of tmux made available with their default ubuntu 12.04 environment is too old. However the TravisCI ubuntu 14.04 "trusty" image provides tmux 1.8, which works great.
+
+Ensure the following is in your `.travis.yml` (see [this project's .travis.yml](./.travis.yml) for an example)
+
+``` yaml
+dist: trusty
+addons:
+  apt:
+    packages:
+    - tmux
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/a-eski/ttytest2.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'yard'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end
+
+task :console do
+  system 'irb -Ilib -rttytest'
+end
+
+task default: :test

data/lib/ttytest/capture.rb

@@ -0,0 +1,54 @@
+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
+  class Capture
+    include TTYtest::Matchers
+
+    attr_reader :cursor_x, :cursor_y, :width, :height
+
+    # Used internally by drivers when called by {Terminal#capture}
+    # @api private
+    def initialize(contents, cursor_x: 0, cursor_y: 0, width: nil, height: nil, cursor_visible: true)
+      @rows = "#{contents}\nEND".split("\n")[0...-1].map do |row|
+        row || ''
+      end
+      @cursor_x = cursor_x
+      @cursor_y = cursor_y
+      @width = width
+      @height = height
+      @cursor_visible = cursor_visible
+    end
+
+    # @return [Array<String>] An array of each row's contend from the captured terminal
+    attr_reader :rows
+
+    # @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
+    def cursor_visible?
+      @cursor_visible
+    end
+
+    # @return [true,false] Whether the cursor is hidden in the captured terminal
+    def cursor_hidden?
+      !cursor_visible?
+    end
+
+    # @return [Capture] returns self
+    def capture
+      self
+    end
+
+    # @return [String] All rows of the captured terminal, separated by newlines
+    def to_s
+      rows.join("\n")
+    end
+  end
+end

data/lib/ttytest/matchers.rb

@@ -0,0 +1,84 @@
+module TTYtest
+  module Matchers
+    # Asserts the contents of a single row
+    # @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
+    def assert_row(row_number, expected)
+      expected = expected.rstrip
+      actual = row(row_number)
+      return unless actual != expected
+
+      raise MatchError,
+            "expected row #{row_number} to be #{expected.inspect} but got #{actual.inspect}\nEntire screen:\n#{self}"
+    end
+
+    # Asserts the contents of a single row
+    # @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
+    def assert_row_like(row_number, expected)
+      raise MatchError, "expected a value for 'expected' but recieved nil" if actual.nil?
+
+      expected = expected.rstrip
+      actual = row(row_number)
+      return if actual.include?(expected)
+
+      raise MatchError,
+            "expected row #{row_number} to be like #{expected.inspect} but got #{actual.inspect}\nEntire screen:\n#{self}"
+    end
+
+    # 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 unless actual != expected
+
+      raise MatchError,
+            "expected cursor to be at #{expected.inspect} but was at #{actual.inspect}\nEntire screen:\n#{self}"
+    end
+
+    # @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
+
+    # @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)
+      expected_rows = expected.split("\n")
+      diff = []
+      matched = true
+      rows.each_with_index do |actual_row, index|
+        expected_row = (expected_rows[index] || '').rstrip
+        if actual_row != expected_row
+          diff << "-#{expected_row}"
+          diff << "+#{actual_row}"
+          matched = false
+        else
+          diff << " #{actual_row}".rstrip
+        end
+      end
+
+      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
+
+    METHODS = public_instance_methods
+  end
+end

data/lib/ttytest/terminal.rb

@@ -0,0 +1,75 @@
+require 'forwardable'
+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.
+  class Terminal
+    extend Forwardable
+
+    attr_accessor :max_wait_time
+
+    # @api private
+    # @see TTYtest.new_terminal
+    def initialize(driver_terminal, max_wait_time: nil)
+      @driver_terminal = driver_terminal
+      @max_wait_time = max_wait_time || TTYtest.default_max_wait_time
+    end
+
+    # @!method send_keys(*keys)
+    #   Simulate typing keys into the terminal
+    #   @param [String] keys keys to send to the terminal
+    # @!method capture
+    #   Capture the current state of the terminal
+    #   @return [Capture] instantaneous state of the terminal when called
+    def_delegators :@driver_terminal, :send_keys, :capture
+
+    # @!method rows
+    #   @return [Array<String>]
+    #   @see Capture#rows
+    # @!method row(row)
+    #   @return [String]
+    #   @see Capture#row
+    # @!method width
+    #   @see Capture#width
+    #   @return [Integer]
+    # @!method height
+    #   @see Capture#height
+    #   @return [Integer]
+    # @!method cursor_x
+    #   @see Capture#cursor_x
+    #   @return [Integer]
+    # @!method cursor_y
+    #   @see Capture#cursor_y
+    #   @return [Integer]
+    # @!method cursor_visible?
+    #   @see Capture#cursor_visible?
+    #   @return [true,false]
+    # @!method cursor_hidden?
+    #   @see Capture#cursor_hidden?
+    #   @return [true,false]
+    def_delegators :capture, :rows, :row, :width, :height, :cursor_x, :cursor_y, :cursor_visible?, :cursor_hidden?
+
+    TTYtest::Matchers::METHODS.each do |matcher_name|
+      define_method matcher_name do |*args|
+        synchronize do
+          capture.public_send(matcher_name, *args)
+        end
+      end
+    end
+
+    private
+
+    def synchronize(seconds = max_wait_time)
+      start_time = Time.now
+      begin
+        yield
+      rescue MatchError => e
+        raise e if (Time.now - start_time) >= seconds
+
+        sleep 0.05
+        retry
+      end
+    end
+  end
+end

data/lib/ttytest/tmux/driver.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'securerandom'
+
+require 'ttytest/terminal'
+require 'ttytest/tmux/session'
+
+module TTYtest
+  module Tmux
+    class Driver
+      COMMAND = 'tmux'
+      SOCKET_NAME = 'ttytest'
+      REQUIRED_TMUX_VERSION = '1.8'
+      DEFAULT_CONFING_FILE_PATH = File.expand_path('tmux.conf', __dir__)
+      SLEEP_INFINITY = 'read x < /dev/fd/1'
+
+      class TmuxError < StandardError; end
+
+      def initialize(
+        debug: false,
+        command: COMMAND,
+        socket_name: SOCKET_NAME,
+        config_file_path: DEFAULT_CONFING_FILE_PATH
+      )
+        @debug = debug
+        @tmux_cmd = command
+        @socket_name = socket_name
+        @config_file_path = config_file_path
+      end
+
+      def new_terminal(cmd, width: 80, height: 24)
+        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)
+      end
+
+      # @api private
+      def tmux(*args)
+        ensure_available
+        puts "tmux(#{args.inspect[1...-1]})" if debug?
+
+        stdout, stderr, status = Open3.capture3(@tmux_cmd, '-L', SOCKET_NAME, *args)
+        raise TmuxError, "tmux(#{args.inspect[1...-1]}) failed\n#{stderr}" unless status.success?
+
+        stdout
+      end
+
+      def available?
+        return false unless tmux_version
+
+        @available ||= (Gem::Version.new(tmux_version) >= Gem::Version.new(REQUIRED_TMUX_VERSION))
+      end
+
+      private
+
+      def debug?
+        @debug
+      end
+
+      def ensure_available
+        return if available?
+        raise TmuxError, 'Running `tmux -V` to determine version failed. Is tmux installed?' unless tmux_version
+
+        raise TmuxError, "tmux version #{tmux_version} does not meet requirement >= #{REQUIRED_TMUX_VERSION}"
+      end
+
+      def tmux_version
+        @tmux_version ||= `#{@tmux_cmd} -V`[/tmux (\d+.\d+)/, 1]
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/ttytest/tmux/session.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TTYtest
+  module Tmux
+    class Session
+      # @api private
+      def initialize(driver, name)
+        @driver = driver
+        @name = name
+
+        ObjectSpace.define_finalizer(self, self.class.finalize(driver, name))
+      end
+
+      # @api private
+      def self.finalize(driver, name)
+        proc { driver.tmux(*%W[kill-session -t #{name}]) }
+      end
+
+      def capture
+        contents = driver.tmux(*%W[capture-pane -t #{name} -p])
+        str = driver.tmux(*%W[display-message -t #{name} -p
+                              #\{cursor_x},#\{cursor_y},#\{cursor_flag},#\{pane_width},#\{pane_height},#\{pane_dead},#\{pane_dead_status},])
+        x, y, cursor_flag, width, height, pane_dead, pane_dead_status, _newline = str.split(',')
+
+        if pane_dead == '1'
+          raise Driver::TmuxError,
+                "Tmux pane has died\nCommand exited with status: #{pane_dead_status}\nEntire screen:\n#{contents}"
+        end
+
+        TTYtest::Capture.new(
+          contents.chomp("\n"),
+          cursor_x: x.to_i,
+          cursor_y: y.to_i,
+          width: width.to_i,
+          height: height.to_i,
+          cursor_visible: (cursor_flag != '0')
+        )
+      end
+
+      def send_keys(*keys)
+        driver.tmux(*%W[send-keys -t #{name} -l], *keys)
+      end
+
+      private
+
+      attr_reader :driver, :name
+    end
+  end
+end

data/lib/ttytest/tmux/tmux.conf

@@ -0,0 +1,3 @@
+set -g status off
+set -g remain-on-exit on
+set -g default-shell /bin/sh

data/lib/ttytest/version.rb

@@ -0,0 +1,3 @@
+module TTYtest
+  VERSION = '0.7.0'.freeze
+end

data/lib/ttytest.rb

@@ -0,0 +1,23 @@
+require 'forwardable'
+require 'ttytest/tmux/driver'
+require 'ttytest/tmux/session'
+
+module TTYtest
+  class << self
+    attr_accessor :driver, :default_max_wait_time
+
+    extend Forwardable
+    # @!method new_terminal(command, width: 80, height: 24)
+    #   Create a new terminal through the current driver.
+    #   @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
+    #   @return [Terminal] a new terminal running the specified command
+    def_delegators :driver, :new_terminal
+  end
+
+  class MatchError < StandardError; end
+
+  self.driver = TTYtest::Tmux::Driver.new
+  self.default_max_wait_time = 2
+end

data/notes.txt

@@ -0,0 +1,7 @@
+to push new version to github,
+git tag v0.7.0
+git push origin --tags
+
+to push new version to rubygems.org
+gem build ttytest2.gemspec
+gem push ttytest2-0.7.0.gem

data/ttytest2.gemspec

@@ -0,0 +1,29 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ttytest/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ttytest2'
+  spec.version       = TTYtest::VERSION
+  spec.authors       = ['Alex Eski']
+  spec.email         = ['alexeski@gmail.com']
+
+  spec.summary       = 'ttytest2 is an integration test framework for interactive tty applications. Based on TTYtest!'
+  spec.description   = 'ttytest2 allows running shell and/or cli applications inside of tmux and then making assertions on the output.'
+  spec.homepage      = 'https://github.com/a-eski/ttytest2'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.2.3'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'yard'
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: ttytest2
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- Alex Eski
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ttytest2 allows running shell and/or cli applications inside of tmux
+  and then making assertions on the output.
+email:
+- alexeski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/test.yml"
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- lib/ttytest.rb
+- lib/ttytest/capture.rb
+- lib/ttytest/matchers.rb
+- lib/ttytest/terminal.rb
+- lib/ttytest/tmux/driver.rb
+- lib/ttytest/tmux/session.rb
+- lib/ttytest/tmux/tmux.conf
+- lib/ttytest/version.rb
+- notes.txt
+- ttytest2.gemspec
+homepage: https://github.com/a-eski/ttytest2
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: ttytest2 is an integration test framework for interactive tty applications.
+  Based on TTYtest!
+test_files: []