ferrum 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +63 -1
  3. data/lib/ferrum/browser/binary.rb +1 -3
  4. data/lib/ferrum/browser/command.rb +0 -2
  5. data/lib/ferrum/browser/options/base.rb +5 -6
  6. data/lib/ferrum/browser/options/chrome.rb +0 -3
  7. data/lib/ferrum/browser/options.rb +33 -12
  8. data/lib/ferrum/browser/process/killer.rb +188 -0
  9. data/lib/ferrum/browser/process/output.rb +143 -0
  10. data/lib/ferrum/browser/process.rb +122 -144
  11. data/lib/ferrum/browser.rb +24 -30
  12. data/lib/ferrum/client/subscriber.rb +7 -2
  13. data/lib/ferrum/client/web_socket.rb +124 -43
  14. data/lib/ferrum/client.rb +36 -9
  15. data/lib/ferrum/console/location.rb +42 -0
  16. data/lib/ferrum/console/message.rb +230 -0
  17. data/lib/ferrum/console.rb +157 -0
  18. data/lib/ferrum/context.rb +41 -20
  19. data/lib/ferrum/contexts.rb +110 -28
  20. data/lib/ferrum/downloads.rb +2 -1
  21. data/lib/ferrum/errors.rb +50 -4
  22. data/lib/ferrum/frame/dom.rb +100 -45
  23. data/lib/ferrum/frame/runtime/legacy.rb +336 -0
  24. data/lib/ferrum/frame/runtime.rb +417 -186
  25. data/lib/ferrum/frame/script.rb +289 -0
  26. data/lib/ferrum/frame.rb +33 -4
  27. data/lib/ferrum/interceptable.rb +35 -4
  28. data/lib/ferrum/isolated_world.rb +94 -0
  29. data/lib/ferrum/keyboard.rb +95 -8
  30. data/lib/ferrum/log/annotated.rb +77 -0
  31. data/lib/ferrum/log/default.rb +55 -0
  32. data/lib/ferrum/log/json.rb +32 -0
  33. data/lib/ferrum/log/paint.rb +28 -0
  34. data/lib/ferrum/log.rb +247 -0
  35. data/lib/ferrum/mouse.rb +22 -8
  36. data/lib/ferrum/node.rb +127 -52
  37. data/lib/ferrum/page/frames.rb +10 -3
  38. data/lib/ferrum/page/screenshot.rb +11 -10
  39. data/lib/ferrum/page/stream.rb +16 -1
  40. data/lib/ferrum/page.rb +117 -58
  41. data/lib/ferrum/proxy.rb +8 -7
  42. data/lib/ferrum/remote_object.rb +75 -0
  43. data/lib/ferrum/target.rb +14 -3
  44. data/lib/ferrum/utils/deprecate.rb +77 -0
  45. data/lib/ferrum/utils/thread.rb +3 -1
  46. data/lib/ferrum/version.rb +1 -1
  47. data/lib/ferrum/worker.rb +8 -0
  48. data/lib/ferrum.rb +4 -1
  49. metadata +18 -4
  50. data/lib/ferrum/browser/options/firefox.rb +0 -70
data/lib/ferrum/proxy.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "logger"
3
4
  require "tempfile"
4
5
 
5
6
  begin
@@ -133,19 +134,19 @@ module Ferrum
133
134
 
134
135
  if proxy
135
136
  @logger.debug("CONNECT: sending a Request-Line")
136
- os << proxy_request_line << CRLF
137
+ os << proxy_request_line << WEBrick::CRLF
137
138
  @logger.debug("CONNECT: > #{proxy_request_line}")
138
139
  if credentials
139
140
  @logger.debug("CONNECT: sending credentials")
140
- os << "Proxy-Authorization: " << credentials << CRLF
141
+ os << "Proxy-Authorization: " << credentials << WEBrick::CRLF
141
142
  end
142
- os << CRLF
143
- proxy_status_line = os.gets(LF)
143
+ os << WEBrick::CRLF
144
+ proxy_status_line = os.gets(WEBrick::LF)
144
145
  @logger.debug("CONNECT: read Status-Line from the upstream server")
145
146
  @logger.debug("CONNECT: < #{proxy_status_line}")
146
147
  if %r{^HTTP/\d+\.\d+\s+200\s*} =~ proxy_status_line
147
- while line = os.gets(LF)
148
- break if /\A(#{CRLF}|#{LF})\z/om =~ line
148
+ while line = os.gets(WEBrick::LF)
149
+ break if /\A(#{WEBrick::CRLF}|#{WEBrick::LF})\z/om =~ line
149
150
  end
150
151
  else
151
152
  raise WEBrick::HTTPStatus::BadGateway
@@ -169,7 +170,7 @@ module Ferrum
169
170
 
170
171
  # Should clear request-line not to send the response twice.
171
172
  # see: HTTPServer#run
172
- req.parse(NullReader) rescue nil
173
+ req.parse(WEBrick::NullReader) rescue nil
173
174
  end
174
175
 
175
176
  begin
@@ -0,0 +1,75 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Ferrum
4
+ #
5
+ # An opaque reference to a JavaScript value living in the browser, returned
6
+ # by {Frame::Runtime#evaluate_handle}. Unlike {Frame::Runtime#evaluate},
7
+ # which serializes the result into Ruby, a handle keeps the value in the
8
+ # page so it can be passed straight back into a later evaluation without a
9
+ # round trip through JSON.
10
+ #
11
+ # @example
12
+ # list = page.evaluate_handle("document.querySelectorAll('li')")
13
+ # page.evaluate("Array.from(nodes).map(n => n.textContent)", nodes: list)
14
+ #
15
+ class RemoteObject
16
+ # @return [String] the CDP remote object id.
17
+ attr_reader :remote_id
18
+
19
+ # @return [String] the JavaScript type, e.g. `"object"` or `"function"`.
20
+ attr_reader :type
21
+
22
+ # @return [String, nil] the JavaScript subtype, e.g. `"array"` or `"map"`.
23
+ attr_reader :subtype
24
+
25
+ # @return [String, nil] the browser's own description of the value.
26
+ attr_reader :description
27
+
28
+ #
29
+ # @param [Frame, Worker] runtime
30
+ # The frame or worker that evaluated the value.
31
+ #
32
+ # @param [Page, Worker] page
33
+ # The target the value belongs to.
34
+ #
35
+ # @param [Hash] result
36
+ # A CDP `Runtime.RemoteObject`.
37
+ #
38
+ def initialize(runtime, page, result)
39
+ @runtime = runtime
40
+ @page = page
41
+ @remote_id = result["objectId"]
42
+ @type = result["type"]
43
+ @subtype = result["subtype"]
44
+ @description = result["description"]
45
+ end
46
+
47
+ #
48
+ # Serializes the handle into a plain Ruby value, resolving nodes into
49
+ # {Node} objects the same way {Frame::Runtime#evaluate} does.
50
+ #
51
+ # @return [Object]
52
+ #
53
+ def value
54
+ @runtime.evaluate_in(self, "this", [], {})
55
+ end
56
+
57
+ #
58
+ # Releases the browser-side reference. The handle is unusable afterwards.
59
+ #
60
+ # @return [void]
61
+ #
62
+ def release
63
+ @page.command("Runtime.releaseObject", objectId: @remote_id)
64
+ nil
65
+ rescue Ferrum::BrowserError
66
+ nil
67
+ end
68
+
69
+ # @return [String]
70
+ def inspect
71
+ %(#<#{self.class} @remote_id=#{@remote_id.inspect} @type=#{@type.inspect} ) +
72
+ %(@subtype=#{@subtype.inspect} @description=#{@description.inspect}>)
73
+ end
74
+ end
75
+ end
data/lib/ferrum/target.rb CHANGED
@@ -17,11 +17,12 @@ module Ferrum
17
17
  attr_reader :options
18
18
  attr_accessor :session_id
19
19
 
20
- def initialize(browser_client, session_id = nil, params = nil)
20
+ def initialize(browser_client, session_id = nil, params = nil, implicit: false)
21
21
  @page = nil
22
22
  @worker = nil
23
23
  @session_id = session_id
24
24
  @params = params
25
+ @implicit = implicit
25
26
  @browser_client = browser_client
26
27
  @options = browser_client.options
27
28
  end
@@ -54,6 +55,9 @@ module Ferrum
54
55
  # Connects to and returns this target's {Worker}.
55
56
  #
56
57
  # @return [Worker]
58
+ #
59
+ # @raise [NoSuchTargetError] if there's no session with the target, e.g. a service worker
60
+ # not attached to with {Context#attach_target}.
57
61
  def worker
58
62
  @worker ||= build_worker
59
63
  end
@@ -81,6 +85,10 @@ module Ferrum
81
85
  #
82
86
  # @return [Worker]
83
87
  def build_worker
88
+ if options.flatten && session_id.nil?
89
+ raise NoSuchTargetError, "No session with #{type} #{id}, attach to it with Context#attach_target first"
90
+ end
91
+
84
92
  Worker.new(client, target_id: id, url: url)
85
93
  end
86
94
 
@@ -137,11 +145,14 @@ module Ferrum
137
145
  @params["parentId"]
138
146
  end
139
147
 
140
- # The id of the browser context this target belongs to.
148
+ # The id of the browser context this target belongs to, `nil` for the
149
+ # browser's implicit context, which Chrome doesn't let us address by id,
150
+ # see {Context#implicit?}. Commands scoped to a browser context target it
151
+ # by omitting `browserContextId`.
141
152
  #
142
153
  # @return [String, nil]
143
154
  def context_id
144
- @params["browserContextId"]
155
+ @params["browserContextId"] unless @implicit
145
156
  end
146
157
 
147
158
  # Whether this target is a window/tab, i.e. was opened via
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Ferrum
4
+ module Utils
5
+ #
6
+ # Emits deprecation warnings for the JavaScript evaluation API, whose
7
+ # old behavior is removed in the next release, Ferrum 0.21.
8
+ #
9
+ # Warnings are printed once per unique message and call site so that a
10
+ # deprecated call inside a loop doesn't flood the output. Set
11
+ # `FERRUM_DEPRECATION_WARNINGS=0` to silence them entirely, or
12
+ # `FERRUM_DEPRECATION_WARNINGS=raise` to turn them into errors while
13
+ # migrating a suite.
14
+ #
15
+ module Deprecate
16
+ @seen = Concurrent::Set.new
17
+
18
+ module_function
19
+
20
+ #
21
+ # Warns about a deprecation, naming where it comes from.
22
+ #
23
+ # @param [String] message
24
+ # What changes, and what to do instead.
25
+ #
26
+ # @param [Boolean] user_code
27
+ # Whether to name the first caller outside any installed gem, which is
28
+ # where a script passed through a library like Capybara was written,
29
+ # rather than the direct caller.
30
+ #
31
+ # @return [void]
32
+ #
33
+ # @raise [Ferrum::Error]
34
+ # When `FERRUM_DEPRECATION_WARNINGS=raise`.
35
+ #
36
+ def warn(message, user_code: false)
37
+ mode = ENV.fetch("FERRUM_DEPRECATION_WARNINGS", "warn")
38
+ return if %w[0 false].include?(mode)
39
+
40
+ location = caller_locations(1)&.find { |frame| !skip?(frame.path.to_s, user_code) }
41
+ message = "[Ferrum] DEPRECATION: #{message}"
42
+ message += "\n called from #{location.path}:#{location.lineno}" if location
43
+
44
+ raise Ferrum::Error, message if mode == "raise"
45
+ return unless @seen.add?(message)
46
+
47
+ Kernel.warn(message)
48
+ end
49
+
50
+ #
51
+ # Forgets which warnings have already been printed. Only useful in tests.
52
+ #
53
+ # @return [void]
54
+ #
55
+ def reset!
56
+ @seen.clear
57
+ end
58
+
59
+ #
60
+ # Whether a caller's path is left out when naming where a deprecated
61
+ # call comes from.
62
+ #
63
+ # @param [String] path
64
+ #
65
+ # @param [Boolean] user_code
66
+ # Whether to leave out installed gems as well as Ferrum itself.
67
+ #
68
+ # @return [Boolean]
69
+ #
70
+ def skip?(path, user_code)
71
+ return true if path.include?("/lib/ferrum/") || path.end_with?("forwardable.rb") || path.start_with?("<")
72
+
73
+ user_code && Gem.path.any? { |gem_path| path.start_with?(File.join(gem_path, "")) }
74
+ end
75
+ end
76
+ end
77
+ end
@@ -14,10 +14,12 @@ module Ferrum
14
14
  #
15
15
  # @param [Boolean] abort_on_exception
16
16
  # Whether the thread aborts the process if it raises an unhandled exception.
17
+ # Off by default: an exception in one of Ferrum's own threads reaches the
18
+ # main thread wherever it happens to be, or kills the process outright.
17
19
  #
18
20
  # @return [Thread]
19
21
  #
20
- def spawn(abort_on_exception: true)
22
+ def spawn(abort_on_exception: false)
21
23
  ::Thread.new(abort_on_exception) do |whether_abort_on_exception|
22
24
  ::Thread.current.abort_on_exception = whether_abort_on_exception
23
25
  ::Thread.current.report_on_exception = true if ::Thread.current.respond_to?(:report_on_exception=)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Ferrum
4
- VERSION = "0.18.0"
4
+ VERSION = "0.20.0"
5
5
  end
data/lib/ferrum/worker.rb CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  require "ferrum/frame/runtime"
4
4
  require "ferrum/interceptable"
5
+ require "ferrum/console"
5
6
 
6
7
  module Ferrum
7
8
  # A dedicated or shared Worker spawned by a page. Unlike {Page} it has no
@@ -26,6 +27,7 @@ module Ferrum
26
27
  @page = self
27
28
  @execution_id = Concurrent::MVar.new
28
29
  @network = Network.new(self)
30
+ @console = Console.new(self)
29
31
 
30
32
  subscribe
31
33
  prepare
@@ -36,6 +38,11 @@ module Ferrum
36
38
  # @return [Network]
37
39
  attr_reader :network
38
40
 
41
+ # Console messages.
42
+ #
43
+ # @return [Console]
44
+ attr_reader :console
45
+
39
46
  # How long to wait for CDP responses and JS evaluation to complete.
40
47
  #
41
48
  # @return [Numeric]
@@ -88,6 +95,7 @@ module Ferrum
88
95
 
89
96
  def subscribe
90
97
  network.subscribe
98
+ console.subscribe
91
99
 
92
100
  on("Runtime.executionContextCreated") do |params|
93
101
  self.execution_id = params.dig("context", "id")
data/lib/ferrum.rb CHANGED
@@ -1,17 +1,20 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "concurrent-ruby"
4
+ require "ferrum/version"
4
5
  require "ferrum/utils/event"
5
6
  require "ferrum/utils/thread"
6
7
  require "ferrum/utils/platform"
7
8
  require "ferrum/utils/elapsed_time"
8
9
  require "ferrum/utils/attempt"
10
+ require "ferrum/utils/deprecate"
9
11
  require "ferrum/errors"
10
12
  require "ferrum/browser"
13
+ require "ferrum/remote_object"
11
14
  require "ferrum/node"
12
15
 
13
16
  #
14
- # Ferrum is a pure Ruby driver for headless Chrome and Firefox. It talks
17
+ # Ferrum is a pure Ruby driver for headless Chrome. It talks
15
18
  # directly to the browser over the Chrome DevTools Protocol (CDP), so it
16
19
  # doesn't depend on Selenium, WebDriver or any other third party gem.
17
20
  #
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ferrum
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.18.0
4
+ version: 0.20.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dmitry Vorotilin
@@ -83,13 +83,17 @@ files:
83
83
  - lib/ferrum/browser/options.rb
84
84
  - lib/ferrum/browser/options/base.rb
85
85
  - lib/ferrum/browser/options/chrome.rb
86
- - lib/ferrum/browser/options/firefox.rb
87
86
  - lib/ferrum/browser/process.rb
87
+ - lib/ferrum/browser/process/killer.rb
88
+ - lib/ferrum/browser/process/output.rb
88
89
  - lib/ferrum/browser/version_info.rb
89
90
  - lib/ferrum/browser/xvfb.rb
90
91
  - lib/ferrum/client.rb
91
92
  - lib/ferrum/client/subscriber.rb
92
93
  - lib/ferrum/client/web_socket.rb
94
+ - lib/ferrum/console.rb
95
+ - lib/ferrum/console/location.rb
96
+ - lib/ferrum/console/message.rb
93
97
  - lib/ferrum/context.rb
94
98
  - lib/ferrum/contexts.rb
95
99
  - lib/ferrum/cookies.rb
@@ -100,10 +104,18 @@ files:
100
104
  - lib/ferrum/frame.rb
101
105
  - lib/ferrum/frame/dom.rb
102
106
  - lib/ferrum/frame/runtime.rb
107
+ - lib/ferrum/frame/runtime/legacy.rb
108
+ - lib/ferrum/frame/script.rb
103
109
  - lib/ferrum/headers.rb
104
110
  - lib/ferrum/interceptable.rb
111
+ - lib/ferrum/isolated_world.rb
105
112
  - lib/ferrum/keyboard.json
106
113
  - lib/ferrum/keyboard.rb
114
+ - lib/ferrum/log.rb
115
+ - lib/ferrum/log/annotated.rb
116
+ - lib/ferrum/log/default.rb
117
+ - lib/ferrum/log/json.rb
118
+ - lib/ferrum/log/paint.rb
107
119
  - lib/ferrum/mouse.rb
108
120
  - lib/ferrum/network.rb
109
121
  - lib/ferrum/network/auth_request.rb
@@ -122,9 +134,11 @@ files:
122
134
  - lib/ferrum/page/stream.rb
123
135
  - lib/ferrum/page/tracing.rb
124
136
  - lib/ferrum/proxy.rb
137
+ - lib/ferrum/remote_object.rb
125
138
  - lib/ferrum/rgba.rb
126
139
  - lib/ferrum/target.rb
127
140
  - lib/ferrum/utils/attempt.rb
141
+ - lib/ferrum/utils/deprecate.rb
128
142
  - lib/ferrum/utils/elapsed_time.rb
129
143
  - lib/ferrum/utils/event.rb
130
144
  - lib/ferrum/utils/platform.rb
@@ -148,14 +162,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
148
162
  requirements:
149
163
  - - ">="
150
164
  - !ruby/object:Gem::Version
151
- version: '3.1'
165
+ version: '3.2'
152
166
  required_rubygems_version: !ruby/object:Gem::Requirement
153
167
  requirements:
154
168
  - - ">="
155
169
  - !ruby/object:Gem::Version
156
170
  version: '0'
157
171
  requirements: []
158
- rubygems_version: 4.0.16
172
+ rubygems_version: 4.0.6
159
173
  specification_version: 4
160
174
  summary: Ruby headless Chrome driver
161
175
  test_files: []
@@ -1,70 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Ferrum
4
- class Browser
5
- class Options
6
- #
7
- # Firefox-specific default flags and binary locations. Provides the CLI
8
- # flags required to drive Firefox over CDP (remote debugger address and
9
- # profile directory) along with its (minimal) set of default flags.
10
- #
11
- class Firefox < Base
12
- DEFAULT_OPTIONS = {
13
- "headless" => nil
14
- }.freeze
15
-
16
- MAC_BIN_PATH = [
17
- "/Applications/Firefox.app/Contents/MacOS/firefox-bin"
18
- ].freeze
19
- LINUX_BIN_PATH = %w[firefox].freeze
20
- WINDOWS_BIN_PATH = [
21
- "C:/Program Files/Firefox Developer Edition/firefox.exe",
22
- "C:/Program Files/Mozilla Firefox/firefox.exe"
23
- ].freeze
24
- PLATFORM_PATH = {
25
- mac: MAC_BIN_PATH,
26
- windows: WINDOWS_BIN_PATH,
27
- linux: LINUX_BIN_PATH
28
- }.freeze
29
-
30
- #
31
- # Merges CLI flags required for Firefox to work with CDP.
32
- #
33
- # @param [Hash] flags
34
- # Flags to merge required ones into.
35
- #
36
- # @param [Ferrum::Browser::Options] options
37
- # Browser options.
38
- #
39
- # @param [String] user_data_dir
40
- # Path to the browser's profile directory.
41
- #
42
- # @return [Hash]
43
- # Merged flags.
44
- #
45
- def merge_required(flags, options, user_data_dir)
46
- flags.merge("remote-debugger" => "#{options.host}:#{options.port}", "profile" => user_data_dir)
47
- end
48
-
49
- #
50
- # Merges Firefox's default flags with the given ones.
51
- #
52
- # @param [Hash] flags
53
- # Flags that take precedence over the defaults.
54
- #
55
- # @param [Ferrum::Browser::Options] options
56
- # Browser options.
57
- #
58
- # @return [Hash]
59
- # Merged flags.
60
- #
61
- def merge_default(flags, options)
62
- defaults = except("headless") unless options.headless
63
-
64
- defaults ||= DEFAULT_OPTIONS
65
- defaults.merge(flags)
66
- end
67
- end
68
- end
69
- end
70
- end