test-recorder 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2df7b7454c1776d950afaadc9fcefdab037f2638a0a0f05ba7251ef08131428
-  data.tar.gz: 97e45933561090c772aef6a26849075626c7d8e9766d0e25c60a642841a38f36
+  metadata.gz: 10ed1ca4c5868a640ac26f54969374fabb4d298f1e25a63fbf898b147410c97a
+  data.tar.gz: 36c717726cf643f138140f04d1c6068fc59f04a93d9d3740bc219f4c6fabc6eb
 SHA512:
-  metadata.gz: 2ced41859d336565547e55de99b4574952f175bc3acb7ce6a6231c07ce32bab27483689f6a9c3967950d4da80145ea2002a0abe2ba3b6905c56fa9728902e004
-  data.tar.gz: 1657c90f69bcf393bb7e4905fde1a9e6afc74b7c5e864521a72bee0f4d3f97db9b1ceba28e466d321e7122ce2545548431ccd593a576e53f2b7c3c45d34214da
+  metadata.gz: 0e227207116c5b6bef3acd692d755499117665b1e774cefdaf8e9f2722dc62865997f7bc2246e64ec54b6b8e2f18992cadd8b49b510ff11702a6d37b0a5b1fe4
+  data.tar.gz: 7895ee63692f785d0633e0b35ea2d4d104a318d5bc6f4a27501c4294764367c77c9902d912cd8635976c9f862e5950819fb37f46a7beea09f336fee910eb6989

data/.github/workflows/ci.yml

@@ -18,6 +18,13 @@ jobs:
     strategy:
       matrix:
         ruby: [ '4.0', '3.4', '3.3' ]
+        chrome: [ 'stable' ]
+        include:
+          # The last version without Page.startScreenRecording, to cover the screencast fallback.
+          - ruby: '4.0'
+            chrome: '152'
+
+    name: build (ruby ${{ matrix.ruby }}, chrome ${{ matrix.chrome }})
 
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -43,5 +50,13 @@ jobs:
       run: |
         chmod +x "$HOME/.local/bin/ffmpeg"
         echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+    - name: Use Chrome ${{ matrix.chrome }}
+      if: matrix.chrome != 'stable'
+      run: |
+        install() { npx -y @puppeteer/browsers install "$1@${{ matrix.chrome }}" --path "$RUNNER_TEMP/browsers" | tail -n 1 | cut -d ' ' -f 2; }
+        echo "CHROME_BIN=$(install chrome)" >> "$GITHUB_ENV"
+        echo "SE_CHROMEDRIVER=$(install chromedriver)" >> "$GITHUB_ENV"
+        # Chrome for Testing is not installed under /opt, so AppArmor blocks its sandbox.
+        sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
     - name: Run test
       run: bundle exec rake

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+## 0.5.0 - 2026-10-06
+
+* Record with `Page.startScreenRecording` on Chrome 153+. Chrome encodes the video itself as an `.mp4` file, so FFmpeg is no longer needed. Older Chrome versions fall back to the screencast (`.webm`, requires FFmpeg). `TestRecorder.frame_rate` (default: 25) sets the frame rate, and `jpeg_quality` and `every_nth_frame` now only apply to the screencast fallback
+
 ## 0.4.0 - 2026-08-30
 
 * Record each frame with its own timestamp so that videos play back at the same speed as the test

data/README.md

@@ -9,7 +9,9 @@ This gem was inspired by [Record video feature of Playwright](https://playwright
 
 ## Requirements
 
-This gem depends on FFmpeg. Please install that package.
+Chrome 153 or later records the video by itself (using `Page.startScreenRecording`), so nothing else is needed.
+
+With older Chrome versions, this gem falls back to the screencast, and depends on FFmpeg for that. Please install that package.
 
 On Debian/Ubuntu:
 
@@ -17,6 +19,13 @@ On Debian/Ubuntu:
 sudo apt-get install ffmpeg
 ```
 
+## Output format
+
+The videos are generated in `tmp/videos` directory.
+
+* Chrome 153 or later: `.mp4` (AV1)
+* Older Chrome versions: `.webm` (VP8)
+
 ## Supported libraries
 
 Rails system tests and RSpec(System Spec and Feature Spec).
@@ -98,11 +107,17 @@ end
 
 ### Configuration
 
-You can change the recording quality and the max width/height (in pixels).
+You can change the max width/height (in pixels) and the frame rate. These apply to both recording methods.
 
 ```ruby
-TestRecorder.jpeg_quality = 80    # default: 60
 TestRecorder.max_dimension = 1280 # default: 1000
+TestRecorder.frame_rate = 30      # default: 25
+```
+
+The following settings only apply to the screencast fallback used with Chrome versions older than 153. They are ignored when Chrome records the screen by itself.
+
+```ruby
+TestRecorder.jpeg_quality = 80 # default: 60
 ```
 
 You can also record only every Nth frame. This lowers the recording overhead

data/lib/test_recorder/cdp_recorder.rb

@@ -1,72 +1,31 @@
-require "base64"
 require "fileutils"
-require "tempfile"
+require "selenium-webdriver"
 
-require "test_recorder/frame_writer"
+require "test_recorder/screen_recording"
+require "test_recorder/screencast"
 
 module TestRecorder
   class CdpRecorder
-    FFMPEG_ENCODE_OPTIONS = %w[-y -an -r 25 -c:v vp8 -qmin 0 -qmax 50 -crf 8 -deadline realtime -speed 8 -b:v 1M -threads 1].freeze
-
-    # ffmpeg's -t treats the given duration as an exclusive cutoff, dropping the very frame that
-    # marks the video's real length if it lands exactly on it. This nudges -t just past that frame
-    # so it is kept, without adding a duration long enough to be noticeable.
-    FFMPEG_DURATION_SLACK_S = 0.01
-
-    Record = Struct.new(:page, :io, :last_metadata_time, :last_metadata_received_at)
-
     class << self
-      def record(devtools)
-        records[devtools] ||= begin
-          page = devtools.page
-          page.enable
-
-          record = Record.new(page)
-          page.on(:screencast_frame) do |event|
-            write_frame(record, event)
-            record.page.screencast_frame_ack(session_id: event["sessionId"])
-          end
-          record
-        end
+      def screen_recording_supported?(browser)
+        support.fetch(browser) { support[browser] = probe_screen_recording(browser) }
       end
 
       private
 
-      def write_frame(record, event)
-        record.io&.write(Base64.decode64(event["data"]), frame_time(record, event))
-      rescue IOError
-        # A frame can still arrive after the recording was stopped and the file was closed.
-      rescue => e
-        warn "[TestRecorder] Failed to write a screencast frame: #{e.class}: #{e.message}"
-      end
-
-      # `metadata.timestamp` is the wall clock time of the frame swap, in seconds, on the browser's
-      # clock. The protocol marks it optional, so when it is missing, estimate it from the last
-      # frame that did carry one plus how much monotonic time has passed since. Falling back to
-      # this process's own wall clock instead would silently distort pacing whenever the browser
-      # runs on a different host than the driver, since the two wall clocks are not guaranteed to
-      # agree.
-      def frame_time(record, event)
-        metadata = event["metadata"]
-        timestamp = metadata && metadata["timestamp"]
-
-        if timestamp
-          record.last_metadata_time = timestamp
-          record.last_metadata_received_at = monotonic_time
-          timestamp
-        elsif record.last_metadata_time
-          record.last_metadata_time + (monotonic_time - record.last_metadata_received_at)
-        else
-          Time.now.to_f
-        end
+      # Stopping when nothing is being recorded tells whether the command exists without starting
+      # anything: Chrome 153+ answers "No active screen recording", older versions do not know it.
+      def probe_screen_recording(browser)
+        browser.execute_cdp("Page.stopScreenRecording")
+        true
+      rescue Selenium::WebDriver::Error::UnknownCommandError
+        false
+      rescue Selenium::WebDriver::Error::WebDriverError
+        true
       end
 
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-
-      def records
-        @records ||= {}.compare_by_identity
+      def support
+        @support ||= {}.compare_by_identity
       end
     end
 
@@ -80,63 +39,41 @@ module TestRecorder
       @started = enabled
       return unless @started
 
-      @tmp_video = Tempfile.new(["testrecorder", ".mkv"])
-      @tmp_video.binmode
-
-      @record = self.class.record(page.driver.browser.devtools)
-      @frame_writer = FrameWriter.new(@tmp_video)
-      @record.io = @frame_writer
-
-      @record.page.start_screencast(format: "jpeg", quality: TestRecorder.jpeg_quality, max_width: TestRecorder.max_dimension, max_height: TestRecorder.max_dimension, every_nth_frame: TestRecorder.every_nth_frame)
+      browser = page.driver.browser
+      @recording = if self.class.screen_recording_supported?(browser)
+        ScreenRecording.new(browser)
+      else
+        Screencast.new(browser)
+      end
+      @recording.start
+    rescue => e
+      warn "[TestRecorder] Failed to start the recording: #{e.class}: #{e.message}"
+      @started = false
     end
 
     def stop_and_discard
       return unless @started
 
-      @record.io = nil
-      @record.page.stop_screencast
-      @tmp_video.close!
+      @recording.stop_and_discard
+    rescue => e
+      warn "[TestRecorder] Failed to stop the recording: #{e.class}: #{e.message}"
     end
 
-    def stop_and_save(filename)
+    # `name` is the file name without an extension, since the format depends on how it was recorded.
+    # Returns the path of the video, or "" when nothing was saved.
+    def stop_and_save(name)
       return "" unless @started
 
-      @record.io = nil
-      @record.page.stop_screencast
-      @frame_writer.finish
-      @tmp_video.flush
-
-      # Chrome sends a frame as soon as the screencast starts, so a test that fails
-      # before it draws anything still leaves behind the one frame of the blank page
-      # it started on.
-      if @frame_writer.frame_count < 2
-        warn "[TestRecorder] The screencast captured no page updates, so no video was saved."
-        @tmp_video.close!
-        return ""
-      end
-
       video_dir = ::Rails.root.join("tmp", "videos")
       FileUtils.mkdir_p(video_dir)
-      video_path = video_dir.join(filename).to_s
-
-      # Each frame carries its own timestamp in the Matroska stream, so ffmpeg knows how long to
-      # hold it and duplicates frames to reach the constant output frame rate on its own. Without a
-      # known end, though, ffmpeg pads however long it likes past the last real timestamp, so -t
-      # caps the output at the video's real duration explicitly.
-      duration = @frame_writer.duration + FFMPEG_DURATION_SLACK_S
-      result = system("ffmpeg", "-loglevel", "error", "-f", "matroska", "-i", @tmp_video.path, "-t", duration.to_s, *FFMPEG_ENCODE_OPTIONS, video_path)
-
-      @tmp_video.close!
-
-      if result.nil?
-        warn "[TestRecorder] Failed to execute ffmpeg. Please make sure that FFmpeg is installed."
-        return ""
-      elsif !result
-        warn "[TestRecorder] ffmpeg failed to encode #{video_path}."
-        return ""
-      end
-
-      video_path
+      video_path = video_dir.join("#{name}#{@recording.extension}").to_s
+
+      @recording.stop_and_save(video_path) ? video_path : ""
+    rescue => e
+      # The browser can be gone by now (a crash, a closed window). The test's own failure is what
+      # matters, so this must not replace it with an error from here.
+      warn "[TestRecorder] Failed to save the recording: #{e.class}: #{e.message}"
+      ""
     end
   end
 end

data/lib/test_recorder/rails/setup_and_teardown.rb

@@ -11,7 +11,7 @@ module TestRecorder
 
       def before_teardown
         if failures.any? { |failure| !failure.is_a?(Minitest::Skip) }
-          video_path = @cdp_recorder.stop_and_save("failures_#{TestRecorder.sanitize_filename(self.name)}.webm")
+          video_path = @cdp_recorder.stop_and_save("failures_#{TestRecorder.sanitize_filename(self.name)}")
           puts "[Video]: #{video_path}" if File.exist?(video_path)
         else
           @cdp_recorder.stop_and_discard

data/lib/test_recorder/rspec.rb

@@ -11,7 +11,7 @@ module TestRecorder
         if passed?(example)
           cdp_recorder.stop_and_discard
         else
-          video_path = cdp_recorder.stop_and_save("failures_#{method_name(example)}.webm").to_s
+          video_path = cdp_recorder.stop_and_save("failures_#{method_name(example)}").to_s
           if File.exist?(video_path)
             example.metadata[:extra_failure_lines] = [example.metadata[:extra_failure_lines], "[Video]: #{video_path}"].flatten
           end

data/lib/test_recorder/screen_recording.rb

@@ -0,0 +1,93 @@
+require "base64"
+
+module TestRecorder
+  # Records with `Page.startScreenRecording` (Chrome 153+). Chrome captures the page at a fixed
+  # frame rate and encodes an MP4 itself, so nothing needs to be encoded on this side. The commands
+  # are sent with `execute_cdp`, which does not need the selenium-devtools gem.
+  class ScreenRecording
+    EXTENSION = ".mp4".freeze
+
+    # The size of one `IO.read`.
+    READ_SIZE = 1 << 20
+
+    # What a new Chrome session shows before the test visits anything ("data:," is what
+    # chromedriver opens with).
+    BLANK_URLS = ["data:,", "about:blank"].freeze
+
+    def initialize(browser)
+      @browser = browser
+    end
+
+    def extension
+      EXTENSION
+    end
+
+    def start
+      @stream = @browser.execute_cdp("Page.startScreenRecording", maxWidth: TestRecorder.max_dimension, maxHeight: TestRecorder.max_dimension, frameRate: TestRecorder.frame_rate)["stream"]
+    end
+
+    def stop_and_discard
+      stop
+    ensure
+      close_stream
+    end
+
+    # Returns true when the video was written to `video_path`.
+    def stop_and_save(video_path)
+      # Chrome captures at a fixed frame rate whether or not anything is drawn, so a test that
+      # fails before it visits a page would still leave behind a video of the blank page it
+      # started on.
+      if blank_page?
+        stop
+        warn "[TestRecorder] The test failed before any page was loaded, so no video was saved."
+        return false
+      end
+
+      stop
+      read_stream_into(video_path)
+
+      if File.zero?(video_path)
+        warn "[TestRecorder] The screen recording was empty, so no video was saved."
+        File.delete(video_path)
+        return false
+      end
+
+      true
+    rescue
+      File.delete(video_path) if File.exist?(video_path)
+      raise
+    ensure
+      close_stream
+    end
+
+    private
+
+    def blank_page?
+      BLANK_URLS.include?(@browser.current_url)
+    rescue
+      false
+    end
+
+    # The stream stays readable after this, so it has to be closed even if nobody reads it.
+    def stop
+      @browser.execute_cdp("Page.stopScreenRecording")
+    end
+
+    def read_stream_into(video_path)
+      File.open(video_path, "wb") do |file|
+        loop do
+          chunk = @browser.execute_cdp("IO.read", handle: @stream, size: READ_SIZE)
+          file.write(chunk["base64Encoded"] ? Base64.decode64(chunk["data"]) : chunk["data"])
+          break if chunk["eof"]
+        end
+      end
+    end
+
+    # Runs on the way out of a failed stop or read too, so its own error must not hide that one.
+    def close_stream
+      @browser.execute_cdp("IO.close", handle: @stream)
+    rescue => e
+      warn "[TestRecorder] Failed to close the screen recording stream: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/test_recorder/screencast.rb

@@ -0,0 +1,138 @@
+require "base64"
+require "tempfile"
+
+require "test_recorder/frame_writer"
+
+module TestRecorder
+  # Records with `Page.startScreencast`, which sends a JPEG for every repaint, and has ffmpeg
+  # encode them into a video afterwards. This is the fallback for Chrome versions without
+  # `Page.startScreenRecording`.
+  class Screencast
+    EXTENSION = ".webm".freeze
+
+    FFMPEG_ENCODE_OPTIONS = %w[-y -an -c:v vp8 -qmin 0 -qmax 50 -crf 8 -deadline realtime -speed 8 -b:v 1M -threads 1].freeze
+
+    # ffmpeg's -t treats the given duration as an exclusive cutoff, dropping the very frame that
+    # marks the video's real length if it lands exactly on it. This nudges -t just past that frame
+    # so it is kept, without adding a duration long enough to be noticeable.
+    FFMPEG_DURATION_SLACK_S = 0.01
+
+    Record = Struct.new(:page, :io, :last_metadata_time, :last_metadata_received_at)
+
+    class << self
+      def record(devtools)
+        records[devtools] ||= begin
+          page = devtools.page
+          page.enable
+
+          record = Record.new(page)
+          page.on(:screencast_frame) do |event|
+            write_frame(record, event)
+            record.page.screencast_frame_ack(session_id: event["sessionId"])
+          end
+          record
+        end
+      end
+
+      private
+
+      def write_frame(record, event)
+        record.io&.write(Base64.decode64(event["data"]), frame_time(record, event))
+      rescue IOError
+        # A frame can still arrive after the recording was stopped and the file was closed.
+      rescue => e
+        warn "[TestRecorder] Failed to write a screencast frame: #{e.class}: #{e.message}"
+      end
+
+      # `metadata.timestamp` is the wall clock time of the frame swap, in seconds, on the browser's
+      # clock. The protocol marks it optional, so when it is missing, estimate it from the last
+      # frame that did carry one plus how much monotonic time has passed since. Falling back to
+      # this process's own wall clock instead would silently distort pacing whenever the browser
+      # runs on a different host than the driver, since the two wall clocks are not guaranteed to
+      # agree.
+      def frame_time(record, event)
+        metadata = event["metadata"]
+        timestamp = metadata && metadata["timestamp"]
+
+        if timestamp
+          record.last_metadata_time = timestamp
+          record.last_metadata_received_at = monotonic_time
+          timestamp
+        elsif record.last_metadata_time
+          record.last_metadata_time + (monotonic_time - record.last_metadata_received_at)
+        else
+          Time.now.to_f
+        end
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def records
+        @records ||= {}.compare_by_identity
+      end
+    end
+
+    def initialize(browser)
+      @browser = browser
+    end
+
+    def extension
+      EXTENSION
+    end
+
+    def start
+      @tmp_video = Tempfile.new(["testrecorder", ".mkv"])
+      @tmp_video.binmode
+
+      @record = self.class.record(@browser.devtools)
+      @frame_writer = FrameWriter.new(@tmp_video)
+      @record.io = @frame_writer
+
+      @record.page.start_screencast(format: "jpeg", quality: TestRecorder.jpeg_quality, max_width: TestRecorder.max_dimension, max_height: TestRecorder.max_dimension, every_nth_frame: TestRecorder.every_nth_frame)
+    end
+
+    def stop_and_discard
+      @record.io = nil
+      @record.page.stop_screencast
+      @tmp_video.close!
+    end
+
+    # Returns true when the video was written to `video_path`.
+    def stop_and_save(video_path)
+      @record.io = nil
+      @record.page.stop_screencast
+      @frame_writer.finish
+      @tmp_video.flush
+
+      # Chrome sends a frame as soon as the screencast starts, so a test that fails
+      # before it draws anything still leaves behind the one frame of the blank page
+      # it started on.
+      if @frame_writer.frame_count < 2
+        warn "[TestRecorder] The screencast captured no page updates, so no video was saved."
+        @tmp_video.close!
+        return false
+      end
+
+      # Each frame carries its own timestamp in the Matroska stream, so ffmpeg knows how long to
+      # hold it and duplicates frames to reach the constant output frame rate on its own. Without a
+      # known end, though, ffmpeg pads however long it likes past the last real timestamp, so -t
+      # caps the output at the video's real duration explicitly.
+      duration = @frame_writer.duration + FFMPEG_DURATION_SLACK_S
+      result = system("ffmpeg", "-loglevel", "error", "-f", "matroska", "-i", @tmp_video.path, "-t", duration.to_s, "-r", TestRecorder.frame_rate.to_s, *FFMPEG_ENCODE_OPTIONS, video_path)
+
+      @tmp_video.close!
+
+      if result.nil?
+        warn "[TestRecorder] Failed to execute ffmpeg. Please make sure that FFmpeg is installed."
+        return false
+      elsif !result
+        warn "[TestRecorder] ffmpeg failed to encode #{video_path}."
+        return false
+      end
+
+      true
+    end
+  end
+end

data/lib/test_recorder/version.rb

@@ -1,3 +1,3 @@
 module TestRecorder
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/test_recorder.rb

@@ -4,11 +4,12 @@ module TestRecorder
   DEFAULT_JPEG_QUALITY = 60
   DEFAULT_MAX_DIMENSION = 1000
   DEFAULT_EVERY_NTH_FRAME = 1
+  DEFAULT_FRAME_RATE = 25
 
   CHARS_TO_TRANSLATE = ['/', '.', ':', ',', "'", '"', " "].freeze
 
   class << self
-    attr_writer :jpeg_quality, :max_dimension, :every_nth_frame
+    attr_writer :jpeg_quality, :max_dimension, :every_nth_frame, :frame_rate
 
     def enable!
       @enable = true
@@ -34,6 +35,10 @@ module TestRecorder
       defined?(@every_nth_frame) ? @every_nth_frame : DEFAULT_EVERY_NTH_FRAME
     end
 
+    def frame_rate
+      defined?(@frame_rate) ? @frame_rate : DEFAULT_FRAME_RATE
+    end
+
     def sanitize_filename(name)
       name.tr(CHARS_TO_TRANSLATE.join, "_")
     end

data/test-recorder.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test-recorder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yuji Yaginuma
@@ -90,6 +90,8 @@ files:
 - lib/test_recorder/rails/setup_and_teardown.rb
 - lib/test_recorder/rspec.rb
 - lib/test_recorder/rspec/example_wrapper.rb
+- lib/test_recorder/screen_recording.rb
+- lib/test_recorder/screencast.rb
 - lib/test_recorder/version.rb
 - test-recorder.gemspec
 homepage: http://github.com/y-yagi/test-recorder
@@ -97,6 +99,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: http://github.com/y-yagi/test-recorder
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib