puppeteer-ruby 0.45.6 → 0.50.0.alpha5

data/lib/puppeteer/element_handle.rb

@@ -1,3 +1,5 @@
+# rbs_inline: enabled
+
 require_relative './element_handle/bounding_box'
 require_relative './element_handle/box_model'
 require_relative './element_handle/offset'
@@ -8,10 +10,10 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   include Puppeteer::IfPresent
   using Puppeteer::DefineAsyncMethod
 
-  # @param context [Puppeteer::ExecutionContext]
-  # @param client [Puppeteer::CDPSession]
-  # @param remote_object [Puppeteer::RemoteObject]
-  # @param frame [Puppeteer::Frame]
+  # @rbs context: Puppeteer::ExecutionContext -- Execution context
+  # @rbs client: Puppeteer::CDPSession -- CDP session
+  # @rbs remote_object: Puppeteer::RemoteObject -- Remote object handle
+  # @rbs frame: Puppeteer::Frame -- Owning frame
   def initialize(context:, client:, remote_object:, frame:)
     super(context: context, client: client, remote_object: remote_object)
     @frame = frame
@@ -22,6 +24,7 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
 
   attr_reader :page, :frame, :frame_manager
 
+  # @rbs return: String -- Inspection string
   def inspect
     values = %i[context remote_object page disposed].map do |sym|
       value = instance_variable_get(:"@#{sym}")
@@ -38,11 +41,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   #
   # This method does not work across navigations or if the element is detached from DOM.
   #
-  # @param selector - A
   # {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
   # of an element to wait for
-  # @param options - Optional waiting parameters
-  # @returns Promise which resolves when element specified by selector string
   # is added to DOM. Resolves to `null` if waiting for hidden: `true` and
   # selector is not found in DOM.
   # @remarks
@@ -59,8 +59,18 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   # - `timeout`: maximum time to wait in milliseconds. Defaults to `30000`
   # (30 seconds). Pass `0` to disable timeout. The default value can be changed
   # by using the {@link Page.setDefaultTimeout} method.
+  # @rbs selector: String -- CSS selector
+  # @rbs visible: bool? -- Wait for element to be visible
+  # @rbs hidden: bool? -- Wait for element to be hidden
+  # @rbs timeout: Numeric? -- Maximum wait time in milliseconds
+  # @rbs return: Puppeteer::ElementHandle? -- Matched element handle
   def wait_for_selector(selector, visible: nil, hidden: nil, timeout: nil)
-    query_handler_manager.detect_query_handler(selector).wait_for(self, visible: visible, hidden: hidden, timeout: timeout)
+    query_handler_manager.detect_query_handler(selector).wait_for(
+      self,
+      visible: visible,
+      hidden: hidden,
+      timeout: timeout,
+    )
   end
 
   define_async_method :async_wait_for_selector
@@ -92,11 +102,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   # await browser.close();
   # })();
   # ```
-  # @param xpath - A
   # {@link https://developer.mozilla.org/en-US/docs/Web/XPath | xpath} of an
   # element to wait for
-  # @param options - Optional waiting parameters
-  # @returns Promise which resolves when element specified by xpath string is
   # added to DOM. Resolves to `null` if waiting for `hidden: true` and xpath is
   # not found in DOM.
   # @remarks
@@ -113,6 +120,11 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   # - `timeout`: A number which is maximum time to wait for in milliseconds.
   # Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default
   # value can be changed by using the {@link Page.setDefaultTimeout} method.
+  # @rbs xpath: String -- XPath expression
+  # @rbs visible: bool? -- Wait for element to be visible
+  # @rbs hidden: bool? -- Wait for element to be hidden
+  # @rbs timeout: Numeric? -- Maximum wait time in milliseconds
+  # @rbs return: Puppeteer::ElementHandle? -- Matched element handle
   def wait_for_xpath(xpath, visible: nil, hidden: nil, timeout: nil)
     param_xpath =
       if xpath.start_with?('//')
@@ -126,6 +138,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
 
   define_async_method :async_wait_for_xpath
 
+  # @rbs tag_name: String -- Tag name to assert
+  # @rbs return: Puppeteer::ElementHandle -- Element handle
   def to_element(tag_name)
     unless evaluate('(node, tagName) => node.nodeName === tagName.toUpperCase()', tag_name)
       raise ArgumentError.new("Element is not a(n) `#{tag_name}` element")
@@ -133,10 +147,45 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     self
   end
 
+  # @rbs return: Puppeteer::ElementHandle -- Element handle
   def as_element
     self
   end
 
+  # @rbs return: bool -- Whether element is visible
+  def visible?
+    check_visibility(true)
+  end
+
+  # @rbs return: bool -- Whether element is hidden
+  def hidden?
+    check_visibility(false)
+  end
+
+  # @rbs visible: bool -- Expected visibility state
+  # @rbs return: bool -- Whether visibility matches
+  private def check_visibility(visible)
+    js = <<~JAVASCRIPT
+      (node, visible) => {
+        if (!node) return visible === false;
+        const element =
+          node.nodeType === Node.TEXT_NODE ? node.parentElement : node;
+        if (!element) return visible === false;
+        const style = window.getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        const isVisible =
+          style &&
+          style.visibility !== 'hidden' &&
+          style.visibility !== 'collapse' &&
+          rect.width !== 0 &&
+          rect.height !== 0;
+        return visible === isVisible;
+      }
+    JAVASCRIPT
+    evaluate(js, visible)
+  end
+
+  # @rbs return: Puppeteer::Frame? -- Frame that owns this element
   def content_frame
     node_info = @remote_object.node_info(@client)
     frame_id = node_info['node']['frameId']
@@ -147,8 +196,9 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     end
   end
 
-  class ScrollIntoViewError < StandardError; end
+  class ScrollIntoViewError < Puppeteer::Error; end
 
+  # @rbs return: void -- No return value
   def scroll_into_view_if_needed
     js = <<~JAVASCRIPT
       async(element) => {
@@ -165,7 +215,7 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     end
     begin
       @remote_object.scroll_into_view_if_needed(@client)
-    rescue => err
+    rescue
       # Fallback to Element.scrollIntoView if DOM.scrollIntoViewIfNeeded is not supported
       js = <<~JAVASCRIPT
         async (element, pageJavascriptEnabled) => {
@@ -198,26 +248,27 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     sleep 0.16
   end
 
-  class ElementNotVisibleError < StandardError
+  class ElementNotVisibleError < Puppeteer::Error
     def initialize
       super("Node is either not visible or not an HTMLElement")
     end
   end
 
-  class ElementNotClickableError < StandardError
+  class ElementNotClickableError < Puppeteer::Error
     def initialize
       super("Node is either not clickable or not an HTMLElement")
     end
   end
 
-  # @param quad [Array<Array<Point>>]]
-  # @param offset [Point]
+  # @rbs quad: Array[Point] -- Quad points
+  # @rbs offset: Point -- Offset to apply
+  # @rbs return: Array[Point] -- Offset quad points
   private def apply_offsets_to_quad(quad, offset)
     quad.map { |part| part + offset }
   end
 
-  # @param frame [Puppeteer::Frame]
-  # @return [Point]
+  # @rbs frame: Puppeteer::Frame -- Frame to calculate offsets for
+  # @rbs return: Point -- Calculated offset
   private def oopif_offsets(frame)
     offset = Point.new(x: 0, y: 0)
     while frame.parent_frame
@@ -235,6 +286,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     offset
   end
 
+  # @rbs offset: Puppeteer::ElementHandle::Offset | Hash[Symbol, Numeric] | nil -- Click offset
+  # @rbs return: Puppeteer::ElementHandle::Point -- Clickable point
   def clickable_point(offset = nil)
     offset_param = Offset.from(offset)
 
@@ -258,7 +311,7 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     end
 
     # Filter out quads that have too small area to click into.
-    # Fallback to `layoutViewport` in case of using Firefox.
+    # Prefer cssLayoutViewport when available.
     layout_viewport = layout_metrics["cssLayoutViewport"] || layout_metrics["layoutViewport"]
     client_width = layout_viewport["clientWidth"]
     client_height = layout_viewport["clientHeight"]
@@ -290,18 +343,14 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     quads.first.reduce(:+) / 4
   end
 
-  # @param quad [Array<number>]
-  # @return [Array<Point>]
+  # @rbs quad: Array[Numeric] -- Protocol quad coordinates
+  # @rbs return: Array[Point] -- Point array
   private def from_protocol_quad(quad)
     quad.each_slice(2).map do |x, y|
       Point.new(x: x, y: y)
     end
   end
 
-  # @param quad [Array<Point>]
-  # @param width [number]
-  # @param height [number]
-  # @return [Array<Point>]
   private def intersect_quad_with_viewport(quad, width, height)
     quad.map do |point|
       Point.new(
@@ -311,30 +360,67 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     end
   end
 
+  # @rbs return: void -- No return value
   def hover
     scroll_into_view_if_needed
     point = clickable_point
     @page.mouse.move(point.x, point.y)
   end
 
-  # @param delay [Number]
-  # @param button [String] "left"|"right"|"middle"
-  # @param click_count [Number]
-  # @param offset [Hash]
-  def click(delay: nil, button: nil, click_count: nil, offset: nil)
+  # @rbs delay: Numeric? -- Delay between down and up (ms)
+  # @rbs button: String? -- Mouse button
+  # @rbs click_count: Integer? -- Deprecated: use count (click_count only sets clickCount)
+  # @rbs count: Integer? -- Number of clicks to perform
+  # @rbs offset: Puppeteer::ElementHandle::Offset | Hash[Symbol, Numeric] | nil -- Click offset
+  # @rbs return: void -- No return value
+  def click(delay: nil, button: nil, click_count: nil, count: nil, offset: nil)
     scroll_into_view_if_needed
     point = clickable_point(offset)
-    @page.mouse.click(point.x, point.y, delay: delay, button: button, click_count: click_count)
+    @page.mouse.click(point.x, point.y, delay: delay, button: button, click_count: click_count, count: count)
   end
 
   define_async_method :async_click
 
-  class DragInterceptionNotEnabledError < StandardError
+  # @rbs return: Puppeteer::TouchHandle -- Touch handle
+  def touch_start
+    scroll_into_view_if_needed
+    point = clickable_point
+    @page.touchscreen.touch_start(point.x, point.y)
+  end
+
+  define_async_method :async_touch_start
+
+  # @rbs touch: Puppeteer::TouchHandle? -- Optional touch handle
+  # @rbs return: void -- No return value
+  def touch_move(touch = nil)
+    scroll_into_view_if_needed
+    point = clickable_point
+    if touch
+      touch.move(point.x, point.y)
+    else
+      @page.touchscreen.touch_move(point.x, point.y)
+    end
+  end
+
+  define_async_method :async_touch_move
+
+  # @rbs return: void -- No return value
+  def touch_end
+    scroll_into_view_if_needed
+    @page.touchscreen.touch_end
+  end
+
+  define_async_method :async_touch_end
+
+  class DragInterceptionNotEnabledError < Puppeteer::Error
     def initialize
       super('Drag Interception is not enabled!')
     end
   end
 
+  # @rbs x: Numeric -- Drag end X coordinate
+  # @rbs y: Numeric -- Drag end Y coordinate
+  # @rbs return: void -- No return value
   def drag(x:, y:)
     unless @page.drag_interception_enabled?
       raise DragInterceptionNotEnabledError.new
@@ -344,25 +430,33 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     @page.mouse.drag(start, Point.new(x: x, y: y))
   end
 
+  # @rbs data: Hash[String, untyped] -- Drag data payload
+  # @rbs return: void -- No return value
   def drag_enter(data)
     scroll_into_view_if_needed
     target = clickable_point
     @page.mouse.drag_enter(target, data)
   end
 
+  # @rbs data: Hash[String, untyped] -- Drag data payload
+  # @rbs return: void -- No return value
   def drag_over(data)
     scroll_into_view_if_needed
     target = clickable_point
     @page.mouse.drag_over(target, data)
   end
 
+  # @rbs data: Hash[String, untyped] -- Drag data payload
+  # @rbs return: void -- No return value
   def drop(data)
     scroll_into_view_if_needed
     target = clickable_point
     @page.mouse.drop(target, data)
   end
 
-  # @param target [ElementHandle]
+  # @rbs target: Puppeteer::ElementHandle -- Drop target element
+  # @rbs delay: Numeric? -- Delay before dropping (ms)
+  # @rbs return: void -- No return value
   def drag_and_drop(target, delay: nil)
     scroll_into_view_if_needed
     start_point = clickable_point
@@ -370,7 +464,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     @page.mouse.drag_and_drop(start_point, target_point, delay: delay)
   end
 
-  # @return [Array<String>]
+  # @rbs values: Array[String] -- Option values to select
+  # @rbs return: Array[String] -- Selected values
   def select(*values)
     if nonstring = values.find { |value| !value.is_a?(String) }
       raise ArgumentError.new("Values must be strings. Found value \"#{nonstring}\" of type \"#{nonstring.class}\"")
@@ -411,7 +506,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     evaluate(fn, values)
   end
 
-  # @param file_paths [Array<String>]
+  # @rbs file_paths: Array[String] -- Files to upload
+  # @rbs return: void -- No return value
   def upload_file(*file_paths)
     is_multiple = evaluate("el => el.multiple")
     if !is_multiple && file_paths.length >= 2
@@ -433,12 +529,14 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
         element.dispatchEvent(new Event('change', { bubbles: true }));
       }
       JAVASCRIPT
-      await evaluate(fn)
+      evaluate(fn)
     else
       @remote_object.set_file_input_files(@client, file_paths.map { |path| File.expand_path(path) }, backend_node_id)
     end
   end
 
+  # @rbs block: Proc? -- Optional block for Object#tap usage
+  # @rbs return: Puppeteer::ElementHandle | nil -- Element handle or nil
   def tap(&block)
     return super(&block) if block
 
@@ -449,14 +547,16 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
 
   define_async_method :async_tap
 
+  # @rbs return: void -- No return value
   def focus
     evaluate('element => element.focus()')
   end
 
   define_async_method :async_focus
 
-  # @param text [String]
-  # @param delay [number|nil]
+  # @rbs text: String -- Text to type
+  # @rbs delay: Numeric? -- Delay between key presses (ms)
+  # @rbs return: void -- No return value
   def type_text(text, delay: nil)
     focus
     @page.keyboard.type_text(text, delay: delay)
@@ -464,17 +564,18 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
 
   define_async_method :async_type_text
 
-  # @param key [String]
-  # @param text [String]
-  # @param delay [number|nil]
+  # @rbs key: String -- Key name
+  # @rbs delay: Numeric? -- Delay between key events (ms)
+  # @rbs text: String? -- Text to input
+  # @rbs return: void -- No return value
   def press(key, delay: nil, text: nil)
     focus
-    @page.keyboard.press(key, delay: delay, text: text)
+    @page.keyboard.press(key, delay: delay)
   end
 
   define_async_method :async_press
 
-  # @return [BoundingBox|nil]
+  # @rbs return: Puppeteer::ElementHandle::BoundingBox? -- Bounding box or nil
   def bounding_box
     if_present(box_model) do |result_model|
       offset = oopif_offsets(@frame)
@@ -491,13 +592,23 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     end
   end
 
-  # @return [BoxModel|nil]
+  # @rbs return: Puppeteer::ElementHandle::BoxModel? -- Box model or nil
   def box_model
     if_present(@remote_object.box_model(@client)) do |result|
       BoxModel.new(result['model'], offset: oopif_offsets(@frame))
     end
   end
 
+  # @rbs type: String? -- Image format
+  # @rbs path: String? -- File path to save
+  # @rbs full_page: bool? -- Capture full page
+  # @rbs clip: Hash[Symbol, Numeric]? -- Clip rectangle
+  # @rbs quality: Integer? -- JPEG quality
+  # @rbs omit_background: bool? -- Omit background for PNG
+  # @rbs encoding: String? -- Encoding (base64 or binary)
+  # @rbs capture_beyond_viewport: bool? -- Capture beyond viewport
+  # @rbs from_surface: bool? -- Capture from surface
+  # @rbs return: String -- Screenshot data
   def screenshot(type: nil,
                  path: nil,
                  full_page: nil,
@@ -571,30 +682,85 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     Puppeteer::QueryHandlerManager.instance
   end
 
+  private def query_selector_in_isolated_world(selector)
+    puppeteer_world = frame.puppeteer_world
+    if execution_context == puppeteer_world.execution_context
+      return query_handler_manager.detect_query_handler(selector).query_one(self)
+    end
+
+    adopted = puppeteer_world.adopt_handle(self)
+    begin
+      result = query_handler_manager.detect_query_handler(selector).query_one(adopted)
+      return nil unless result
+
+      if result.execution_context == frame.main_world.execution_context
+        return result
+      end
+
+      frame.main_world.transfer_handle(result)
+    ensure
+      adopted.dispose
+    end
+  end
+
+  private def query_selector_all_in_isolated_world(selector)
+    puppeteer_world = frame.puppeteer_world
+    if execution_context == puppeteer_world.execution_context
+      results = query_handler_manager.detect_query_handler(selector).query_all(self)
+      return results || []
+    end
+
+    adopted = puppeteer_world.adopt_handle(self)
+    begin
+      results = query_handler_manager.detect_query_handler(selector).query_all(adopted)
+      return [] unless results
+
+      results.map do |handle|
+        if handle.execution_context == frame.main_world.execution_context
+          handle
+        else
+          frame.main_world.transfer_handle(handle)
+        end
+      end
+    ensure
+      adopted.dispose
+    end
+  end
+
   # `$()` in JavaScript.
-  # @param selector [String]
+  # @rbs selector: String -- CSS selector
+  # @rbs return: Puppeteer::ElementHandle? -- Matching element or nil
   def query_selector(selector)
-    query_handler_manager.detect_query_handler(selector).query_one(self)
+    query_selector_in_isolated_world(selector)
   end
   alias_method :S, :query_selector
 
   # `$$()` in JavaScript.
-  # @param selector [String]
-  def query_selector_all(selector)
-    query_handler_manager.detect_query_handler(selector).query_all(self)
+  # @rbs selector: String -- CSS selector
+  # @rbs isolate: bool? -- Use isolated world for queries
+  # @rbs return: Array[Puppeteer::ElementHandle] -- Matching elements
+  def query_selector_all(selector, isolate: nil)
+    if isolate == false
+      results = query_handler_manager.detect_query_handler(selector).query_all(self)
+      return results || []
+    end
+
+    query_selector_all_in_isolated_world(selector)
   end
   alias_method :SS, :query_selector_all
 
-  class ElementNotFoundError < StandardError
+  class ElementNotFoundError < Puppeteer::Error
+    # @rbs selector: String -- CSS selector
     def initialize(selector)
       super("failed to find element matching selector \"#{selector}\"")
     end
   end
 
   # `$eval()` in JavaScript.
-  # @param selector [String]
-  # @param page_function [String]
-  # @return [Object]
+  # @rbs selector: String -- CSS selector
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @rbs return: untyped -- Evaluation result
   def eval_on_selector(selector, page_function, *args)
     element_handle = query_selector(selector)
     unless element_handle
@@ -610,9 +776,10 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   define_async_method :async_eval_on_selector
 
   # `$$eval()` in JavaScript.
-  # @param selector [String]
-  # @param page_function [String]
-  # @return [Object]
+  # @rbs selector: String -- CSS selector
+  # @rbs page_function: String -- Function or expression to evaluate
+  # @rbs args: Array[untyped] -- Arguments for evaluation
+  # @rbs return: untyped -- Evaluation result
   def eval_on_selector_all(selector, page_function, *args)
     handles = query_handler_manager.detect_query_handler(selector).query_all_array(self)
     result = handles.evaluate(page_function, *args)
@@ -625,8 +792,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   define_async_method :async_eval_on_selector_all
 
   # `$x()` in JavaScript. $ is not allowed to use as a method name in Ruby.
-  # @param expression [String]
-  # @return [Array<ElementHandle>]
+  # @rbs expression: String -- XPath expression
+  # @rbs return: Array[Puppeteer::ElementHandle] -- Matching elements
   def Sx(expression)
     param_xpath =
       if expression.start_with?('//')
@@ -641,8 +808,8 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   define_async_method :async_Sx
 
   # in JS, #isIntersectingViewport.
-  # @param threshold [Float|nil]
-  # @return [Boolean]
+  # @rbs threshold: Numeric? -- Visibility threshold
+  # @rbs return: bool -- Whether element intersects viewport
   def intersecting_viewport?(threshold: nil)
     option_threshold = threshold || 0
     js = <<~JAVASCRIPT
@@ -662,7 +829,6 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
     evaluate(js, option_threshold)
   end
 
-  # @param quad [Array<Point>]
   private def compute_quad_area(quad)
     # Compute sum of all directed areas of adjacent triangles
     # https://en.wikipedia.org/wiki/Polygon#Simple_polygons
@@ -670,6 +836,9 @@ class Puppeteer::ElementHandle < Puppeteer::JSHandle
   end
 
   # used in AriaQueryHandler
+  # @rbs accessible_name: String? -- Accessible name filter
+  # @rbs role: String? -- Accessible role filter
+  # @rbs return: Hash[String, untyped] -- Accessibility tree result
   def query_ax_tree(accessible_name: nil, role: nil)
     @remote_object.query_ax_tree(@client,
       accessible_name: accessible_name, role: role)

data/lib/puppeteer/emulation_manager.rb

@@ -23,7 +23,7 @@ class Puppeteer::EmulationManager
       end
     has_touch = viewport.has_touch?
 
-    await_all(
+    Puppeteer::AsyncUtils.await_promise_all(
       @client.async_send_message('Emulation.setDeviceMetricsOverride',
         mobile: mobile,
         width: width,

data/lib/puppeteer/env.rb

@@ -16,7 +16,7 @@ class Puppeteer::Env
   end
 
   def windows?
-    RUBY_PLATFORM =~ /mswin|mingw|cygwin/
+    !!(RUBY_PLATFORM =~ /mswin|mingw|cygwin/)
   end
 end
 

data/lib/puppeteer/errors.rb

@@ -1,2 +1,25 @@
-# ref: https://github.com/puppeteer/puppeteer/blob/master/src/Errors.ts
-class Puppeteer::TimeoutError < StandardError; end
+# ref: https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Errors.ts
+
+# The base class for all Puppeteer-specific errors
+class Puppeteer::Error < StandardError
+  attr_writer :cause
+
+  def cause
+    return nil if @cause.equal?(self)
+
+    stack = Thread.current[:puppeteer_cause_stack] ||= []
+    return nil if stack.include?(object_id)
+
+    stack << object_id
+    begin
+      @cause || super
+    ensure
+      stack.pop
+      Thread.current[:puppeteer_cause_stack] = nil if stack.empty?
+    end
+  end
+end
+
+class Puppeteer::TimeoutError < Puppeteer::Error; end
+
+class Puppeteer::TouchError < Puppeteer::Error; end

data/lib/puppeteer/event_callbackable.rb

@@ -20,6 +20,12 @@ module Puppeteer::EventCallbackable
       @listeners.delete(id)
     end
 
+    # @param handler [Proc] Listener proc
+    def delete_by_handler(handler)
+      id, = @listeners.find { |_, listener| listener == handler }
+      @listeners.delete(id) if id
+    end
+
     # @implement Enumerable#each
     def each(&block)
       @listeners.values.each(&block)
@@ -33,6 +39,15 @@ module Puppeteer::EventCallbackable
 
   alias_method :on, :add_event_listener
 
+  def off(event_name_or_id, listener = nil, &block)
+    listener ||= block
+    if listener
+      (@event_listeners ||= {})[event_name_or_id]&.delete_by_handler(listener)
+    else
+      remove_event_listener(event_name_or_id)
+    end
+  end
+
   def remove_event_listener(*id_args)
     (@event_listeners ||= {}).each do |event_name, listeners|
       id_args.each do |id|

data/lib/puppeteer/events.rb

@@ -34,6 +34,7 @@ module CDPSessionEmittedEvents ; end
 
 {
   Disconnected: EventsDefinitionUtils.symbol('CDPSession.Disconnected'),
+  Ready: EventsDefinitionUtils.symbol('CDPSession.Ready'),
 }.define_const_into(CDPSessionEmittedEvents)
 
 # All the events a Browser may emit.
@@ -159,6 +160,9 @@ module PageEmittedEvents ; end
   # The object is readonly. See Page#setRequestInterception for intercepting and mutating requests.
   Request: 'request',
 
+  # Emitted when a request is served from cache.
+  RequestServedFromCache: 'requestservedfromcache',
+
   # Emitted when a request fails, for example by timing out.
   #
   # Contains a HTTPRequest.