feat(record): drive twd-js command pacing from --record-pace - #15
Conversation
twd-js spaces out its own command loop, so frames are captured at full rate rather than the video being stretched afterwards the way record.speed does. Measured, speed 0.25 drops the effective frame rate to 7.7fps and slows the dead air as much as the interesting moments; pacing does neither. Degrades rather than crashes on an older twd-js: the in-page call returns null when the hook is absent, so the run still completes and still records, unpaced, with a warning. Without that a missing hook would throw a bare TypeError and take the whole run down, which every user would hit until twd-js ships the hook.
TWD Contract Validation
23 passed · 41 failed · 3 warnings · 1 skipped Failed validations./contracts/users-3.0.json
./contracts/posts-3.1.json
./contracts/products-3.0.json
./contracts/events-3.1.json
|
Recording exists to produce something someone will watch, and an unpaced clip is about a second long, so the default should be the good outcome rather than one a second flag unlocks. --record alone is now watchable. 300 rather than 500: still clearly watchable and roughly 40% cheaper in wall clock on a broad run. --record-pace raises or lowers it, and 0 disables. The cost is run time, not timeouts. A 50 test suite averaging 10 actions per test gains about 2.5 minutes. Reaching protocolTimeout would take around 100 actions in a single test, which is why the docs point at wall clock instead.
|
Pacing is now on by default at 300ms ( 300 rather than 500 because it is still clearly watchable and costs roughly 40% less wall clock on a broad run. I also corrected something I had overstated in the original description. The risk of a default pace is wall clock, not Updated: |
TWD Contract Validation
23 passed · 41 failed · 3 warnings · 1 skipped Failed validations./contracts/users-3.0.json
./contracts/posts-3.1.json
./contracts/products-3.0.json
./contracts/events-3.1.json
|
Adds
--record-pace <ms>, which slows the run itself so a recorded video is watchable at full frame rate.Depends on BRIKEV/twd#316, merged but not yet released. See "Before merging" below.
npx twd-cli run --record --record-pace 500 --test "checkout flow"Why not just use
--record-speedspeedis an ffmpegsetptsfilter applied after recording. It stretches the same frames over a longer timeline, so the effective frame rate falls in proportion. Measured on identical page activity:10.50.25It also slows the dead air exactly as much as the interesting moments.
paceinstead tells twd-js to hold briefly after each command. Frames are captured at full rate, the pauses land where something just happened, and typing is spaced per keystroke so text appears character by character.What changed
src/config.jsrecord.pace, default0src/parseArgs.js--record-pace <ms>, both flag forms, same positive-finite guard as--record-speedsrc/index.jspage.evaluateafterstartRecording, gated onrecord.enabledbin/twd-cli.js,README.mdGraceful degradation on an older twd-js
This is the one place I went beyond the plan, and it matters more than it sounds.
The plan called for a bare
page.evaluate((ms) => window.__twdSetPace(ms), pace). On any currently published twd-js that global does not exist, so it throws aTypeErrorand takes the entire test run down, not just the pacing. Since twd-js has not shipped the hook yet, every user of this flag would hit it today.The in-page call now returns
nullwhen the hook is absent. The run completes, still records, and warns:There is a test asserting the run returns
hasFailures === falseon that path, so a regression cannot quietly turn it back into a crash.Testing
308 passing, up from 297 on main. Covers: the config default and partial merge, both flag forms and rejection of non-numeric, zero and negative values, the pace being set when recording, not set when
paceis 0, not set when recording is disabled, the clamp warning, and the missing-hook degradation.Not verified end to end. Everything here mocks the browser, and a real check needs a published twd-js carrying
window.__twdSetPace. The twd-js half was itself verified end to end in its own PR (pace 600measured 6.0x slower on the example app), but the two have not yet been run together against a real package.Before merging
Nothing here breaks without twd-js: absent the hook the flag warns and records unpaced. So this is safe to merge ahead of the twd-js release, it just will not do anything useful until
twd-jsships the hook.If you would rather prove the pair first, point twd-cli's
twd-jsat a local twd checkout with afile:link and run it against the example app.