feat: add touch emulation to Page#set_viewport's mobile: option

CHANGELOG.md

@@ -13,6 +13,9 @@
   so callers can `#join` it if they need cleanup to have finished, e.g. before process exit or before reusing a
   fixed port. Default (`wait: true`) keeps the previous synchronous behavior; `#restart` always waits.
 - `Ferrum::Page::Stream#close_stream`, a public method that releases a CDP `IO` stream handle (`IO.close`).
+- `Ferrum::Page#set_viewport`'s `mobile:` option now also enables touch emulation
+  (`Emulation.setTouchEmulationEnabled`), alongside the existing device metrics override, so it fully emulates a
+  mobile device's viewport and touch support together. [#94]
 
 ### Changed
 - `Ferrum::Page::Stream#stream` now closes the CDP stream handle (`IO.close`) once it's been fully read, so streams

docs/14-emulation.md

@@ -6,14 +6,26 @@ sidebar_position: 14
 
 #### set_viewport
 
-Overrides device screen dimensions and emulates viewport.
+Overrides device screen dimensions and emulates viewport. When `:mobile` is
+`true`, this also enables touch emulation (`navigator.maxTouchPoints`,
+`ontouchstart`) alongside the mobile viewport metrics.
 
 * options `Hash`
   * :width `Integer`, viewport width. `0` by default
   * :height `Integer`, viewport height. `0` by default
   * :scale_factor `Float`, device scale factor. `0` by default
-  * :mobile `Boolean`, whether to emulate mobile device. `false` by default
+  * :mobile `Boolean`, whether to emulate mobile device and enable touch. `false` by default
 
 ```ruby
 page.set_viewport(width: 1000, height: 600, scale_factor: 3)
 ```
+
+`:width`, `:height`, and `:scale_factor` all default to `0`, which per the
+[DevTools protocol](https://chromedevtools.github.io/devtools-protocol/tot/Emulation/#method-setDeviceMetricsOverride)
+disables overriding that particular value. This means `mobile:` can be
+enabled on its own, at the page's current size, without specifying a device
+size preset:
+
+```ruby
+page.set_viewport(mobile: true)
+```

lib/ferrum/browser/binary.rb

@@ -68,7 +68,7 @@ def prepare_paths
         [paths, exts]
       end
 
-      # rubocop:disable Style/CollectionCompact
+      # rubocop:disable-next Style/CollectionCompact
       def lazy_find(cmds)
         cmds.lazy.map do |cmd, path, ext|
           absolute_path = File.absolute_path(cmd)
@@ -81,7 +81,6 @@ def lazy_find(cmds)
           cmd
         end.reject(&:nil?) # .compact isn't defined on Enumerator::Lazy
       end
-      # rubocop:enable Style/CollectionCompact
     end
   end
 end

lib/ferrum/page.rb

@@ -176,9 +176,15 @@ def close_connection
     #
     # @param [Float] scale_factor device scale factor value. 0 disables the override
     #
-    # @param [Boolean] mobile whether to emulate mobile device
+    # @param [Boolean] mobile whether to emulate mobile device and enable touch
     #
-    def set_viewport(width:, height:, scale_factor: 0, mobile: false)
+    def set_viewport(width: 0, height: 0, scale_factor: 0, mobile: false)
+      command(
+        "Emulation.setTouchEmulationEnabled",
+        enabled: mobile,
+        maxTouchPoints: 1
+      )
+
       command(
         "Emulation.setDeviceMetricsOverride",
         slowmoable: true,

lib/ferrum/page/screenshot.rb

@@ -32,9 +32,9 @@ module Screenshot
         A1: { width: 23.40, height: 33.10 },
         A2: { width: 16.54, height: 23.40 },
         A3: { width: 11.70, height: 16.54 },
-        A4: { width:  8.27, height: 11.70 },
-        A5: { width:  5.83, height:  8.27 },
-        A6: { width:  4.13, height:  5.83 }
+        A4: { width: 8.27, height: 11.70 },
+        A5: { width: 5.83, height: 8.27 },
+        A6: { width: 4.13, height: 5.83 }
       }.freeze
 
       #

sig/ferrum/page.rbs

@@ -53,6 +53,8 @@ module Ferrum
 
     def close_connection: () -> void
 
+    def set_viewport: (?width: ::Integer, ?height: ::Integer, ?scale_factor: ::Float, ?mobile: bool) -> Hash[String, untyped]
+
     def resize: (?width: ::Numeric?, ?height: ::Numeric?, ?fullscreen: bool) -> Hash[String, untyped]
 
     def position: () -> Hash[String, ::Integer]

spec/page_spec.rb

@@ -198,6 +198,32 @@
       expect(page.viewport_size).to eq([500, 300])
       expect(page.device_pixel_ratio).to eq(2)
     end
+
+    def is_mobile?
+      page.evaluate("'ontouchstart' in window || navigator.maxTouchPoints > 0")
+    end
+
+    context "when mobile is true" do
+      it "enables touch/mobile emulation without changing the window size" do
+        page.go_to("/")
+
+        expect do
+          page.set_viewport(mobile: true)
+          page.reload
+        end.to change { is_mobile? }.to(true)
+      end
+    end
+
+    context "when mobile is false" do
+      it "does not enable touch/mobile emulation" do
+        page.go_to("/")
+
+        expect do
+          page.set_viewport(mobile: false)
+          page.reload
+        end.not_to(change { is_mobile? })
+      end
+    end
   end
 
   describe "#on" do