test-recorder 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76a3cec00d302949375e3ad8d9c4c566f8c52cac703db8384b36505d2be47bb
-  data.tar.gz: 109b533201bcde42f210224cf1a01f5b0b795cb1dc5c737d83a80a0b232d67b3
+  metadata.gz: 10ed1ca4c5868a640ac26f54969374fabb4d298f1e25a63fbf898b147410c97a
+  data.tar.gz: 36c717726cf643f138140f04d1c6068fc59f04a93d9d3740bc219f4c6fabc6eb
 SHA512:
-  metadata.gz: 5b4ca4f5087cc0d32cb335f79fdface896ae918493958ff753f36207f93e44b80a0d1af11f9486c8a6cdcad9d2dd2974599cabfac1afaf158e85d51842d5f71c
-  data.tar.gz: 52a41a7cc4a35ee019892cea4c67f467bb0e7a9e7f391bba7bfca52a596bda057b2fb92f72c9dc20ef85e700b52985dd049a2bfed6baac874cb3bad8479eb19d
+  metadata.gz: 0e227207116c5b6bef3acd692d755499117665b1e774cefdaf8e9f2722dc62865997f7bc2246e64ec54b6b8e2f18992cadd8b49b510ff11702a6d37b0a5b1fe4
+  data.tar.gz: 7895ee63692f785d0633e0b35ea2d4d104a318d5bc6f4a27501c4294764367c77c9902d912cd8635976c9f862e5950819fb37f46a7beea09f336fee910eb6989

data/.github/workflows/ci.yml

@@ -18,16 +18,23 @@ 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@v4
-    - uses: ruby/setup-ruby@v1
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+    - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
       with:
         ruby-version: ${{ matrix.ruby }}
         bundler-cache: true
     - name: Cache ffmpeg
       id: cache-ffmpeg
-      uses: actions/cache@v4
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
       with:
         path: ~/.local/bin/ffmpeg
         key: ffmpeg-${{ runner.os }}-${{ env.FFMPEG_BUILD }}
@@ -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/.github/workflows/push_gem.yml

@@ -19,15 +19,15 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@4d991eb9b905ef189e4c376166672c3f2f230481 # v2.11.0
+        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up Ruby
-        uses: ruby/setup-ruby@2e007403fc1ec238429ecaa57af6f22f019cc135 # v1.234.0
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
         with:
           bundler-cache: true
           ruby-version: ruby
 
-      - uses: rubygems/release-gem@9e85cb11501bebc2ae661c1500176316d3987059 # v1.1.0
+      - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## 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
+
 ## 0.3.0 - 2026-08-23
 
 * Reduce recording overhead

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/Rakefile

@@ -6,7 +6,7 @@ Rake::TestTask.new(:test) do |t|
   t.libs << "lib"
   t.verbose = true
   t.warning = true
-  t.test_files = ["test/integration_test.rb", "test/test_recorder_config_test.rb"]
+  t.test_files = ["test/integration_test.rb", "test/frame_writer_test.rb", "test/test_recorder_config_test.rb"]
 end
 
 task :default => :test

data/lib/test_recorder/cdp_recorder.rb

@@ -1,43 +1,31 @@
-require "base64"
 require "fileutils"
-require "tempfile"
+require "selenium-webdriver"
+
+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
-
-    Record = Struct.new(:page, :io, :frame_count)
-
     class << self
-      def record(devtools)
-        records[devtools] ||= begin
-          page = devtools.page
-          page.enable
-
-          record = Record.new(page, nil, 0)
-          page.on(:screencast_frame) do |event|
-            write_frame(record, event["data"])
-            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, data)
-        return if record.io.nil?
-
-        record.io.write(Base64.decode64(data))
-        record.frame_count += 1
-      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}"
+      # 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 records
-        @records ||= {}.compare_by_identity
+      def support
+        @support ||= {}.compare_by_identity
       end
     end
 
@@ -51,62 +39,41 @@ module TestRecorder
       @started = enabled
       return unless @started
 
-      @tmp_video = Tempfile.new(["testrecorder", ".mjpeg"])
-      @tmp_video.binmode
-
-      @record = self.class.record(page.driver.browser.devtools)
-      @record.io = @tmp_video
-      @record.frame_count = 0
-
-      @every_nth_frame = TestRecorder.every_nth_frame
-
-      @record.page.start_screencast(format: "jpeg", quality: TestRecorder.jpeg_quality, max_width: TestRecorder.max_dimension, max_height: TestRecorder.max_dimension, every_nth_frame: @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
-      @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 @record.frame_count < 2
-        @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
-
-      # Chrome captures at about 25 fps, but `every_nth_frame` makes it deliver only
-      # one out of every N frames. So the captured file holds 25 / N frames per second.
-      # Tell ffmpeg that input rate, otherwise it assumes 25 fps and the video plays
-      # N times faster than the actual test.
-      result = system("ffmpeg", "-loglevel", "error", "-f", "image2pipe", "-c:v", "mjpeg", "-framerate", "25/#{@every_nth_frame}", "-i", @tmp_video.path, *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/frame_writer.rb

@@ -0,0 +1,83 @@
+require "test_recorder/matroska_writer"
+
+module TestRecorder
+  class FrameWriter
+    # How long the last frame stays visible at the end of the video. A test usually fails some
+    # time after the last repaint, and that last screen is the one worth looking at.
+    MIN_LAST_FRAME_DURATION = 1.0
+    MAX_LAST_FRAME_DURATION = 5.0
+
+    def initialize(io)
+      @container = MatroskaWriter.new(io)
+      @first_frame_time = nil
+      @last_frame = nil
+      @last_write_at = nil
+      @last_timestamp_ms = 0
+      @duration = nil
+      @frame_count = 0
+      @finished = false
+      # CDP dispatches every screencast frame event on its own thread, and `finish` can run on the
+      # main thread while a frame is still in flight, so all access to the state above and to the
+      # container is serialized through this.
+      @mutex = Mutex.new
+    end
+
+    def empty?
+      @last_frame.nil?
+    end
+
+    # How many seconds the finished video should run for. ffmpeg does not reliably infer this from
+    # the container alone, so `stop_and_save` passes it to ffmpeg explicitly. Only meaningful after
+    # `finish` has run.
+    attr_reader :duration
+
+    # 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. Callers use this
+    # to tell that apart from a real recording.
+    attr_reader :frame_count
+
+    def write(frame, time)
+      @mutex.synchronize do
+        return if @finished
+
+        @first_frame_time ||= time
+        write_at(frame, time)
+        @last_frame = frame
+        @last_write_at = monotonic_time
+        @frame_count += 1
+      end
+    end
+
+    # Repeats the last frame at the end of the recording so that it stays on screen, and so that
+    # the video covers the time between the last repaint and the end of the test. That interval is
+    # measured with the monotonic clock, so a wall clock adjustment cannot stretch or shrink it.
+    def finish
+      @mutex.synchronize do
+        return if @finished
+
+        @finished = true
+        return if empty?
+
+        elapsed = (monotonic_time - @last_write_at).clamp(MIN_LAST_FRAME_DURATION, MAX_LAST_FRAME_DURATION)
+        write_ms(@last_frame, @last_timestamp_ms + (elapsed * 1000).round)
+        @duration = @last_timestamp_ms / 1000.0
+      end
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def write_at(frame, time)
+      write_ms(frame, ((time - @first_frame_time) * 1000).round)
+    end
+
+    def write_ms(frame, timestamp_ms)
+      timestamp_ms = [timestamp_ms, @last_timestamp_ms].max
+      @container.write_frame(frame, timestamp_ms)
+      @last_timestamp_ms = timestamp_ms
+    end
+  end
+end

data/lib/test_recorder/matroska_writer.rb

@@ -0,0 +1,177 @@
+module TestRecorder
+  # Writes a Matroska stream holding a single MJPEG video track, where every frame carries the
+  # time it was captured. Chrome emits a screencast frame only when the page repaints, so frames
+  # are not evenly spaced; keeping the real times lets ffmpeg reproduce the original pacing
+  # instead of assuming a fixed frame rate.
+  #
+  # Written against the specifications:
+  #   EBML     https://datatracker.ietf.org/doc/html/rfc8794
+  #   Matroska https://datatracker.ietf.org/doc/html/rfc9559
+  #   Codecs   https://datatracker.ietf.org/doc/html/draft-ietf-cellar-codec
+  #
+  # RFC 9559 updates RFC 8794, so read the two together: it makes 0x80 a legal EBML ID, which
+  # leaves 0xFF as the only reserved one. Codec IDs such as V_MJPEG are defined by neither, but by
+  # the codec document, which is still a draft.
+  #
+  # Only the elements those specifications require for this kind of stream are emitted. The stream
+  # is written as it is captured, so the sizes of the Segment and of each Cluster are not known
+  # when they start and are left unknown, which Matroska allows for those two elements alone.
+  class MatroskaWriter
+    # Element IDs, as defined by Matroska. The leading byte of an ID already encodes how many
+    # bytes the ID occupies, so an ID is written as the minimal big endian form of these numbers.
+    module Id
+      EBML = 0x1A45DFA3
+      EBML_VERSION = 0x4286
+      EBML_READ_VERSION = 0x42F7
+      EBML_MAX_ID_LENGTH = 0x42F2
+      EBML_MAX_SIZE_LENGTH = 0x42F3
+      DOC_TYPE = 0x4282
+      DOC_TYPE_VERSION = 0x4287
+      DOC_TYPE_READ_VERSION = 0x4285
+      SEGMENT = 0x18538067
+      INFO = 0x1549A966
+      TIMESTAMP_SCALE = 0x2AD7B1
+      MUXING_APP = 0x4D80
+      WRITING_APP = 0x5741
+      TRACKS = 0x1654AE6B
+      TRACK_ENTRY = 0xAE
+      TRACK_NUMBER = 0xD7
+      TRACK_UID = 0x73C5
+      TRACK_TYPE = 0x83
+      FLAG_LACING = 0x9C
+      CODEC_ID = 0x86
+      VIDEO = 0xE0
+      PIXEL_WIDTH = 0xB0
+      PIXEL_HEIGHT = 0xBA
+      CLUSTER = 0x1F43B675
+      TIMESTAMP = 0xE7
+      SIMPLE_BLOCK = 0xA3
+    end
+    private_constant :Id
+
+    # A size whose data bits are all ones means "unknown". One byte is enough to say that.
+    UNKNOWN_SIZE = [0xFF].pack("C")
+
+    # TimestampScale is given in nanoseconds per tick, so this makes every timestamp in the stream
+    # a number of milliseconds.
+    TIMESTAMP_SCALE_NS = 1_000_000
+
+    # A block states its time as a 16 bit signed offset from the timestamp of its cluster, so a
+    # cluster can only cover about 32 seconds. Matroska also recommends keeping clusters short,
+    # a few seconds at most.
+    MAX_CLUSTER_DURATION_MS = 5_000
+
+    TRACK_NUMBER = 1
+    TRACK_TYPE_VIDEO = 1
+    KEYFRAME = 0x80
+
+    def initialize(io)
+      @io = io
+      @cluster_timestamp_ms = nil
+
+      write_header
+    end
+
+    # Appends one JPEG, shown at the given number of milliseconds from the start of the stream.
+    # Timestamps must not go backwards.
+    def write_frame(frame, timestamp_ms)
+      open_cluster(timestamp_ms) if start_new_cluster?(timestamp_ms)
+
+      # The block header is written separately from the frame so that the frame, which is by far
+      # the largest part, never has to be copied into another string.
+      @io.write(simple_block_header(frame.bytesize, timestamp_ms - @cluster_timestamp_ms))
+      @io.write(frame)
+    end
+
+    private
+
+    def write_header
+      @io.write(element(Id::EBML, [
+        element(Id::EBML_VERSION, uint(1)),
+        element(Id::EBML_READ_VERSION, uint(1)),
+        element(Id::EBML_MAX_ID_LENGTH, uint(4)),
+        element(Id::EBML_MAX_SIZE_LENGTH, uint(8)),
+        element(Id::DOC_TYPE, "matroska"),
+        element(Id::DOC_TYPE_VERSION, uint(4)),
+        element(Id::DOC_TYPE_READ_VERSION, uint(2))
+      ].join))
+
+      # Everything below lives inside the segment, which stays open until the file ends.
+      @io.write(id(Id::SEGMENT) + UNKNOWN_SIZE)
+
+      @io.write(element(Id::INFO, [
+        element(Id::TIMESTAMP_SCALE, uint(TIMESTAMP_SCALE_NS)),
+        element(Id::MUXING_APP, "test-recorder"),
+        element(Id::WRITING_APP, "test-recorder")
+      ].join))
+
+      @io.write(element(Id::TRACKS, element(Id::TRACK_ENTRY, [
+        element(Id::TRACK_NUMBER, uint(TRACK_NUMBER)),
+        element(Id::TRACK_UID, uint(TRACK_NUMBER)),
+        element(Id::TRACK_TYPE, uint(TRACK_TYPE_VIDEO)),
+        # Lacing packs several frames into one block. Each frame here is a whole picture with its
+        # own time, so it is turned off.
+        element(Id::FLAG_LACING, uint(0)),
+        element(Id::CODEC_ID, "V_MJPEG"),
+        # PixelWidth and PixelHeight are mandatory, but the frame size is not known before the
+        # first frame arrives, and the browser may change it mid recording. Every JPEG states its
+        # own size, so declare the smallest allowed picture and let the decoder use the real one.
+        # Declaring a plausible size instead is actively harmful: ffmpeg then compares it with the
+        # size it decodes and can read a shorter picture as one field of an interlaced frame.
+        element(Id::VIDEO, element(Id::PIXEL_WIDTH, uint(1)) + element(Id::PIXEL_HEIGHT, uint(1)))
+      ].join)))
+    end
+
+    def start_new_cluster?(timestamp_ms)
+      @cluster_timestamp_ms.nil? || timestamp_ms - @cluster_timestamp_ms > MAX_CLUSTER_DURATION_MS
+    end
+
+    def open_cluster(timestamp_ms)
+      @io.write(id(Id::CLUSTER) + UNKNOWN_SIZE)
+      @io.write(element(Id::TIMESTAMP, uint(timestamp_ms)))
+      @cluster_timestamp_ms = timestamp_ms
+    end
+
+    def simple_block_header(frame_length, relative_ms)
+      track = vint(TRACK_NUMBER)
+      # The payload is the track number, the 16 bit offset, the flags and then the frame itself.
+      size = track.bytesize + 2 + 1 + frame_length
+
+      id(Id::SIMPLE_BLOCK) + vint(size) + track + [relative_ms].pack("s>") + [KEYFRAME].pack("C")
+    end
+
+    # An element is its ID, then its length as a variable size integer, then its content.
+    def element(element_id, content)
+      id(element_id) + vint(content.bytesize) + content
+    end
+
+    # A variable size integer starts with a marker bit that says how many bytes it spans, and
+    # carries the value in the bits after it. A value that would fill every remaining bit is
+    # reserved to mean "unknown", so it needs one more byte.
+    def vint(value)
+      width = 1
+      width += 1 until value < (1 << (7 * width)) - 1
+
+      bytes = big_endian_bytes(value, width)
+      bytes[0] |= 1 << (8 - width)
+      bytes.pack("C*")
+    end
+
+    # Numbers are stored big endian, in as few bytes as they fit into.
+    def uint(value)
+      big_endian_bytes(value).pack("C*")
+    end
+    alias id uint
+
+    def big_endian_bytes(value, width = nil)
+      bytes = []
+      loop do
+        bytes.unshift(value & 0xFF)
+        value >>= 8
+        break if value.zero?
+      end
+      bytes.unshift(0) while width && bytes.size < width
+      bytes
+    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.3.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Yuji Yaginuma
@@ -84,10 +84,14 @@ files:
 - lib/test-recorder.rb
 - lib/test_recorder.rb
 - lib/test_recorder/cdp_recorder.rb
+- lib/test_recorder/frame_writer.rb
+- lib/test_recorder/matroska_writer.rb
 - lib/test_recorder/rails.rb
 - 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
@@ -95,6 +99,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: http://github.com/y-yagi/test-recorder
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -109,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Automatically record videos when tests failed.
 test_files: []