tui-td 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 739ccd98a6d9a5ee8f29eadfdaaaa86cde8ee67cebf7bd9c293a20e1785f4bdb
-  data.tar.gz: bbeb1b4fcc9def290a68ee73df31d63d4fb3cb5a7a9a55b8d8cf5b8a57394885
+  metadata.gz: b5a923ea75814849ee5cf0633c81c09e2db156e47df52f6f92f2b314f743f3b7
+  data.tar.gz: c5cb55618e38bcc06a477bedce42d61d8f0c497ff38f887462943e8d094863b0
 SHA512:
-  metadata.gz: 6bb830eee8c25605c0cc1ecf7e5692fe5db1144c5c7cc2a6144367139056c6a2aa8650390429647d51b263058c21e78b46ee01c085fd0662ef3879ca551184e3
-  data.tar.gz: cbefe0d9f7483787190763563d5a1919aa8c476c1b57cddd704b981974b652b3b1734c59c60031ffd12e59d940a4a07f1abe937ab35012249a88a7303ca29073
+  metadata.gz: 1d36aac819998194c942dc9fc16c96ef0b4ef9fa7d549649f4bdd78cd59687858939ef7e1303d215a13e1dcd0957350d3839e43af94d4b837eb509ea5541cb58
+  data.tar.gz: 3d9f2fe282a9e32a274cea860ef5592e7666ce48121d590395c926bd0119d0f970ad2d2f232b88b0323742df8ef42b18686cd60ca75007d9f739cc2e8f4bae5b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 0.2.5
+
+- MCP smoke test expanded: 20 → 54 assertions, covers all 10 tools plus error paths (88% server coverage)
+- Extracted `ansi_utils.rb` — shared ANSI helpers used by parser, renderer, and screenshot
+- New RSpec specs for `ansi_utils`, enhanced specs for `test_runner`, `html_renderer`, `matchers`, `state`, `ansi_parser`
+
+## 0.2.4
+
+- `assert_regex` JSON test step — match terminal output against a Ruby regex
+- `assert_not_text` JSON test step — fail if text IS present (inverse of assert_text)
+- `have_regex` RSpec matcher — regex assertions in spec files
+- `have_text` negation in RSpec: `expect(state).not_to have_text("Error")`
+- README step reference table updated (all 13 step types listed)
+
 ## 0.2.3
 
 - `have_exit_status` RSpec matcher and `exitstatus` drive command — exit code testing on all three levels (JSON + RSpec + drive)

data/README.md

@@ -1,57 +1,23 @@
 # TUI Test Drive
 
-*Like Playwright or Puppeteer, but built specifically for Terminal UIs and optimized for AI Coding Agents.*
-
 Testing framework for Terminal User Interfaces (TUIs) with MCP support.
 
-A Ruby library, but language-agnostic through its JSON test format and MCP server — use it from Python, JavaScript, Go, or any other programming language on Linux and macOS.
-
 **tui-td** lets you:
 1. Start a TUI application in a virtual terminal (PTY)
 2. See the output — as structured JSON, plain text, PNG screenshots, or HTML renders
 3. Send input — keystrokes, text, control sequences
 4. Analyze output — find text, check colors, detect cursor position
 5. Loop — adjust and retest without manual intervention
-6. Integrate — works with any language via JSON test files or MCP
 
 ## Installation
 
-### 1. Install Ruby
-
-**rbenv (recommended):**
-
-```bash
-# macOS
-brew install rbenv ruby-build
-echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
-
-# Linux
-git clone https://github.com/rbenv/rbenv.git ~/.rbenv
-git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
-echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
-```
-
-Then install Ruby 3 and activate it:
-
-```bash
-rbenv install 3.4.1
-rbenv global 3.4.1
-ruby --version  # must show 3.0+
-```
-
-**Alternative — Homebrew (macOS):**
-
-```bash
-brew install ruby
-```
-
-### 2. Install tui-td
+Ruby 3.0+ is required. Install via [rbenv](https://github.com/rbenv/rbenv#installation) or `brew install ruby`.
 
 ```bash
 gem install tui-td
 ```
 
-### 3. Test
+Quick test:
 
 ```bash
 tui-td capture "echo Hello World"
@@ -124,20 +90,20 @@ Interactive commands (drive mode):
   exit               Quit drive mode
 
 Global options:
-  -r, --rows N          Terminal rows (default: 40)
-  -c, --cols N          Terminal cols (default: 120)
-  -t, --timeout N       Timeout in seconds (default: 30)
-  -C, --chdir PATH      Working directory for the command
-  --screenshot PATH     Save PNG screenshot
-  --html PATH           Save HTML render for browser viewing
-  --json                Output state as compact JSON (includes raw ANSI)
-  --pretty              Output state as pretty JSON
-  --text                Output state as plain text table
-  -v, --verbose         Show each test step as it runs
-  -l, --live            Show terminal state after each test step (screen-refresh)
-  -s, --step            Pause after each test step for confirmation
-  --version             Show version
-  -h, --help            Show complete reference
+    -r, --rows N                     Terminal rows (default: 40)
+    -c, --cols N                     Terminal cols (default: 120)
+    -t, --timeout SECONDS            Timeout in seconds (default: 30)
+    -C, --chdir PATH                 Working directory for the command
+        --screenshot PATH            Save screenshot (e.g., output.png)
+        --html PATH                  Save HTML render (e.g., output.html)
+        --json                       Output state as compact JSON
+        --pretty                     Output state as pretty JSON
+        --text                       Output state as plain text table
+    -v, --verbose                    Show each test step as it runs
+    -l, --live                       Show terminal state after each step (screen-refresh)
+    -s, --step                       Pause after each test step for confirmation
+        --version                    Show version
+    -h, --help                       Show help
 ```
 
 `tui-td --help` serves as the full CLI reference. `tui-td help test` shows all JSON test
@@ -271,12 +237,18 @@ tui-td test examples/echo_test.json
   "rows": 24,
   "cols": 80,
   "timeout": 10,
+  "chdir": "/path/to/project",
+  "before_all": [
+    { "start": "my_tui_app", "env": { "DATABASE_URL": "test://" } }
+  ],
   "steps": [
-    { "start": "my_tui_app" },
     { "wait_for_text": "> " },
     { "send": "hello\n" },
     { "assert_text": "hello" },
-    { "assert_fg": [0, 0], "is": "cyan" },
+    { "assert_regex": "hello|world" },
+    { "assert_fg": [0, 0], "is": "cyan" }
+  ],
+  "after_all": [
     { "close": true }
   ]
 }
@@ -292,9 +264,13 @@ tui-td test examples/echo_test.json
 | `wait_for_text` | `"text"` | Wait until text appears |
 | `wait_for_stable` | — | Wait until output is stable |
 | `assert_text` | `"text"` | Assert that text exists on screen |
+| `assert_not_text` | `"text"` | Assert that text does NOT exist on screen |
+| `assert_regex` | `"pattern"` | Assert that regex pattern matches (e.g. `"error\|fail"`) |
 | `assert_fg` | `[row, col], "is": "color"` | Assert foreground color |
 | `assert_bg` | `[row, col], "is": "color"` | Assert background color |
 | `assert_style` | `[row, col], "bold": true` | Assert cell style (bold, italic, underline) |
+| `wait_for_exit` | — | Wait until the process exits |
+| `assert_exit` | `N` | Assert the process exit code equals N |
 | `screenshot` | `"path"` | Save PNG screenshot |
 | `html` | `"path"` | Save HTML render for browser viewing |
 | `close` | — | Close the TUI |
@@ -367,9 +343,11 @@ end
 | Matcher | Usage |
 |---------|-------|
 | `have_text("...")` | Assert text is present on screen |
+| `have_regex(/pattern/)` | Assert regex pattern matches anywhere |
 | `have_fg("color").at(row, col)` | Assert foreground color at position |
 | `have_bg("color").at(row, col)` | Assert background color at position |
 | `have_style.at(row, col).with(bold: true, ...)` | Assert cell style |
+| `have_exit_status(N)` | Assert the driver process exit status equals N |
 
 ## MCP Server — AI Integration
 

data/lib/tui_td/ansi_parser.rb

@@ -83,15 +83,13 @@ module TUITD
     # Parse raw terminal output into a structured state Hash
     def self.parse(raw, rows = 40, cols = 120)
       grid = Array.new(rows) do
-        Array.new(cols) do
-          { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false }
-        end
+        Array.new(cols) { default_cell.dup }
       end
 
       cursor = { row: 0, col: 0 }
       attrs = { fg: "default", bg: "default", bold: false, italic: false, underline: false }
       saved_cursor = nil
-      scroll_region = nil
+      scroll_region = { top: 0, bottom: rows - 1 }
       pending_dsr = false
 
       # Strip everything before the last full clear (if any)
@@ -103,11 +101,12 @@ module TUITD
         if processed[i] == "\e" && processed[i + 1] == "["
           # Find end of CSI sequence
           j = i + 2
-          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fhlmnR]/)
+          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fhlmnRrsu]/)
           seq = processed[i..j]
 
-          dsr = _apply_csi(seq, cursor, attrs, grid, rows, cols)
+          dsr, new_saved = _apply_csi(seq, cursor, attrs, grid, rows, cols, saved_cursor, scroll_region)
           pending_dsr ||= dsr
+          saved_cursor = new_saved if new_saved
 
           i = j + 1
         elsif processed[i] == "\n" || processed[i] == "\r\n"
@@ -128,11 +127,20 @@ module TUITD
           # Bell — ignore
           i += 1
         elsif processed[i] == "\e"
-          # Skip escape sequences:
-          #   CSI: \e[... (already handled above)
-          #   ISO 2022 charset: \e( B  \e) 0  etc. (3 chars total)
-          #   Other: just the ESC
-          if processed[i + 1] && processed[i + 1].match?(/[()*+\-.\/]/)
+          # Handle non-CSI escape sequences
+          if processed[i + 1] == "7"
+            # DECSC — Save Cursor
+            saved_cursor = { row: cursor[:row], col: cursor[:col] }
+            i += 2
+          elsif processed[i + 1] == "8"
+            # DECRC — Restore Cursor
+            if saved_cursor
+              cursor[:row] = saved_cursor[:row]
+              cursor[:col] = saved_cursor[:col]
+            end
+            i += 2
+          elsif processed[i + 1] && processed[i + 1].match?(/[()*+\-.\/]/)
+            # ISO 2022 charset: \e( B  \e) 0  etc. (3 chars total)
             i += 3
           else
             i += 1
@@ -151,14 +159,22 @@ module TUITD
           i += 1
         end
 
-        # Handle scrolling
-        if cursor[:row] >= rows
-          scroll_lines = cursor[:row] - rows + 1
-          grid.shift(scroll_lines)
-          scroll_lines.times do
-            grid << Array.new(cols) { { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false } }
+        # Handle scrolling within the defined scroll region
+        region_top = scroll_region[:top]
+        region_bottom = scroll_region[:bottom]
+
+        if cursor[:row] > region_bottom
+          scroll_lines = [cursor[:row] - region_bottom, rows].min
+          # Shift lines within the scroll region up
+          (region_top..(region_bottom - scroll_lines)).each do |ri|
+            src = ri + scroll_lines
+            grid[ri] = src <= region_bottom ? grid[src] : Array.new(cols) { default_cell.dup }
+          end
+          # Fill bottom of scroll region with blank lines
+          ((region_bottom - scroll_lines + 1)..region_bottom).each do |ri|
+            grid[ri] = Array.new(cols) { default_cell.dup }
           end
-          cursor[:row] = rows - 1
+          cursor[:row] = region_bottom
         end
       end
 
@@ -211,15 +227,17 @@ module TUITD
       out
     end
 
-    def self._apply_csi(seq, cursor, attrs, grid, rows, cols)
+    def self._apply_csi(seq, cursor, attrs, grid, rows, cols, saved_cursor, scroll_region)
       # Strip leading escape char if present
       cleaned = seq.sub(/^\e/, "")
-      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhlmnR])$/)
-      return unless match
+      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhlmnRrsu])$/)
+      return [false, nil] unless match
 
       params = match[1].split(";").map(&:to_i)
       command = match[2]
 
+      new_saved = nil
+
       case command
       when "m"
         _apply_sgr(params, attrs)
@@ -270,14 +288,36 @@ module TUITD
           next unless cursor[:row] < rows && cursor[:col] + i < cols
           grid[cursor[:row]][cursor[:col] + i][:char] = " "
         end
-      when "h", "l" # DEC private mode set/reset — skip (alternate screen, cursor show/hide, etc.)
+      when "s" # DECSC — Save Cursor (CSI variant)
+        new_saved = { row: cursor[:row], col: cursor[:col] }
+      when "u" # DECRC — Restore Cursor (CSI variant)
+        if saved_cursor
+          cursor[:row] = saved_cursor[:row]
+          cursor[:col] = saved_cursor[:col]
+        end
+      when "r" # DECSTBM — Set Scroll Region
+        top = (params[0] || 1) - 1
+        bottom = (params[1] || rows) - 1
+        top = top.clamp(0, rows - 1)
+        bottom = bottom.clamp(0, rows - 1)
+        if top < bottom
+          scroll_region[:top] = top
+          scroll_region[:bottom] = bottom
+        else
+          scroll_region[:top] = 0
+          scroll_region[:bottom] = rows - 1
+        end
+        cursor[:row] = 0
+        cursor[:col] = 0
+      when "h", "l" # DEC private mode set/reset — skip
         nil
       when "n" # DSR — Device Status Report request
-        # \e[6n = request cursor position → caller must respond with \e[row;colR
-        return params[0] == 6
+        return [params[0] == 6, nil]
       when "R" # DSR response (from terminal side) or CPR — ignore
         nil
       end
+
+      [false, new_saved]
     end
 
     def self._apply_sgr(params, attrs)
@@ -397,21 +437,25 @@ module TUITD
     def self._color_code(name, prefix)
       case name
       when "default" then nil
-      when /^(bright_)?(.+)$/
-        base_name = $2
-        index = SGR_16_TO_NAME.key(base_name)
-        index += 8 if $1 && index && index < 8
-        index ? "#{prefix};5;#{index}" : nil
       when /^#([0-9a-fA-F]{6})$/
         r = $1[0..1].to_i(16)
         g = $1[2..3].to_i(16)
         b = $1[4..5].to_i(16)
         "#{prefix};2;#{r};#{g};#{b}"
+      when /^(bright_)?(.+)$/
+        base_name = $2
+        index = SGR_16_TO_NAME.key(base_name)
+        index += 8 if $1 && index && index < 8
+        index ? "#{prefix};5;#{index}" : nil
       else
         nil
       end
     end
 
+    def self.default_cell
+      { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false }
+    end
+
     # Extract a single UTF-8 character at position i in a binary string.
     # Returns [char_string, byte_length] or nil if the byte is not printable/valid.
     def self._utf8_char_at(str, i)

data/lib/tui_td/ansi_utils.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module TUITD
+  # Shared ANSI color constants and helpers.
+  # Used by Screenshot, HtmlRenderer, and other color-aware renderers.
+  module ANSIUtils
+    ANSI_RGB = {
+      "black"         => [0x00, 0x00, 0x00],
+      "red"           => [0xAA, 0x00, 0x00],
+      "green"         => [0x00, 0xAA, 0x00],
+      "yellow"        => [0xAA, 0x55, 0x00],
+      "blue"          => [0x00, 0x00, 0xAA],
+      "magenta"       => [0xAA, 0x00, 0xAA],
+      "cyan"          => [0x00, 0xAA, 0xAA],
+      "white"         => [0xAA, 0xAA, 0xAA],
+      "bright_black"  => [0x55, 0x55, 0x55],
+      "bright_red"    => [0xFF, 0x55, 0x55],
+      "bright_green"  => [0x55, 0xFF, 0x55],
+      "bright_yellow" => [0xFF, 0xFF, 0x55],
+      "bright_blue"   => [0x55, 0x55, 0xFF],
+      "bright_magenta"=> [0xFF, 0x55, 0xFF],
+      "bright_cyan"   => [0x55, 0xFF, 0xFF],
+      "bright_white"  => [0xFF, 0xFF, 0xFF],
+    }.freeze
+
+    CUBE = [0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF].freeze
+
+    ANSI_INDEX = %w[
+      black red green yellow blue magenta cyan white
+      bright_black bright_red bright_green bright_yellow
+      bright_blue bright_magenta bright_cyan bright_white
+    ].freeze
+
+    DEFAULT_FG = [0xC0, 0xC0, 0xC0].freeze
+    DEFAULT_BG = [0x00, 0x00, 0x00].freeze
+
+    def resolve_color(name, fallback)
+      case name
+      when "default"
+        fallback
+      when /^#([0-9a-fA-F]{6})$/
+        [$1[0..1].to_i(16), $1[2..3].to_i(16), $1[4..5].to_i(16)]
+      when /\Acolor(\d+)\z/
+        xterm_256($1.to_i)
+      when /\Abright_(.+)\z/
+        ANSI_RGB[name] || fallback
+      else
+        ANSI_RGB[name] || fallback
+      end
+    end
+
+    def xterm_256(index)
+      if index < 16
+        name = ANSI_INDEX[index]
+        ANSI_RGB[name] || DEFAULT_FG
+      elsif index < 232
+        r = CUBE[((index - 16) / 36) % 6]
+        g = CUBE[((index - 16) / 6) % 6]
+        b = CUBE[(index - 16) % 6]
+        [r, g, b]
+      else
+        v = 8 + (index - 232) * 10
+        [v, v, v]
+      end
+    end
+
+    def _dig(hash, *keys)
+      keys.each do |k|
+        return nil unless hash
+        hash = hash[k] || hash[k.to_s]
+      end
+      hash
+    end
+  end
+end

data/lib/tui_td/cli.rb

@@ -366,6 +366,13 @@ module TUITD
           {"assert_text": "<substring>"}
               Fail if the text is not found in the current state.
 
+          {"assert_not_text": "<substring>"}
+              Fail if the text IS found in the current state.
+
+          {"assert_regex": "<pattern>"}
+              Fail if the regex pattern does not match anywhere.
+              Pattern syntax is Ruby regex (e.g. "error|fail|warn").
+
           {"assert_fg": [row, col], "is": "<color>"}
               Assert foreground color at cell. Colors: "default",
               named ANSI (red, green, blue, cyan, ...), "bright_*",
@@ -432,6 +439,13 @@ module TUITD
         have_text(expected)
             Passes if expected text appears anywhere in the terminal state.
             Usage: expect(state).to have_text("Hello")
+            Negate: expect(state).not_to have_text("Error")
+
+        have_regex(pattern)
+            Passes if the regex pattern matches anywhere. Accepts a Regexp
+            or a string (parsed as Ruby regex).
+            Usage: expect(state).to have_regex(/error|fail/)
+            Usage: expect(state).to have_regex("\\d{3}")
 
         have_fg(expected).at(row, col)
             Assert foreground color at [row, col] matches expected.

data/lib/tui_td/html_renderer.rb

@@ -1,39 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "ansi_utils"
+
 module TUITD
   # Renders terminal state as a self-contained HTML document.
   # Faithfully reproduces what a TUI application shows — colors, styles,
   # cursor position — so an LLM or human can "see" the terminal.
   class HtmlRenderer
-    ANSI_RGB = {
-      "black"         => [0x00, 0x00, 0x00],
-      "red"           => [0xAA, 0x00, 0x00],
-      "green"         => [0x00, 0xAA, 0x00],
-      "yellow"        => [0xAA, 0x55, 0x00],
-      "blue"          => [0x00, 0x00, 0xAA],
-      "magenta"       => [0xAA, 0x00, 0xAA],
-      "cyan"          => [0x00, 0xAA, 0xAA],
-      "white"         => [0xAA, 0xAA, 0xAA],
-      "bright_black"  => [0x55, 0x55, 0x55],
-      "bright_red"    => [0xFF, 0x55, 0x55],
-      "bright_green"  => [0x55, 0xFF, 0x55],
-      "bright_yellow" => [0xFF, 0xFF, 0x55],
-      "bright_blue"   => [0x55, 0x55, 0xFF],
-      "bright_magenta"=> [0xFF, 0x55, 0xFF],
-      "bright_cyan"   => [0x55, 0xFF, 0xFF],
-      "bright_white"  => [0xFF, 0xFF, 0xFF],
-    }.freeze
-
-    CUBE = [0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF].freeze
-
-    ANSI_INDEX = %w[
-      black red green yellow blue magenta cyan white
-      bright_black bright_red bright_green bright_yellow
-      bright_blue bright_magenta bright_cyan bright_white
-    ].freeze
-
-    DEFAULT_FG = [0xC0, 0xC0, 0xC0].freeze
-    DEFAULT_BG = [0x00, 0x00, 0x00].freeze
+    include ANSIUtils
 
     def initialize(state)
       @state = state
@@ -173,36 +147,6 @@ module TUITD
       @cursor[:row] == ri && @cursor[:col] == ci
     end
 
-    def resolve_color(name, fallback)
-      case name
-      when "default"
-        fallback
-      when /^#([0-9a-fA-F]{6})$/
-        [$1[0..1].to_i(16), $1[2..3].to_i(16), $1[4..5].to_i(16)]
-      when /\Acolor(\d+)\z/
-        xterm_256($1.to_i)
-      when /\Abright_(.+)\z/
-        ANSI_RGB[name] || fallback
-      else
-        ANSI_RGB[name] || fallback
-      end
-    end
-
-    def xterm_256(index)
-      if index < 16
-        name = ANSI_INDEX[index]
-        ANSI_RGB[name] || DEFAULT_FG
-      elsif index < 232
-        r = CUBE[((index - 16) / 36) % 6]
-        g = CUBE[((index - 16) / 6) % 6]
-        b = CUBE[(index - 16) % 6]
-        [r, g, b]
-      else
-        v = 8 + (index - 232) * 10
-        [v, v, v]
-      end
-    end
-
     def css_color(rgb)
       format("#%02x%02x%02x", *rgb)
     end
@@ -217,12 +161,5 @@ module TUITD
       end
     end
 
-    def _dig(hash, *keys)
-      keys.each do |k|
-        return nil unless hash
-        hash = hash[k] || hash[k.to_s]
-      end
-      hash
-    end
   end
 end

data/lib/tui_td/matchers.rb

@@ -23,6 +23,17 @@ module TUITD
       failure_message_when_negated { |state| "expected terminal NOT to contain #{expected.inspect}" }
     end
 
+    RSpec::Matchers.define :have_regex do |pattern|
+      match do |state|
+        @regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+        state.find_text(@regex).any?
+      end
+
+      description { "match regex #{pattern.inspect}" }
+      failure_message { |state| "expected terminal to match #{pattern.inspect}" }
+      failure_message_when_negated { |state| "expected terminal NOT to match #{pattern.inspect}" }
+    end
+
     RSpec::Matchers.define :have_fg do |expected|
       chain(:at) { |row, col| @row, @col = row, col }
 

data/lib/tui_td/screenshot.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "chunky_png"
+require_relative "ansi_utils"
 
 module TUITD
   class Screenshot
+    include ANSIUtils
+
     CELL_W = 8
     CELL_H = 16
 
@@ -106,39 +109,6 @@ module TUITD
     ].freeze
     private_constant :FONT
 
-    ANSI_RGB = {
-      "black"         => [0x00, 0x00, 0x00],
-      "red"           => [0xAA, 0x00, 0x00],
-      "green"         => [0x00, 0xAA, 0x00],
-      "yellow"        => [0xAA, 0x55, 0x00],
-      "blue"          => [0x00, 0x00, 0xAA],
-      "magenta"       => [0xAA, 0x00, 0xAA],
-      "cyan"          => [0x00, 0xAA, 0xAA],
-      "white"         => [0xAA, 0xAA, 0xAA],
-      "bright_black"  => [0x55, 0x55, 0x55],
-      "bright_red"    => [0xFF, 0x55, 0x55],
-      "bright_green"  => [0x55, 0xFF, 0x55],
-      "bright_yellow" => [0xFF, 0xFF, 0x55],
-      "bright_blue"   => [0x55, 0x55, 0xFF],
-      "bright_magenta"=> [0xFF, 0x55, 0xFF],
-      "bright_cyan"   => [0x55, 0xFF, 0xFF],
-      "bright_white"  => [0xFF, 0xFF, 0xFF],
-    }.freeze
-    private_constant :ANSI_RGB
-
-    CUBE = [0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF].freeze
-    private_constant :CUBE
-
-    ANSI_INDEX = %w[
-      black red green yellow blue magenta cyan white
-      bright_black bright_red bright_green bright_yellow
-      bright_blue bright_magenta bright_cyan bright_white
-    ].freeze
-    private_constant :ANSI_INDEX
-
-    DEFAULT_FG = [0xC0, 0xC0, 0xC0].freeze
-    DEFAULT_BG = [0x00, 0x00, 0x00].freeze
-
     def initialize(state)
       @state = state
       @rows = _dig(state, :size, :rows) || 40
@@ -191,36 +161,6 @@ module TUITD
       draw_underline(image, px, py, CELL_W, fg_rgb) if underline
     end
 
-    def resolve_color(name, fallback)
-      case name
-      when "default"
-        fallback
-      when /^#([0-9a-fA-F]{6})$/
-        [$1[0..1].to_i(16), $1[2..3].to_i(16), $1[4..5].to_i(16)]
-      when /\Acolor(\d+)\z/
-        xterm_256($1.to_i)
-      when /\Abright_(.+)\z/
-        ANSI_RGB[name] || fallback
-      else
-        ANSI_RGB[name] || fallback
-      end
-    end
-
-    def xterm_256(index)
-      if index < 16
-        name = ANSI_INDEX[index]
-        ANSI_RGB[name] || DEFAULT_FG
-      elsif index < 232
-        r = CUBE[((index - 16) / 36) % 6]
-        g = CUBE[((index - 16) / 6) % 6]
-        b = CUBE[(index - 16) % 6]
-        [r, g, b]
-      else
-        v = 8 + (index - 232) * 10
-        [v, v, v]
-      end
-    end
-
     def fill_rect(image, x, y, w, h, rgb)
       color = ChunkyPNG::Color.rgb(*rgb)
       h.times do |dy|
@@ -260,12 +200,5 @@ module TUITD
       w.times { |dx| image[px + dx, y] = color }
     end
 
-    def _dig(hash, *keys)
-      keys.each do |k|
-        return nil unless hash
-        hash = hash[k] || hash[k.to_s]
-      end
-      hash
-    end
   end
 end

data/lib/tui_td/state.rb

@@ -7,6 +7,9 @@ module TUITD
     attr_reader :rows, :cols, :grid, :cursor
 
     def initialize(data)
+      raise ArgumentError, "State data must include :size key" unless data[:size]
+      raise ArgumentError, "State data must include :rows key" unless data[:rows]
+
       @rows = data[:size][:rows]
       @cols = data[:size][:cols]
       @grid = data[:rows]

data/lib/tui_td/test_runner.rb

@@ -37,6 +37,12 @@ module TUITD
       @plan[:before_all] = @plan[:before_all]&.map { |s| s.transform_keys(&:to_sym) }
       @plan[:after_all] = @plan[:after_all]&.map { |s| s.transform_keys(&:to_sym) }
       @on_step = on_step
+    rescue JSON::ParserError => e
+      raise Error, "Invalid JSON: #{e.message}"
+      @plan[:steps] = @plan[:steps].map { |s| s.transform_keys(&:to_sym) }
+      @plan[:before_all] = @plan[:before_all]&.map { |s| s.transform_keys(&:to_sym) }
+      @plan[:after_all] = @plan[:after_all]&.map { |s| s.transform_keys(&:to_sym) }
+      @on_step = on_step
     end
 
     def run
@@ -88,122 +94,98 @@ module TUITD
                   Result.new(step: action, passed: true, message: "Found: #{value}")
 
                 when "wait_for_stable"
-                ensure_driver!(driver)
-                driver.wait_for_stable
-                Result.new(step: action, passed: true, message: "Stable")
-
-              when "assert_text"
-                ensure_driver!(driver)
-                state = State.new(driver.state_data)
-                if state.find_text(value.to_s).any?
-                  Result.new(step: action, passed: true, message: "Text found: #{value}")
-                else
-                  Result.new(step: action, passed: false, message: "Text NOT found: #{value}")
-                end
+                  ensure_driver!(driver)
+                  driver.wait_for_stable
+                  Result.new(step: action, passed: true, message: "Stable")
 
-              when "assert_fg"
-                ensure_driver!(driver)
-                row, col = coords(step)
-                expected = step[:is] || step["is"]
-                state = State.new(driver.state_data)
-                actual = state.foreground_at(row, col)
-                if actual == expected
-                  Result.new(step: action, passed: true, message: "FG at [#{row},#{col}] is #{expected}")
-                else
-                  Result.new(step: action, passed: false, message: "FG at [#{row},#{col}] is #{actual}, expected #{expected}")
-                end
+                when "assert_text", "assert_not_text", "assert_regex"
+                  check_text(driver, value, action)
 
-              when "assert_bg"
-                ensure_driver!(driver)
-                row, col = coords(step)
-                expected = step[:is] || step["is"]
-                state = State.new(driver.state_data)
-                actual = state.background_at(row, col)
-                if actual == expected
-                  Result.new(step: action, passed: true, message: "BG at [#{row},#{col}] is #{expected}")
-                else
-                  Result.new(step: action, passed: false, message: "BG at [#{row},#{col}] is #{actual}, expected #{expected}")
-                end
+                when "assert_fg"
+                  check_color(driver, step, :fg)
 
-              when "assert_style"
-                ensure_driver!(driver)
-                row, col = coords(step)
-                state = State.new(driver.state_data)
-                actual = state.style_at(row, col)
-                expected = {}
-                expected[:bold] = step[:bold] unless step[:bold].nil?
-                expected[:italic] = step[:italic] unless step[:italic].nil?
-                expected[:underline] = step[:underline] unless step[:underline].nil?
-                match = expected.all? { |k, v| actual[k] == v }
-                if match
-                  Result.new(step: action, passed: true, message: "Style at [#{row},#{col}] matches #{expected}")
-                else
-                  Result.new(step: action, passed: false, message: "Style at [#{row},#{col}] is #{actual}, expected #{expected}")
-                end
+                when "assert_bg"
+                  check_color(driver, step, :bg)
 
-              when "screenshot"
-                ensure_driver!(driver)
-                path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.png"
-                driver.screenshot(path)
-                Result.new(step: action, passed: true, message: "Saved: #{path}")
-
-              when "html"
-                ensure_driver!(driver)
-                path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.html"
-                HtmlRenderer.new(driver.state_data).render(path)
-                Result.new(step: action, passed: true, message: "Saved: #{path}")
-
-              when "wait_for_exit"
-                ensure_driver!(driver)
-                driver.wait_for_exit
-                status = driver.exitstatus
-                Result.new(step: action, passed: true, message: "Exited with status #{status}")
-
-              when "assert_exit"
-                ensure_driver!(driver)
-                expected = value.to_s.to_i
-                actual = driver.exitstatus
-                if actual == expected
-                  Result.new(step: action, passed: true, message: "Exit status #{expected} matches")
-                else
-                  Result.new(step: action, passed: false, message: "Exit status #{actual}, expected #{expected}")
-                end
+                when "assert_style"
+                  ensure_driver!(driver)
+                  row, col = coords(step)
+                  state = State.new(driver.state_data)
+                  actual = state.style_at(row, col)
+                  expected = {}
+                  expected[:bold] = step[:bold] unless step[:bold].nil?
+                  expected[:italic] = step[:italic] unless step[:italic].nil?
+                  expected[:underline] = step[:underline] unless step[:underline].nil?
+                  match = expected.all? { |k, v| actual[k] == v }
+                  if match
+                    Result.new(step: action, passed: true, message: "Style at [#{row},#{col}] matches #{expected}")
+                  else
+                    Result.new(step: action, passed: false, message: "Style at [#{row},#{col}] is #{actual}, expected #{expected}")
+                  end
 
-              when "close"
-                driver&.close
-                driver = nil
-                Result.new(step: action, passed: true, message: "Closed")
+                when "screenshot"
+                  ensure_driver!(driver)
+                  path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.png"
+                  driver.screenshot(path)
+                  Result.new(step: action, passed: true, message: "Saved: #{path}")
 
-              else
-                Result.new(step: action, passed: false, message: "Unknown action: #{action}")
-              end
+                when "html"
+                  ensure_driver!(driver)
+                  path = value.is_a?(String) ? value : "/tmp/tui_td_#{Time.now.to_i}.html"
+                  HtmlRenderer.new(driver.state_data).render(path)
+                  Result.new(step: action, passed: true, message: "Saved: #{path}")
 
-        rescue StandardError => e
-          r = Result.new(step: action, passed: false, message: "#{e.class}: #{e.message}")
-        end
+                when "wait_for_exit"
+                  ensure_driver!(driver)
+                  driver.wait_for_exit
+                  status = driver.exitstatus
+                  Result.new(step: action, passed: true, message: "Exited with status #{status}")
 
-        all_results << r
-        all_passed &&= r.passed
+                when "assert_exit"
+                  ensure_driver!(driver)
+                  expected = value.to_s.to_i
+                  actual = driver.exitstatus
+                  if actual == expected
+                    Result.new(step: action, passed: true, message: "Exit status #{expected} matches")
+                  else
+                    Result.new(step: action, passed: false, message: "Exit status #{actual}, expected #{expected}")
+                  end
 
-        if @on_step
-          state_data = nil
-          begin
-            state_data = driver.state_data if driver
-          rescue StandardError
-            # ignore — state retrieval is best-effort
+                when "close"
+                  driver&.close
+                  driver = nil
+                  Result.new(step: action, passed: true, message: "Closed")
+
+                else
+                  Result.new(step: action, passed: false, message: "Unknown action: #{action}")
+                end
+
+          rescue StandardError => e
+            r = Result.new(step: action, passed: false, message: "#{e.class}: #{e.message}")
+          end
+
+          all_results << r
+          all_passed &&= r.passed
+
+          if @on_step
+            state_data = nil
+            begin
+              state_data = driver.state_data if driver
+            rescue StandardError
+              # ignore — state retrieval is best-effort
+            end
+            @on_step.call(
+              index: all_results.size - 1,
+              total: total_steps,
+              action: action,
+              value: value,
+              result: r,
+              driver: driver,
+              state_data: state_data
+            )
           end
-          @on_step.call(
-            index: all_results.size - 1,
-            total: total_steps,
-            action: action,
-            value: value,
-            result: r,
-            driver: driver,
-            state_data: state_data
-          )
         end
       end
-      end
 
       driver&.close
 
@@ -222,10 +204,65 @@ module TUITD
 
     def coords(step)
       pos = step[:assert_fg] || step[:assert_bg] || step[:assert_style]
-      pos = value if pos.nil? && (value = step.values.first).is_a?(Array)
       row = pos.is_a?(Array) ? pos[0] : (pos[:row] || pos["row"] || 0)
       col = pos.is_a?(Array) ? pos[1] : (pos[:col] || pos["col"] || 0)
       [row, col]
     end
+
+    def check_text(driver, value, action)
+      ensure_driver!(driver)
+      state = State.new(driver.state_data)
+      text = value.to_s
+
+      if action == "assert_regex"
+        begin
+          pattern = Regexp.new(text)
+        rescue RegexpError => e
+          return Result.new(step: action, passed: false, message: "Invalid regex: #{e.message}")
+        end
+      else
+        pattern = text
+      end
+
+      found = state.find_text(pattern).any?
+
+      case action
+      when "assert_text"
+        if found
+          Result.new(step: action, passed: true, message: "Text found: #{value}")
+        else
+          Result.new(step: action, passed: false, message: "Text NOT found: #{value}")
+        end
+      when "assert_not_text"
+        if found
+          Result.new(step: action, passed: false, message: "Text found but should not be: #{value}")
+        else
+          Result.new(step: action, passed: true, message: "Text not found: #{value}")
+        end
+      when "assert_regex"
+        if found
+          Result.new(step: action, passed: true, message: "Regex matched: #{value}")
+        else
+          Result.new(step: action, passed: false, message: "Regex did not match: #{value}")
+        end
+      else
+        Result.new(step: action, passed: false, message: "Unknown text check: #{action}")
+      end
+    end
+
+    def check_color(driver, step, property)
+      ensure_driver!(driver)
+      row, col = coords(step)
+      expected = step[:is] || step["is"]
+      state = State.new(driver.state_data)
+      label = property == :fg ? "FG" : "BG"
+      actual = property == :fg ? state.foreground_at(row, col) : state.background_at(row, col)
+
+      if actual == expected
+        Result.new(step: step.keys.first.to_s, passed: true, message: "#{label} at [#{row},#{col}] is #{expected}")
+      else
+        Result.new(step: step.keys.first.to_s, passed: false, message: "#{label} at [#{row},#{col}] is #{actual}, expected #{expected}")
+      end
+    end
   end
 end

data/lib/tui_td/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TUITD
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

data/lib/tui_td.rb

@@ -7,6 +7,7 @@ end
 require_relative "tui_td/version"
 require_relative "tui_td/driver"
 require_relative "tui_td/ansi_parser"
+require_relative "tui_td/ansi_utils"
 require_relative "tui_td/state"
 require_relative "tui_td/screenshot"
 require_relative "tui_td/html_renderer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Haluk Durmus
@@ -123,6 +123,7 @@ files:
 - bin/tui-td
 - lib/tui_td.rb
 - lib/tui_td/ansi_parser.rb
+- lib/tui_td/ansi_utils.rb
 - lib/tui_td/cli.rb
 - lib/tui_td/driver.rb
 - lib/tui_td/html_renderer.rb