Ruby ecosystem development introduction workshop: Tokyo: 2026-08-05: i7a: ferrum: Work log

[i7a]

This is a work log of a "Ruby ecosystem development introduction workshop".
"Ruby ecosystem development introduction workshop" is an activity to increase Ruby ecosystem developers.
Here's been discussed in Japanese. Thanks.

Rubyエコシステム開発入門ワークショップ関連情報

• スライド：ワークショップの進行に使っているスライドがあります。
• ruby-jp Slackの#oss_gateチャンネル：Rubyエコシステムの開発に関することならなんでも相談できます。ワークショップが終わった後もオンラインで相談しながら継続的にRubyエコシステムの開発に参加しましょう！
• 過去のビギナーの作業ログ：他の人の作業ログから学べることがいろいろあるはずです。

[i7a]

https://github.com/rubycdp/ferrum から、https://github.com/rubycdp/ferrum/blob/main/LICENSE を確認
MIT Licenseでした

MIT Licenseを下記で検索
https://opensource.org/licenses
あったので問題なさそう

とりあえずお作法を理解したいので、ferrumをforkして ( https://github.com/i7a/ferrum )手元にclone。codexにtypoっぽい記載を探させると、下記が出てくる
https://github.com/rubycdp/ferrum/blob/v0.17.2/lib/ferrum/network/request.rb#L36

resourceのtypoを直したcommitを作り、forkした repoにpush ( https://github.com/i7a/ferrum/tree/fix/network-request-resource-typo )
本家にPRを投げる
rubycdp/ferrum#607

[i7a]

上記の際にテストコードのファイル名のtypoが出てきた
https://github.com/rubycdp/ferrum/blob/v0.17.2/spec/rbga_spec.rb
(正しくは rgba_spec.rb )

ので、新規ローカルブランチを切って手元でファイル名を変更
ローカルでテストを実行し、failしない事を確認
forkしたrepoにpush
Descriptionに rubycdp/ferrum#286 へのrefを張りつつ、本家にPRを投げる
rubycdp/ferrum#608

[i7a]

テスト戦略を把握したいので、下記をcodexに尋ねる

そもそもこのrepoのテスト戦略というか、どういった観点をどういったテストで抑えるか、みたいなのってあったりしそうですか？

明文化された「テスト戦略」は見当たりません。CONTRIBUTING.md やテスト方針文書はなく、READMEには bundle exec rake test の実行方法だけが
  書かれています。

  ただし、spec構成とCIから、実質的な戦略はかなり読み取れます。結論からいうと、このリポジトリは「実ブラウザーを使った統合テストを中心
  に、必要な部分だけunit specで補う」構成です。一般的なテストピラミッドより、統合テストへ強く寄っています。

  ## 観点とテスト方法

   確認したい観点                           主なテスト方法
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   公開APIが利用者視点で動くか              実Chromeを起動する統合spec
  ───────────────────────────────────────  ───────────────────────────────────────────────
   DOM検索・クリック・入力                  ローカルHTMLへアクセスし、実際のDOM結果を確認
  ───────────────────────────────────────  ───────────────────────────────────────────────
   ページ遷移・iframe・非同期処理           CDPイベントとページ状態を実ブラウザーで確認
  ───────────────────────────────────────  ───────────────────────────────────────────────
   HTTP通信・Cookie・Header                 ローカルPumaサーバーへの実リクエストを観測
  ───────────────────────────────────────  ───────────────────────────────────────────────
   Screenshot・PDF・Tracing                 生成物のサイズ、内容、JSONを検査
  ───────────────────────────────────────  ───────────────────────────────────────────────
   Download                                 実ファイルの保存とCDPイベントを確認
  ───────────────────────────────────────  ───────────────────────────────────────────────
   オプション・プロセス・OS分岐             mockを利用したunit spec
  ───────────────────────────────────────  ───────────────────────────────────────────────
   Request・Responseなどの値オブジェクト    クラス単位の比較的小さなspec
  ───────────────────────────────────────  ───────────────────────────────────────────────
   Rubyバージョン互換性                     CIでRuby 3.1〜4.0をマトリクス実行
  ───────────────────────────────────────  ───────────────────────────────────────────────
   コーディング規約                         Ruby 3.1と4.0でRubocop

  ## 中心は実ブラウザー統合テスト

  RSpec全体で、Pumaのテストサーバーと実際のChromeを起動します。repositories/ferrum/spec/spec_helper.rb:35

  spec/support/views/ に多数のテスト用HTMLがあり、たとえば次のような動作を利用者と同じ経路で確認しています。

  browser.go_to("/form")
  input = browser.at_css("input")
  input.focus.type("text")
  expect(input.value).to eq("text")

  テストダブルでCDPを模倣するより、実際にChromeへCDPコマンドを送り、結果をDOMから読み戻す方針です。

  この方法には次の利点があります。

  - CDPコマンドの指定ミスを検出できる
  - Chromeの実際のイベント順序を検証できる
  - DOM、Network、Frameをまたぐ問題を検出できる
  - 利用者の操作に近い形で回帰テストを書ける

  一方で、Chromeバージョン、OS、ロケール、タイミングに影響されやすくなります。先ほどの全量テストで出た「オフライン画面が日本語」
  「Chrome 151で入力結果が変わる」といった失敗は、この戦略の副作用です。

  ## ローカルWebアプリケーションをfixtureとして使う

  外部サイトには依存せず、テスト用のRackアプリケーションをPumaで起動します。repositories/ferrum/spec/support/server.rb:51

  これにより、以下を再現可能にしています。

  - 遅いレスポンス
  - リダイレクト
  - AJAX
  - Basic認証
  - ファイルダウンロード
  - iframe
  - CookieとHeader
  - 通信切断
  - JavaScriptエラー
  - ダイアログ
  - Popup

  外部ネットワークの不安定さを避けつつ、ブラウザー通信そのものは本物を使うという境界です。

  ## specは公開機能単位で整理されている

  specのファイル構成は、ほぼ公開クラスや機能に対応しています。

  spec/browser_spec.rb
  spec/page_spec.rb
  spec/frame_spec.rb
  spec/node_spec.rb
  spec/network_spec.rb
  spec/downloads_spec.rb
  spec/page/screenshot_spec.rb
  spec/page/tracing_spec.rb

  特にテスト数が多いのは以下です。

  - Node: 約110 examples
  - Network: 約48 examples
  - Browser: 約46 examples
  - Frame: 約42 examples
  - Screenshot: 約31 examples

  利用者が直接触るAPIや、Chromeとの境界が複雑な部分へ厚くテストを置いています。

  ## unit specは補助的

  spec/unit/ は存在しますが、現在はごく少数です。

  - Browserのロガーとコマンドライン
  - Process終了処理
  - AccessibilityのAXNode

  それ以外でもRequest、Response、Cookieなどには比較的小さなspecがありますが、全体としてunit test中心ではありません。

  実際、rgba_spec.rb のようにブラウザーを必要としないspecを単独実行しても、共通の spec_helper によりPumaとChromeが起動します。したがっ
  て、unitとintegrationの実行基盤は明確には分離されていません。

  ## 非同期処理は最終結果を中心に確認

  FerrumではCDPイベントを別スレッドで受け取るため、テストでは次の仕組みを使っています。

  - rspec-wait
  - wait_a_bit
  - Ferrum自身のtimeout
  - テストサーバーのpending request待機
  - ページ遷移完了待機

  内部イベントの順番を逐一mockするより、「最終的にDOMや通信状態が期待値になったか」を見る傾向があります。

  Utils::Event や Client::Subscriber に直接unit specがないのも、この方針によるものと考えられます。これらはページ遷移やダウンロードの統
  合テストを通して間接的に確認されています。

  ## テスト間の分離

  各exampleの終了後に browser.reset が呼ばれ、作成したBrowser ContextやPageを破棄します。repositories/ferrum/spec/support/
  global_helpers.rb:30

  また、次のexampleに進む前に、テストサーバー側で処理中のリクエストが残っていないことを待ちます。

  狙いは以下です。

  - CookieやPageをテスト間で残さない
  - 遅いリクエストを次のテストへ持ち越さない
  - 1つのChromeプロセスを再利用して実行時間を抑える

  ## CIで確認している互換性

  GitHub Actionsでは、Chrome stableに対してRubyをマトリクス実行しています。repositories/ferrum/.github/workflows/tests.yml:11

  Ruby 3.1
  Ruby 3.2
  Ruby 3.3
  Ruby 3.4
  Ruby 4.0

  つまり、ブラウザーの種類やChromeバージョンを広く組み合わせるのではなく、「最新Chrome × 対応Ruby各バージョン」を主要な互換性境界として
  います。

  失敗時には、ブラウザーのログとスクリーンショットをCI artifactへ保存します。非同期・描画系の失敗を後から調べやすくする設計です。

  ## 現時点で明示されていないもの

  以下は戦略として明文化・導入されていません。

  - カバレッジ率の計測・最低基準
  - unit／integration／system testの分類基準
  - mockを使う条件
  - Chromeバージョンごとの互換性マトリクス
  - macOS／WindowsでのCI
  - FirefoxのCI
  - flaky testの再実行ポリシー
  - skipされたテストの管理方針
  - 性能テスト
  - mutation testing

  したがって、現在の実質的な戦略は次のように要約できます。

  > Chromeとの統合部分は、ローカルWebアプリケーションと実Chromeを使って利用者視点で確認する。プロセス制御や単純な値変換は必要に応じて
  > unit specで補い、対応RubyバージョンはCIマトリクスで確認する。

  これはブラウザー操作ライブラリとして合理的ですが、内部の並行処理やretryロジックの回帰を素早く特定するunit spec、カバレッジの可視化、
  flaky testの整理には改善余地があります。

CDPへの依存が強いgemなので、実際にCDPを呼んで試すテストに軸足を置いている事を理解
CDP経由でアクセスさせる先のサイトの各種挙動をスタブさせる為に、ローカルでサーバを立ててそれをテスト用に使っている事を理解

[i7a]

上記を踏まえて下記をcodexに相談

テスト戦略と現在のunitテストのカバー状況を踏まえた時に、Unitテストを追加する価値が最も高そうなクラスはどれですか

  結論としては次のとおりです。

  - リポジトリ全体で最も追加価値が高いクラス：Ferrum::Client::Subscriber
  - 小さく安全に始めるなら：Ferrum::Utils::Event
  - 最も簡単だが相対的な価値は少し下がる：Ferrum::Utils::Attempt

とのことなので、一旦Ferrum::Utils::Eventの中身を見てみる

[i7a]

下記をcursorに解説して貰う
https://github.com/rubycdp/ferrum/blob/main/lib/ferrum/utils/event.rb

このファイル自体は薄いラッパーで、やっていることは次だけです。

スレッド間の「ページが落ち着いたか」通知は親の set / wait に任せる
reset を「unset にする + 必ず世代を進める + その世代を返す」に差し替える
その世代を iteration で読めるようにする
ページナビの開始／完了を、ブロッキング待機と世代カウンタの両方で扱うための小さなアダプタ、という位置づけです。

背景として、「CDPコマンドのレスポンス」と「ページ読み込み開始イベント」が別経路・別スレッドで届くためこのコマンド起因で新しいロードが始まったか／始まっていないかを判断するものの模様 (ムズい、CDPコマンド周りの処理の理解が必要そう)

[i7a]

並行してpdf作成処理周りに関して、パフォーマンスやセキュリティ面での改善点をcodexに調査させたところ、その内に一つにCDPのIO.close呼び出し漏れが上がる

 CDPストリームを必ずcloseする

  これはGem側で改修すべき具体的な問題です。

  現在は IO.read をEOFまで呼びますが、IO.close を呼んでいません。lib/ferrum/page/stream.rb:27

  Chromeで確認したところ、EOF後にも IO.close は正常に受け付けられました。つまりEOFだけでは明示的にcloseしたことになっていません。CDPのIO仕様
  (https://chromedevtools.github.io/devtools-protocol/tot/IO/)でも、IO.close は一時バックストレージを破棄する操作とされています。

  長寿命Chromeへ切り替えるなら、少なくとも以下の構造にするのが安全です。

  def stream(output:, handle:)
    loop do
      result = command("IO.read", handle: handle, size: STREAM_CHUNK)
      chunk = result.fetch("data")
      chunk = Base64.decode64(chunk) if result["base64Encoded"]
      output << chunk
      break if result["eof"]
    end
  ensure
    close_stream(handle)
  end

  元の例外を IO.close の失敗で上書きしない処理とテストも必要です。PDFだけでなくTracingにも共通で効きます。

明示的にIO.closeを呼ぶようにした方がお行儀は良さそう
そこまで性能インパクトは無いが、異常終了時などに聞いてくる可能性はありそう

[i7a]

IO.close の実装有無に関して、過去議論されていない事をcodexに確認して貰う

調査した範囲では、Ferrumで IO.close の要否を明示的に議論した形跡は見つかりませんでした。意図的に省略したというより、実装時の見落としである可能性が高そうです。

  確認できた経緯は次のとおりです。

  - PR #121: Stream PDFs in chunks (https://github.com/rubycdp/ferrum/pull/121) で2020年に ReturnAsStream と IO.read が導入された
  - 議論は主に85MB PDFのメモリ使用量、128KBのチャンクサイズ、Base64エンコードについて
  - レビューコメントにも IO.close への言及はない
  - 2022年の PR #189: Implement Tracing (https://github.com/rubycdp/ferrum/pull/189) でPDFとTracingのストリーム処理が共通化された
  - このレビューでも設計やイベント処理は議論されたが、closeは議論されていない
  - Git履歴全体を IO.close で検索しても、追加・削除された履歴はない
  - Issue/PR検索でも IO.close、close stream、temporary backing に該当する議論はない
  - Issue #531 (https://github.com/rubycdp/ferrum/issues/531) には IO.read がEOFに達したログがあるものの、論点はwindow closeのハングであり、CDPストリームのcloseではない

  一方、PR #189で参考として挙げられていた同時期の実装は明示的にcloseしています。

  - 当時のPlaywrightは、EOFまで読んだ後に IO.close を実行していました。historical crProtocolHelper.ts
    (https://github.com/microsoft/playwright/blob/c373986ca0b91b76d4910ce0617b55e50934114c/packages/playwright-core/src/server/chromium/crProtocolHelper.ts)

  - 当時のpuppeteer-rubyも、読み取り後に io_close を実行しています。ProtocolStreamReader
    (https://github.com/YusukeIwaki/puppeteer-ruby/blob/a9018bd39c0f6dcb7988e5ab53762aa1922ad8ce/lib/puppeteer/protocol_stream_reader.rb)

  - 現在のPuppeteerとPlaywrightも、引き続き IO.close を実行しています。Puppeteer
    (https://github.com/puppeteer/puppeteer/blob/f8d63c73c3d7c21a8b0f421411e7df8386195436/packages/puppeteer-core/src/common/util.ts)、Playwright
    (https://github.com/microsoft/playwright/blob/5f58876dc84d69008907e75d818baf55b0f78dc1/packages/playwright-core/src/server/chromium/crProtocolHelper.ts)

  したがって、現状は次のように評価できます。

  - 「close不要」と判断した過去の設計判断は確認できない
  - 参考実装にはcloseがあったが、Ferrumには取り込まれなかった
  - CDP仕様と他実装に揃える修正としてPRを出す根拠は十分ある
  - ただし性能改善ではなく、リソース管理の完全性・異常系のcleanupとして説明するのが妥当

  PRでは「リークが実証された」と断定せず、「CDP仕様上必要な後始末であり、Puppeteer/Playwrightとも整合する」とするのが通りやすいと思います。

[i7a]

streamメソッドのテストの整備状況を確認

• 現状、stream メソッドの直接的な単体テストは0件です。PDFとTracingの結合テストから間接的に通っているだけです。

  ### 現在カバーされている範囲

  PDFでは、実際にファイルへ出力してPDFサイズを検証するテストが2件あります。

  - spec/page/screenshot_spec.rb:373
  - spec/page/screenshot_spec.rb:388

  また、1回の IO.read が即EOFを返すモックテストが1件あります。

  - spec/page/screenshot_spec.rb:409

  Tracingでは以下が間接的に確認されています。

  - ファイル出力
  - メモリへのバイナリ出力
  - Base64出力
  - スクリーンショットを含む比較的大きなTrace
  - 連続3回のTrace生成

  spec/page/tracing_spec.rb:15

  ただし、これらは最終成果物を確認しているだけで、stream の細かな動作を固定するテストではありません。

  ### カバーされていない重要ケース

  現在、次は明示的にテストされていません。

  - 複数チャンクが正しい順番で結合される
  - EOFまで正しい回数だけ IO.read する
  - size: STREAM_CHUNK が毎回渡される
  - base64Encoded: true のチャンクを正しくデコードする
  - Base64と非Base64チャンクが混在する
  - 空ストリーム
  - IO.read が途中で失敗する
  - ファイル書き込みが途中で失敗する
  - result.fetch("data") が失敗する
  - 同じhandleを全readで使用する
  - IO.close の呼び出し
  - 正常時・異常時にcloseが一度だけ呼ばれる
  - close自体が失敗した場合の扱い
  - read/write例外をclose失敗で上書きしないこと

  ### IO.close 追加時の影響

  現在のモックテストは Page.printToPDF と IO.read しかスタブしていません。spec/page/screenshot_spec.rb:412

  そのため IO.close を追加すると、このテストは実在しないhandle "1" をChromeへcloseしようとして失敗する可能性があります。ここには次の期待値を追加する必要があります。

  expect(browser.page).to receive(:command)
    .with("IO.close", handle: "1")
    .and_return({})

  ### 追加すべき最小テストセット

  最低でも、spec/page/stream_spec.rb を新設して次の5件が必要です。

  1. 複数チャンクをEOFまで結合する
  2. Base64チャンクをデコードする
  3. 正常完了時に IO.close を一度呼ぶ
  4. IO.read または出力書き込み失敗時にもcloseする
  5. close失敗が元のread/write例外を上書きしない

  特に4と5が重要です。ensure を追加しただけでは、cleanupの例外が本来のPDF生成エラーを隠す実装になりやすいためです。

  総評として、正常系の結合テストはそれなりにありますが、ストリーム処理単体の回帰防止としては弱い状態です。IO.close の修正を入れるなら、単体テストを同時追加するのが妥当で
  す。

初手整備しに行っても良さそう