test-recorder 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76a3cec00d302949375e3ad8d9c4c566f8c52cac703db8384b36505d2be47bb
-  data.tar.gz: 109b533201bcde42f210224cf1a01f5b0b795cb1dc5c737d83a80a0b232d67b3
+  metadata.gz: f2df7b7454c1776d950afaadc9fcefdab037f2638a0a0f05ba7251ef08131428
+  data.tar.gz: 97e45933561090c772aef6a26849075626c7d8e9766d0e25c60a642841a38f36
 SHA512:
-  metadata.gz: 5b4ca4f5087cc0d32cb335f79fdface896ae918493958ff753f36207f93e44b80a0d1af11f9486c8a6cdcad9d2dd2974599cabfac1afaf158e85d51842d5f71c
-  data.tar.gz: 52a41a7cc4a35ee019892cea4c67f467bb0e7a9e7f391bba7bfca52a596bda057b2fb92f72c9dc20ef85e700b52985dd049a2bfed6baac874cb3bad8479eb19d
+  metadata.gz: 2ced41859d336565547e55de99b4574952f175bc3acb7ce6a6231c07ce32bab27483689f6a9c3967950d4da80145ea2002a0abe2ba3b6905c56fa9728902e004
+  data.tar.gz: 1657c90f69bcf393bb7e4905fde1a9e6afc74b7c5e864521a72bee0f4d3f97db9b1ceba28e466d321e7122ce2545548431ccd593a576e53f2b7c3c45d34214da

data/.github/workflows/ci.yml

@@ -20,14 +20,14 @@ jobs:
         ruby: [ '4.0', '3.4', '3.3' ]
 
     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 }}

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,9 @@
 ## Unreleased
 
+## 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/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

@@ -2,11 +2,18 @@ require "base64"
 require "fileutils"
 require "tempfile"
 
+require "test_recorder/frame_writer"
+
 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)
+    # 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)
@@ -14,9 +21,9 @@ module TestRecorder
           page = devtools.page
           page.enable
 
-          record = Record.new(page, nil, 0)
+          record = Record.new(page)
           page.on(:screencast_frame) do |event|
-            write_frame(record, event["data"])
+            write_frame(record, event)
             record.page.screencast_frame_ack(session_id: event["sessionId"])
           end
           record
@@ -25,17 +32,39 @@ module TestRecorder
 
       private
 
-      def write_frame(record, data)
-        return if record.io.nil?
-
-        record.io.write(Base64.decode64(data))
-        record.frame_count += 1
+      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
@@ -51,16 +80,14 @@ module TestRecorder
       @started = enabled
       return unless @started
 
-      @tmp_video = Tempfile.new(["testrecorder", ".mjpeg"])
+      @tmp_video = Tempfile.new(["testrecorder", ".mkv"])
       @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
+      @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: @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: TestRecorder.every_nth_frame)
     end
 
     def stop_and_discard
@@ -76,12 +103,14 @@ module TestRecorder
 
       @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 @record.frame_count < 2
+      if @frame_writer.frame_count < 2
+        warn "[TestRecorder] The screencast captured no page updates, so no video was saved."
         @tmp_video.close!
         return ""
       end
@@ -90,11 +119,12 @@ module TestRecorder
       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)
+      # 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!
 

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: test-recorder
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yuji Yaginuma
@@ -84,6 +84,8 @@ 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
@@ -109,7 +111,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: []