tui-td 0.2.19 → 0.2.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48cd9df54d8ad7bc1d41b8d4cfd961462ecff6e8056c4fd37e46abb56fa50f38
-  data.tar.gz: c77b9a6eb3a048806d17d4f5b2245dcf82dd1c5e818a247db48912e9b590d78d
+  metadata.gz: fcd0909e5284e4bdd97bd38154ba64108c9c6e95903ca067126b8fb16215ae28
+  data.tar.gz: 9b2bf1430a37e58a72c8f185adbbfb500a70f78a3a80bb66e083dee3e9124aa8
 SHA512:
-  metadata.gz: ce4bdb6d4397369717686756508ec43219340ed4a0cc0ec8a4851018a19dc19bbdec3050147238a221cd4b282c92d848df1d71a1377b4915bfb42282af400d95
-  data.tar.gz: 6053e73dd915f8839d92ef8b046578bae6fbf481b0fda21872851e7e9052816833ce62ab5d6a4d15a685ce517f161fe31e75d5a9309a0dacb3521a3df4e893af
+  metadata.gz: 4c084254da02d47fe56471eab086e89f35025c875153e0987b8399de324894a270a7488992c64ad78aa888c7886810898b0365b1a288667caef4c17f68096b82
+  data.tar.gz: 97aafa9d1056b7db02f84cb9b378edfb869e0651bfebaeceedfcb0f75d05ad76f97994a2986af80e84d8d8cbf77c9e0641600860247e771bb58b404b4aabd492

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # CHANGELOG
 
+## 0.2.20
+
+### Added
+
+- Video recording via ffmpeg: `VideoRecorder` class pipes PNG frames from the
+  existing Screenshot pipeline directly to ffmpeg for incremental encoding
+- Driver methods: `start_recording`, `stop_recording`, `recording?`
+- CLI flags: `--record <path>`, `--framerate <N>`, `--codec <name>`
+- MCP tools: `tui_record_start`, `tui_record_stop`, `tui_record_status`
+- JSON test steps: `start_recording`, `stop_recording`, `assert_recording`
+- Minitest assertions: `assert_record_start`, `assert_record_stop`,
+  `assert_recording`, `refute_recording`
+- RSpec matchers: `be_recording`, `have_recorded_video`
+- Configuration: `ffmpeg_path`, `record_default_fps`, `record_default_codec`
+- `Screenshot#to_blob` for in-memory PNG rendering (no temp files)
+
+### Changed
+
+- `Driver#close` auto-stops recording if active
+- `TestRunner#run` auto-stops recording on `close` step
+
+## 0.2.19
+
+### Added
+
+- Minitest integration: `TUITD::Minitest::Assertions` module with 34 assertion methods
+  (17 assert + 17 refute) covering text, regex, colors, styles, exit status, all 9
+  element roles, and named snapshots with region/ignore_rows support
+- Auto-wait for Minitest: Driver assertions wait up to 3s, State checks immediately
+- `tui-td help minitest` — complete assertion reference
+- Example: `examples/minitest_example_test.rb` with 7 test cases
+- Smoke test: `test/minitest_smoke_test.rb` (10 runs, 19 assertions)
+
+### Changed
+
+- Updated gemspec metadata (summary, description) for rubygems.org
+
+## 0.2.18
+
+(yanked — same as 0.2.19 but with outdated gemspec metadata)
+
 ## 0.2.17
 
 ### Added

data/README.md

@@ -3,7 +3,11 @@
 [![Gem Version](https://badge.fury.io/rb/tui-td.svg)](https://rubygems.org/gems/tui-td)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-Testing framework for Terminal User Interfaces (TUIs). Start a TUI in a PTY, send input, analyze output — as structured JSON, plain text, PNG screenshots, or HTML renders. Includes an MCP server for AI-driven testing, auto-wait RSpec matchers, and semantic selectors.
+Testing framework and general-purpose TUI driver. Start a TUI in a PTY, send input, analyze output — as structured JSON, plain text, PNG screenshots, or HTML renders. Use it for testing, automation, or as a bridge between AI agents and terminal apps.
+
+**Language-agnostic:** JSON tests + CLI + MCP let you drive TUIs from any language (Python, JavaScript, Rust, Go, …). Write a `.json` test plan, script via `tui-td drive`, or let an AI agent control a TUI through `tui-td serve`.
+
+**Ruby-native:** In the Ruby ecosystem, tui-td integrates with RSpec and Minitest — auto-wait matchers and assertions included.
 
 > New to tui-td? Jump to [Quick Start](docs/quick_start.md).
 
@@ -13,10 +17,12 @@ Testing framework for Terminal User Interfaces (TUIs). Start a TUI in a PTY, sen
 2. **Auto-wait assertions** — matchers automatically retry until the condition is met or timeout
 3. **Semantic selectors** — `get_by_role(:button)`, `get_by_role(:dialog)`, `within { }` scoping
 4. **Multiple output formats** — structured JSON, plain text, PNG screenshots, HTML renders
-5. **JSON test runner** — language-agnostic, 15+ step types, CI-friendly
+5. **JSON test runner** — language-agnostic, 23+ step types, CI-friendly
 6. **RSpec matchers** — `have_text`, `have_fg`, `have_button`, `have_dialog`, and more
-7. **MCP server** — AI agents can drive TUIs via JSON-RPC over stdio
-8. **Pure Ruby rendering** — embedded Spleen font + 2766 Unifont glyphs, no native deps required
+7. **Minitest assertions** — `assert_text`, `assert_button`, `assert_snapshot`, and more
+8. **MCP server** — AI agents can drive TUIs via JSON-RPC over stdio
+9. **Pure Ruby rendering** — embedded Spleen font + 2766 Unifont glyphs, no native deps required
+10. **Video recording** — record TUI sessions as MP4 via ffmpeg for demos, debugging, and AI agent playback
 
 ## Installation
 
@@ -53,6 +59,9 @@ tui-td --html output.html capture "htop"
 # Save as a PNG screenshot
 tui-td --screenshot output.png capture "htop"
 
+# Record a session as video (requires ffmpeg)
+tui-td --record demo.mp4 capture "htop" --timeout 10
+
 # Drive a TUI interactively
 tui-td drive "htop"
 # At the > prompt:
@@ -106,6 +115,9 @@ Global options:
     -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)
+        --record PATH                Record session as video (MP4/WebM, requires ffmpeg)
+        --framerate N                Recording framerate (default: 30)
+        --codec NAME                 Video codec: libx264, libx265, libvpx-vp9 (default: libx264)
         --json                       Output state as compact JSON
         --pretty                     Output state as pretty JSON
         --text                       Output state as plain text table
@@ -117,7 +129,7 @@ Global options:
 ```
 
 `tui-td --help` serves as the full CLI reference. `tui-td help test` shows all JSON test
-step types and `tui-td help rspec` shows all RSpec matchers — no need to consult the docs.
+step types, `tui-td help rspec` shows all RSpec matchers, and `tui-td help minitest` shows all Minitest assertions — no need to consult the docs.
 
 ## Demo
 
@@ -161,6 +173,11 @@ driver.screenshot("screenshot.png")  # PNG renderer
 TUITD::HtmlRenderer.new(driver.state_data).render("output.html")  # HTML renderer
 html_string = TUITD::HtmlRenderer.new(driver.state_data).to_html   # HTML string
 
+# Video recording (requires ffmpeg)
+driver.start_recording("session.mp4", framerate: 30, codec: "libx264")
+driver.recording?                   # => true
+driver.stop_recording               # => "session.mp4"
+
 driver.close
 ```
 
@@ -293,6 +310,9 @@ tui-td test examples/echo_test.json
 | `assert_tab` | `"text"` | Assert a tab (`[Tab1]`) is visible |
 | `assert_statusbar` | — | Assert a status bar (bottom row with background) is visible |
 | `assert_progress_bar` | `"text"` (optional) | Assert a progress bar (`[####]`) is visible |
+| `start_recording` | `"path", "framerate": 30` | Start video recording (requires ffmpeg) |
+| `stop_recording` | — | Stop recording and finalize video |
+| `assert_recording` | `true` / `false` | Assert recording is active / not active |
 | `close` | — | Close the TUI |
 
 Example with `html` step for before/after snapshots:
@@ -378,6 +398,58 @@ end
 | `have_statusbar` | Assert a status bar (bottom row with background) is visible |
 | `have_progress_bar("50%")` | Assert a progress bar (`[####]`) is visible |
 | `have_exit_status(N)` | Assert the driver process exit status equals N |
+| `be_recording` | Assert that the driver is currently recording video |
+| `have_recorded_video("path.mp4")` | Assert that a video file was created and has content |
+
+## Minitest Assertions
+
+Include the assertions module for native Minitest support (auto-wait included):
+
+```ruby
+require "tui_td/minitest/assertions"
+
+class MyTUITest < Minitest::Test
+  include TUITD::Minitest::Assertions
+
+  def test_login
+    driver = TUITD::Driver.new("my_tui", rows: 24, cols: 80)
+    driver.start
+    assert_text(driver, "Welcome")
+    assert_button(driver, "OK")
+    refute_text(driver, "Error")
+    assert_snapshot(driver, "login", type: :text, region: 0..6)
+  ensure
+    driver&.close
+  end
+end
+```
+
+| Assertion | Usage |
+|-----------|-------|
+| `assert_text(driver, "...")` | Assert text is present |
+| `refute_text(driver, "...")` | Assert text is NOT present |
+| `assert_regex(driver, /pattern/)` | Assert regex matches |
+| `assert_fg(driver, "cyan", row:, col:)` | Assert foreground color |
+| `assert_bg(driver, "blue", row:, col:)` | Assert background color |
+| `assert_style(driver, row:, col:, bold: true)` | Assert cell style |
+| `assert_exit_status(driver, 0)` | Assert process exit status |
+| `assert_button(driver, "OK")` | Assert button with given text |
+| `assert_dialog(driver)` | Assert a dialog is visible |
+| `assert_checkbox(driver, "Label", checked: true)` | Assert checkbox with state |
+| `assert_role(driver, :button, text: "OK")` | Generic role assertion |
+| `assert_input(driver)` | Assert an input field |
+| `assert_label(driver, "Name")` | Assert a label |
+| `assert_menu(driver)` | Assert a menu |
+| `assert_tab(driver, "File")` | Assert a tab |
+| `assert_statusbar(driver)` | Assert a status bar |
+| `assert_progress_bar(driver)` | Assert a progress bar |
+| `assert_snapshot(driver, "name", type:, region:, ignore_rows:)` | Named snapshot comparison |
+| `assert_record_start(driver, "path", framerate:)` | Start video recording |
+| `assert_record_stop(driver)` | Stop recording and finalize video |
+| `assert_recording(driver)` | Assert recording is active |
+| `refute_recording(driver)` | Assert recording is NOT active |
+
+See `tui-td help minitest` for the full reference.
 
 ## Snapshot Testing
 
@@ -459,6 +531,9 @@ tui-td serve
 | `tui_annotate_element` | Manually register a UI element annotation. Picked up by tui_find_elements. |
 | `tui_save_snapshot` | Save the current terminal state as a named snapshot to disk. |
 | `tui_assert_snapshot` | Assert current state matches a saved named snapshot. Creates on first run. |
+| `tui_record_start` | Start video recording with path, framerate, codec, and quality options. |
+| `tui_record_stop` | Stop recording and finalize the video file. |
+| `tui_record_status` | Check if recording is currently active. |
 | `tui_close` | Close the TUI and clean up. |
 
 ### MCP configuration
@@ -604,6 +679,93 @@ html = TUITD::HtmlRenderer.new(driver.state_data).to_html
 {"html": "/tmp/snapshot.html"}
 ```
 
+## Video Recording
+
+Record TUI sessions as MP4 video using ffmpeg. Frames are captured via the same Screenshot pipeline and piped directly to ffmpeg for incremental encoding — no temporary frame files.
+
+**Requires ffmpeg** (`brew install ffmpeg` on macOS, `apt install ffmpeg` on Debian).
+
+```bash
+# Record a capture session
+tui-td --record demo.mp4 capture "htop" --timeout 10
+
+# High-framerate recording
+tui-td --record session.mp4 --framerate 60 drive "vim file.txt"
+
+# Custom codec and quality
+tui-td --record output.mp4 --codec libx265 --framerate 30 capture "glow README.md"
+```
+
+### Ruby API
+
+```ruby
+driver = TUITD::Driver.new("htop", rows: 40, cols: 120)
+driver.start
+
+# Start recording
+driver.start_recording("session.mp4", framerate: 30, codec: "libx264", quality: "high")
+
+# Check recording status
+driver.recording?  # => true
+
+# ... interact with TUI ...
+
+# Stop recording
+driver.stop_recording  # => "session.mp4"
+driver.close             # auto-stops recording if active
+```
+
+### Configuration
+
+```ruby
+TUITD.configure do |c|
+  c.ffmpeg_path           = "/usr/local/bin/ffmpeg"  # default: auto-detect
+  c.record_default_fps    = 30
+  c.record_default_codec  = "libx264"
+end
+```
+
+### RSpec
+
+```ruby
+require "tui_td/matchers"
+
+driver.start_recording("test.mp4", framerate: 30)
+expect(driver).to be_recording
+# ... interact ...
+driver.stop_recording
+expect(driver).not_to be_recording
+expect(driver).to have_recorded_video("test.mp4")
+```
+
+### Minitest
+
+```ruby
+require "tui_td/minitest/assertions"
+
+assert_record_start(driver, "test.mp4", framerate: 30)
+assert_recording(driver)
+# ... interact ...
+assert_record_stop(driver)
+refute_recording(driver)
+```
+
+### JSON Test Steps
+
+```json
+{"start_recording": "output.mp4", "framerate": 30, "codec": "libx264"}
+{"assert_recording": true}
+{"stop_recording": true}
+```
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `tui_record_start` | Start recording with path, framerate, codec, quality |
+| `tui_record_stop` | Stop recording and finalize video file |
+| `tui_record_status` | Check if recording is currently active |
+
 ## License
 
 MIT

data/lib/tui_td/cli.rb

@@ -71,6 +71,15 @@ module TUITD
         opts.on("--html PATH", "Save HTML render (e.g., output.html)") do |p|
           global_opts[:html] = p
         end
+        opts.on("--record PATH", "Record session as video (MP4/WebM, requires ffmpeg)") do |p|
+          global_opts[:record] = p
+        end
+        opts.on("--framerate N", Integer, "Recording framerate (default: 30)") do |f|
+          global_opts[:record_framerate] = f
+        end
+        opts.on("--codec NAME", "Video codec: libx264, libx265, libvpx-vp9 (default: libx264)") do |c|
+          global_opts[:record_codec] = c
+        end
         opts.on("--json", "Output state as compact JSON") do |_|
           global_opts[:format] = :json
         end
@@ -136,6 +145,23 @@ module TUITD
 
     private
 
+    def _start_recording_if(driver, globals)
+      return unless globals[:record]
+
+      framerate = globals[:record_framerate] || 30
+      codec = globals[:record_codec] || "libx264"
+      path = driver.start_recording(globals[:record], framerate: framerate, codec: codec)
+      puts "Recording to: #{path}"
+      path
+    end
+
+    def _stop_recording(driver)
+      return unless driver.recording?
+
+      path = driver.stop_recording
+      puts "Recording saved: #{path}" if path
+    end
+
     def cmd_serve(globals)
       server = MCP::Server.new(
         rows: globals[:rows] || 40,
@@ -155,6 +181,8 @@ module TUITD
       puts "─" * (globals[:cols] || 80)
       driver.start
 
+      _start_recording_if(driver, globals)
+
       driver.wait_for_stable
 
       if %i[json pretty_json].include?(globals[:format])
@@ -172,6 +200,7 @@ module TUITD
         puts "HTML saved: #{path}"
       end
 
+      _stop_recording(driver)
       driver.close
     end
 
@@ -185,6 +214,8 @@ module TUITD
       puts "Type commands to send. Exit with Ctrl+C."
       driver.start
 
+      _start_recording_if(driver, globals)
+
       begin
         loop do
           driver.wait_for_stable
@@ -264,6 +295,7 @@ module TUITD
       rescue Interrupt
         puts "\nDone."
       ensure
+        _stop_recording(driver)
         driver.close
       end
     end
@@ -281,6 +313,9 @@ module TUITD
         # Proceed with whatever was rendered before the timeout.
         driver.refresh
       end
+
+      _start_recording_if(driver, globals)
+
       begin
         driver.wait_for_stable
       rescue TimeoutError
@@ -305,6 +340,7 @@ module TUITD
         puts "HTML saved: #{path}"
       end
 
+      _stop_recording(driver)
       driver.close
     end
 
@@ -462,6 +498,16 @@ module TUITD
           {"html": "<path>"}
               Save an HTML render. Path defaults to /tmp/tui_td_<ts>.html.
 
+          {"start_recording": "<path>", "framerate": 30, "codec": "libx264"}
+              Start recording the TUI session as a video (requires ffmpeg).
+              framerate defaults to 30, codec defaults to libx264.
+
+          {"stop_recording": true}
+              Stop video recording and finalize the video file.
+
+          {"assert_recording": true}
+              Assert that recording is active. Use false to assert NOT recording.
+
           {"wait_for_exit": true}
               Wait until the process exits naturally.
 
@@ -650,6 +696,22 @@ module TUITD
         have_exit_status(expected)
             Assert the process exit status matches expected.
             Usage: expect(driver).to have_exit_status(0)
+
+        Video Recording
+        ---------------
+
+        Start/stop recording via Driver methods, then verify with matchers:
+
+          driver.start_recording("test.mp4", framerate: 30, codec: "libx264")
+          expect(driver).to be_recording
+          # ... interact with TUI ...
+          driver.stop_recording
+          expect(driver).not_to be_recording
+          expect(driver).to have_recorded_video("test.mp4")
+
+        Options for start_recording: framerate (default 30),
+        codec (libx264, libx265, libvpx-vp9), quality (high/medium/low).
+        Recording stops automatically when the driver is closed.
       HELP
       exit 0
     end
@@ -752,6 +814,21 @@ module TUITD
 
         assert_snapshot(driver, "main", ignore_rows: [5])
             Skip volatile rows with ignore_rows:.
+
+        Video Recording
+        ---------------
+
+        assert_record_start(driver, "test.mp4", framerate: 30, codec: "libx264")
+            Start recording the TUI session as a video (requires ffmpeg).
+
+        assert_record_stop(driver)
+            Stop recording and finalize the video file.
+
+        assert_recording(driver)
+            Verify that recording is currently active.
+
+        refute_recording(driver)
+            Verify that recording is NOT active.
       HELP
       exit 0
     end

data/lib/tui_td/configuration.rb

@@ -9,10 +9,13 @@ module TUITD
   #   end
   #
   class Configuration
-    attr_accessor :snapshot_dir
+    attr_accessor :snapshot_dir, :ffmpeg_path, :record_default_fps, :record_default_codec
 
     def initialize
       @snapshot_dir = nil
+      @ffmpeg_path = nil
+      @record_default_fps = 30
+      @record_default_codec = "libx264"
     end
 
     # Check if UPDATE_SNAPSHOTS env var is set to update mode.

data/lib/tui_td/driver.rb

@@ -224,8 +224,36 @@ module TUITD
       TUITD::State.new(state_data)
     end
 
+    # Start video recording (requires ffmpeg).
+    # Options: framerate (default 30), codec (default "libx264"), quality ("high"/"medium"/"low").
+    def start_recording(path, framerate: 30, codec: "libx264", quality: "high")
+      raise Error, "Recording already in progress" if recording?
+
+      require_relative "video_recorder"
+      @recorder = VideoRecorder.new(path, driver: self, framerate: framerate,
+                                          codec: codec, quality: quality,)
+      @recorder.start
+      path
+    end
+
+    # Stop video recording and finalize the video file.
+    # Returns the output path, or nil if not recording.
+    def stop_recording
+      return nil unless @recorder
+
+      path = @recorder.stop
+      @recorder = nil
+      path
+    end
+
+    # Is video recording currently active?
+    def recording?
+      @recorder&.recording? || false
+    end
+
     # Close the driver and clean up
     def close
+      stop_recording
       _stop_reader_thread
 
       # Kill the process if still running

data/lib/tui_td/matchers.rb

@@ -134,6 +134,37 @@ module TUITD
       end
     end
 
+    # Video recording matchers — work on Driver instances
+
+    RSpec::Matchers.define :be_recording do
+      match do |driver|
+        @actual = driver.recording?
+        @actual
+      end
+
+      description { "be recording video" }
+      failure_message do |_driver|
+        "expected driver to be recording, but it is not"
+      end
+      failure_message_when_negated do |_driver|
+        "expected driver NOT to be recording, but it is"
+      end
+    end
+
+    RSpec::Matchers.define :have_recorded_video do |path|
+      match do |_actual|
+        File.exist?(File.expand_path(path)) && File.size(File.expand_path(path)).positive?
+      end
+
+      description { "have recorded video at #{path}" }
+      failure_message do |_actual|
+        "expected video file to exist at #{path}"
+      end
+      failure_message_when_negated do |_actual|
+        "expected video file NOT to exist at #{path}"
+      end
+    end
+
     # Selector-based matchers — work with both State and Driver (auto-wait)
 
     RSpec::Matchers.define :have_button do |expected|

data/lib/tui_td/mcp/server.rb

@@ -424,6 +424,52 @@ module TUITD
                   required: ["name"],
                 },
               },
+              {
+                name: "tui_record_start",
+                description: "Start recording the current TUI session as a video file (requires ffmpeg). Call before interacting with the TUI. Frames are captured via the screenshot pipeline and encoded incrementally.",
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    path: {
+                      type: "string",
+                      description: "Output file path for the video (e.g., /tmp/session.mp4). Required.",
+                    },
+                    framerate: {
+                      type: "integer",
+                      description: "Frames per second (default: 30).",
+                      default: 30,
+                    },
+                    codec: {
+                      type: "string",
+                      description: "Video codec: libx264, libx265, libvpx-vp9 (default: libx264).",
+                      default: "libx264",
+                    },
+                    quality: {
+                      type: "string",
+                      enum: %w[high medium low],
+                      description: "Quality preset: high (best), medium, low (smaller files). Default: high.",
+                      default: "high",
+                    },
+                  },
+                  required: ["path"],
+                },
+              },
+              {
+                name: "tui_record_stop",
+                description: "Stop video recording and finalize the video file. Returns the output path.",
+                inputSchema: {
+                  type: "object",
+                  properties: {},
+                },
+              },
+              {
+                name: "tui_record_status",
+                description: "Check whether video recording is currently active.",
+                inputSchema: {
+                  type: "object",
+                  properties: {},
+                },
+              },
               {
                 name: "tui_close",
                 description: "Close the TUI application and clean up the PTY session. Call this when finished.",
@@ -461,6 +507,9 @@ module TUITD
                  when "tui_annotate_element" then call_tui_annotate_element(args)
                  when "tui_save_snapshot" then call_tui_save_snapshot(args)
                  when "tui_assert_snapshot" then call_tui_assert_snapshot(args)
+                 when "tui_record_start" then call_tui_record_start(args)
+                 when "tui_record_stop" then call_tui_record_stop
+                 when "tui_record_status" then call_tui_record_status
                  when "tui_close" then call_tui_close
                  else
                    return error_response(id, -32_602, "Unknown tool: #{tool_name}")
@@ -783,6 +832,35 @@ module TUITD
         end
       end
 
+      def call_tui_record_start(args)
+        ensure_driver!
+        path = args["path"] or return "ERROR: 'path' argument is required"
+        framerate = args["framerate"] || 30
+        codec = args["codec"] || "libx264"
+        quality = args["quality"] || "high"
+
+        safe = safe_path(path, ext: "mp4")
+        @driver.start_recording(safe, framerate: framerate, codec: codec, quality: quality)
+        "OK: Recording started to #{safe} (#{framerate} fps, #{codec})"
+      end
+
+      def call_tui_record_stop
+        ensure_driver!
+        return "No recording in progress" unless @driver.recording?
+
+        path = @driver.stop_recording
+        "OK: Recording saved to #{path}"
+      end
+
+      def call_tui_record_status
+        ensure_driver!
+        if @driver.recording?
+          "Recording is active"
+        else
+          "Not recording"
+        end
+      end
+
       def call_tui_close
         @driver&.close
         @driver = nil

data/lib/tui_td/minitest/assertions.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
+# rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists, Metrics/ModuleLength
 
 require "minitest"
 
@@ -234,6 +234,48 @@ module TUITD
         assert(result, msg)
       end
 
+      # --- Video Recording ---
+
+      # Start recording the TUI session as a video (requires ffmpeg).
+      # +actual+ must be a Driver.
+      def assert_record_start(actual, path, framerate: 30, codec: "libx264", quality: "high")
+        unless actual.respond_to?(:start_recording)
+          raise ArgumentError, "assert_record_start requires a Driver, got #{actual.class}"
+        end
+
+        result = actual.start_recording(path, framerate: framerate, codec: codec, quality: quality)
+        assert(result, "Recording failed to start")
+      end
+
+      # Stop video recording and finalize the video file.
+      # +actual+ must be a Driver.
+      def assert_record_stop(actual)
+        unless actual.respond_to?(:stop_recording)
+          raise ArgumentError, "assert_record_stop requires a Driver, got #{actual.class}"
+        end
+
+        path = actual.stop_recording
+        assert(path, "No recording in progress")
+      end
+
+      # Verify that recording is currently active.
+      def assert_recording(actual)
+        unless actual.respond_to?(:recording?)
+          raise ArgumentError, "assert_recording requires a Driver, got #{actual.class}"
+        end
+
+        assert(actual.recording?, "Expected recording to be active")
+      end
+
+      # Verify that recording is NOT active.
+      def refute_recording(actual)
+        unless actual.respond_to?(:recording?)
+          raise ArgumentError, "refute_recording requires a Driver, got #{actual.class}"
+        end
+
+        refute(actual.recording?, "Expected recording NOT to be active")
+      end
+
       # --- Snapshot ---
 
       def assert_snapshot(actual, name, type: :text, wait: false, region: nil, ignore_rows: nil)
@@ -260,4 +302,4 @@ module TUITD
     end
   end
 end
-# rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
+# rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists, Metrics/ModuleLength

data/lib/tui_td/screenshot.rb

@@ -215,6 +215,19 @@ module TUITD
     end
 
     def render(output_path)
+      image = build_image
+      image.save(output_path)
+      output_path
+    end
+
+    # Return the rendered PNG as a binary string (for in-memory use, e.g. video recording).
+    def to_blob
+      build_image.to_blob
+    end
+
+    private
+
+    def build_image
       width = @cols * CELL_W
       height = @rows * CELL_H
       image = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::BLACK)
@@ -230,13 +243,9 @@ module TUITD
       end
 
       draw_cursor(image)
-
-      image.save(output_path)
-      output_path
+      image
     end
 
-    private
-
     def render_cell(image, ri, ci, cell)
       char = cell[:char] || cell["char"] || " "
       fg = cell[:fg] || cell["fg"] || "default"

data/lib/tui_td/test_runner.rb

@@ -227,7 +227,37 @@ module TUITD
                     Result.new(step: action, passed: result.passed?, message: msg)
                   end
 
+                when "start_recording"
+                  ensure_driver!(driver)
+                  framerate = step[:framerate] || 30
+                  codec = step[:codec] || "libx264"
+                  path = safe_output_path(value.to_s, "mp4")
+                  driver.start_recording(path, framerate: framerate, codec: codec)
+                  Result.new(step: action, passed: true, message: "Recording started: #{path}")
+
+                when "stop_recording"
+                  ensure_driver!(driver)
+                  if driver.recording?
+                    path = driver.stop_recording
+                    Result.new(step: action, passed: true, message: "Recording saved: #{path}")
+                  else
+                    Result.new(step: action, passed: false, message: "No recording in progress")
+                  end
+
+                when "assert_recording"
+                  ensure_driver!(driver)
+                  expected = value == true || value.nil? # true/nil → assert active; false → assert NOT active
+                  is_recording = driver.recording?
+                  if is_recording == expected
+                    state = expected ? "is active" : "is NOT active"
+                    Result.new(step: action, passed: true, message: "Recording #{state} (as expected)")
+                  else
+                    state = is_recording ? "IS active (expected not)" : "is NOT active (expected active)"
+                    Result.new(step: action, passed: false, message: "Recording #{state}")
+                  end
+
                 when "close"
+                  driver&.stop_recording if driver&.recording?
                   driver&.close
                   driver = nil
                   Result.new(step: action, passed: true, message: "Closed")

data/lib/tui_td/version.rb

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

data/lib/tui_td/video_recorder.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/CyclomaticComplexity, Naming/PredicateMethod
+
+require "English"
+
+module TUITD
+  # Records TUI sessions as video using ffmpeg.
+  #
+  # Frames are captured via the existing Screenshot pipeline and piped
+  # directly to ffmpeg's stdin as PNG images — no temporary frame files.
+  #
+  # Usage:
+  #   recorder = VideoRecorder.new("session.mp4", driver: driver, framerate: 30)
+  #   recorder.start
+  #   # ... interact with TUI ...
+  #   recorder.stop  # => "session.mp4"
+  #
+  class VideoRecorder
+    QUALITY_CRF = {
+      "high" => 18,
+      "medium" => 23,
+      "low" => 28,
+    }.freeze
+
+    DEFAULT_QUALITY = "high"
+    DEFAULT_FRAMERATE = 30
+    DEFAULT_CODEC = "libx264"
+
+    attr_reader :output_path, :framerate, :codec, :quality
+
+    def initialize(output_path, driver:, framerate: DEFAULT_FRAMERATE,
+                   codec: DEFAULT_CODEC, quality: DEFAULT_QUALITY)
+      raise Error, "ffmpeg not found. Install ffmpeg to use video recording." unless self.class.available?
+
+      @output_path = File.expand_path(output_path)
+      @driver = driver
+      @framerate = framerate
+      @codec = codec
+      @quality = quality
+      @ffmpeg_io = nil
+      @capture_thread = nil
+      @running = false
+      @mutex = Mutex.new
+      @frame_interval = 1.0 / framerate
+    end
+
+    # Check whether ffmpeg is available on the system.
+    def self.available?
+      system("which ffmpeg > /dev/null 2>&1")
+    end
+
+    # Start recording. Spawns ffmpeg and begins frame capture.
+    def start
+      @mutex.synchronize do
+        raise Error, "Recording already in progress" if @running
+
+        @ffmpeg_io = IO.popen(ffmpeg_command, "w", err: File::NULL)
+        @running = true
+      end
+
+      @capture_thread = Thread.new { capture_loop }
+      true
+    end
+
+    # Stop recording. Waits for ffmpeg to finalize and returns the output path.
+    def stop
+      @mutex.synchronize do
+        return nil unless @running
+
+        @running = false
+      end
+
+      @capture_thread&.join(5)
+      begin
+        @capture_thread&.kill
+      rescue StandardError
+        nil
+      end
+      @capture_thread = nil
+
+      begin
+        @ffmpeg_io&.close_write
+        @ffmpeg_io&.close
+      rescue StandardError
+        nil
+      end
+      @ffmpeg_io = nil
+
+      @output_path
+    end
+
+    # Is recording currently active?
+    def recording?
+      @mutex.synchronize { @running }
+    end
+
+    private
+
+    def ffmpeg_command
+      crf = QUALITY_CRF.fetch(@quality, QUALITY_CRF[DEFAULT_QUALITY])
+      ffmpeg_bin = TUITD.configuration.ffmpeg_path || "ffmpeg"
+
+      [
+        ffmpeg_bin,
+        "-y",                # overwrite output
+        "-f", "image2pipe",  # input format: pipe of images
+        "-vcodec", "png",    # input codec
+        "-r", @framerate.to_s, # input framerate
+        "-i", "-",           # read from stdin
+        "-vcodec", @codec,   # output codec
+        "-crf", crf.to_s,    # quality (lower = better)
+        "-pix_fmt", "yuv420p", # wide compatibility
+        @output_path,
+      ]
+    end
+
+    def capture_loop
+      last_frame = nil
+
+      while recording?
+        loop_start = monotonic
+
+        begin
+          state = @driver.state_data
+          screenshot = Screenshot.new(state)
+          png_blob = screenshot.to_blob
+
+          # Only write frames that differ from the last one (delta compression)
+          if last_frame.nil? || png_blob != last_frame
+            @ffmpeg_io&.write(png_blob)
+            @ffmpeg_io&.flush
+            last_frame = png_blob
+          end
+        rescue IOError, Errno::EPIPE
+          break # ffmpeg pipe closed
+        rescue StandardError => e
+          warn "[tui-td VideoRecorder] Frame capture error: #{e.class}: #{e.message}"
+        end
+
+        elapsed = monotonic - loop_start
+        sleep_time = @frame_interval - elapsed
+        sleep(sleep_time) if sleep_time.positive?
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end
+
+# rubocop:enable Metrics/CyclomaticComplexity, Naming/PredicateMethod

data/lib/tui_td.rb

@@ -16,10 +16,10 @@ require_relative "tui_td/state"
 require_relative "tui_td/configuration"
 require_relative "tui_td/snapshot"
 require_relative "tui_td/screenshot"
+require_relative "tui_td/video_recorder"
 require_relative "tui_td/html_renderer"
 require_relative "tui_td/test_runner"
 require_relative "tui_td/selector"
-require_relative "tui_td/minitest/assertions"
 require_relative "tui_td/mcp/server"
 require_relative "tui_td/cli"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.2.19
+  version: 0.2.21
 platform: ruby
 authors:
 - Haluk Durmus
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.3
+        version: 0.1.4
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.15'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -182,6 +196,7 @@ files:
 - lib/tui_td/test_runner.rb
 - lib/tui_td/unifont_glyphs.rb
 - lib/tui_td/version.rb
+- lib/tui_td/video_recorder.rb
 homepage: https://github.com/vurte/tui-td
 licenses:
 - MIT