Class: Ferrum::Target

Inherits:
Object
  • Object
show all
Defined in:
lib/ferrum/target.rb

Overview

Represents a CDP target, e.g. a page, iframe, dedicated/shared worker or service worker. Wraps the raw targetInfo params and lazily connects to the target as a Page or Worker over its own Client/SessionClient session, so a Target can exist without being connected to yet.

Constant Summary collapse

NEW_WINDOW_WAIT = 
ENV.fetch("FERRUM_NEW_WINDOW_WAIT", 0.3).to_f

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(browser_client, session_id = nil, params = nil) ⇒ Target

Returns a new instance of Target.



20
21
22
23
24
25
26
27
 
# File 'lib/ferrum/target.rb', line 20

def initialize(browser_client, session_id = nil, params = nil)
  @page = nil
  @worker = nil
  @session_id = session_id
  @params = params
  @browser_client = browser_client
  @options = browser_client.options
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the value of attribute options.



17
18
19
 
# File 'lib/ferrum/target.rb', line 17

def options
  @options
end

#page ⇒ Page

Connects to and returns this target's Page.

Returns:



50
51
52
 
# File 'lib/ferrum/target.rb', line 50

def page
  @page ||= build_page
end

#session_id ⇒ Object

Returns the value of attribute session_id.



18
19
20
 
# File 'lib/ferrum/target.rb', line 18

def session_id
  @session_id
end

Instance Method Details

#build_page(**options) ⇒ Page

Builds a Page for this target. Called lazily by page, or eagerly by Context#create_page.

Parameters:

  • options (Hash)

Returns:



75
76
77
78
 
# File 'lib/ferrum/target.rb', line 75

def build_page(**options)
  maybe_sleep_if_new_window
  Page.new(client, context_id: context_id, target_id: id, **options)
end

#build_worker ⇒ Worker

Builds a Worker for this target. Called lazily by #worker.

Returns:



83
84
85
 
# File 'lib/ferrum/target.rb', line 83

def build_worker
  Worker.new(client, target_id: id, url: url)
end

#client ⇒ Client, SessionClient

The client connected to this target's own session (or a dedicated WebSocket connection if options.flatten is disabled).

Returns:



65
66
67
 
# File 'lib/ferrum/target.rb', line 65

def client
  @client ||= build_client
end

#close_connection ⇒ void

This method returns an undefined value.

Closes the WebSocket connection, without closing the target itself in the browser.



91
92
93
94
 
# File 'lib/ferrum/target.rb', line 91

def close_connection
  @page&.close_connection
  @worker&.close_connection
end

#command ⇒ Boolean, Hash

Sends a CDP command through #client.

Returns:

  • (Boolean, Hash) —

    true when sent asynchronously, otherwise the command's result.



203
204
205
 
# File 'lib/ferrum/target.rb', line 203

def command(...)
  client.command(...)
end

#connected? ⇒ Boolean

Whether this target has already been connected to as a Page or Worker.

Returns:

  • (Boolean) 


43
44
45
 
# File 'lib/ferrum/target.rb', line 43

def connected?
  !!@page || !!@worker
end

#context_id ⇒ String?

The id of the browser context this target belongs to.

Returns:

  • (String, nil) 


143
144
145
 
# File 'lib/ferrum/target.rb', line 143

def context_id
  @params["browserContextId"]
end

#id ⇒ String

The target's id.

Returns:

  • (String) 


99
100
101
 
# File 'lib/ferrum/target.rb', line 99

def id
  @params["targetId"]
end

#iframe? ⇒ Boolean

Whether this target is an iframe.

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/ferrum/target.rb', line 158

def iframe?
  type == "iframe"
end

#maybe_sleep_if_new_window ⇒ void

This method returns an undefined value.

Chrome fires no events for a newly opened window, so we sleep a bit to give it a chance to load before connecting.



194
195
196
197
 
# File 'lib/ferrum/target.rb', line 194

def maybe_sleep_if_new_window
  # Dirty hack because new window doesn't have events at all
  sleep(NEW_WINDOW_WAIT) if window?
end

#opener_id ⇒ String?

The id of the target that opened this one, set only for windows/tabs opened via window.open/links/etc.

Returns:

  • (String, nil) 


129
130
131
 
# File 'lib/ferrum/target.rb', line 129

def opener_id
  @params["openerId"]
end

#page? ⇒ Boolean

Whether this target is a page.

Returns:

  • (Boolean) 


165
166
167
 
# File 'lib/ferrum/target.rb', line 165

def page?
  type == "page"
end

#parent_id ⇒ Object

The id of the target that spawned this one, set for iframes and workers. Unlike opener_id, which is only set for windows/tabs opened via window.open/links/etc.



136
137
138
 
# File 'lib/ferrum/target.rb', line 136

def parent_id
  @params["parentId"]
end

#service_worker? ⇒ Boolean

Whether this target is a service worker.

Returns:

  • (Boolean) 


186
187
188
 
# File 'lib/ferrum/target.rb', line 186

def service_worker?
  type == "service_worker"
end

#shared_worker? ⇒ Boolean

Whether this target is a shared worker.

Returns:

  • (Boolean) 


179
180
181
 
# File 'lib/ferrum/target.rb', line 179

def shared_worker?
  type == "shared_worker"
end

#title ⇒ String

The target's title.

Returns:

  • (String) 


114
115
116
 
# File 'lib/ferrum/target.rb', line 114

def title
  @params["title"]
end

#type ⇒ String

The target's type, e.g. "page", "iframe", "worker", "shared_worker", "service_worker".

Returns:

  • (String) 


107
108
109
 
# File 'lib/ferrum/target.rb', line 107

def type
  @params["type"]
end

#update(params) ⇒ Hash

Merges freshly received CDP target info into this target's params, e.g. on Target.targetInfoChanged.

Parameters:

  • params (Hash)

Returns:

  • (Hash) 


35
36
37
 
# File 'lib/ferrum/target.rb', line 35

def update(params)
  @params.merge!(params)
end

#url ⇒ String

The target's URL.

Returns:

  • (String) 


121
122
123
 
# File 'lib/ferrum/target.rb', line 121

def url
  @params["url"]
end

#window? ⇒ Boolean

Whether this target is a window/tab, i.e. was opened via window.open/a link/etc. and thus has an #opener_id.

Returns:

  • (Boolean) 


151
152
153
 
# File 'lib/ferrum/target.rb', line 151

def window?
  !!opener_id
end

#worker ⇒ Worker

Connects to and returns this target's Worker.

Returns:



57
58
59
 
# File 'lib/ferrum/target.rb', line 57

def worker
  @worker ||= build_worker
end

#worker? ⇒ Boolean

Whether this target is a dedicated worker.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/ferrum/target.rb', line 172

def worker?
  type == "worker"
end