ferrum 0.19.2 → 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 (41) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +60 -0
  3. data/lib/ferrum/browser/binary.rb +1 -2
  4. data/lib/ferrum/browser/options.rb +33 -12
  5. data/lib/ferrum/browser/process/output.rb +143 -0
  6. data/lib/ferrum/browser/process.rb +42 -69
  7. data/lib/ferrum/browser.rb +9 -23
  8. data/lib/ferrum/client/web_socket.rb +4 -15
  9. data/lib/ferrum/client.rb +1 -1
  10. data/lib/ferrum/console/location.rb +42 -0
  11. data/lib/ferrum/console/message.rb +230 -0
  12. data/lib/ferrum/console.rb +157 -0
  13. data/lib/ferrum/context.rb +23 -15
  14. data/lib/ferrum/contexts.rb +41 -18
  15. data/lib/ferrum/errors.rb +7 -5
  16. data/lib/ferrum/frame/dom.rb +50 -44
  17. data/lib/ferrum/frame/runtime/legacy.rb +336 -0
  18. data/lib/ferrum/frame/runtime.rb +416 -186
  19. data/lib/ferrum/frame/script.rb +289 -0
  20. data/lib/ferrum/frame.rb +33 -4
  21. data/lib/ferrum/interceptable.rb +19 -9
  22. data/lib/ferrum/isolated_world.rb +94 -0
  23. data/lib/ferrum/keyboard.rb +95 -8
  24. data/lib/ferrum/log/annotated.rb +77 -0
  25. data/lib/ferrum/log/default.rb +55 -0
  26. data/lib/ferrum/log/json.rb +32 -0
  27. data/lib/ferrum/log/paint.rb +28 -0
  28. data/lib/ferrum/log.rb +247 -0
  29. data/lib/ferrum/mouse.rb +16 -8
  30. data/lib/ferrum/node.rb +127 -52
  31. data/lib/ferrum/page/frames.rb +10 -3
  32. data/lib/ferrum/page/screenshot.rb +8 -7
  33. data/lib/ferrum/page.rb +106 -53
  34. data/lib/ferrum/proxy.rb +8 -7
  35. data/lib/ferrum/remote_object.rb +75 -0
  36. data/lib/ferrum/target.rb +7 -0
  37. data/lib/ferrum/utils/deprecate.rb +77 -0
  38. data/lib/ferrum/version.rb +1 -1
  39. data/lib/ferrum/worker.rb +8 -0
  40. data/lib/ferrum.rb +3 -0
  41. metadata +16 -2
@@ -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
@@ -55,6 +55,9 @@ module Ferrum
55
55
  # Connects to and returns this target's {Worker}.
56
56
  #
57
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}.
58
61
  def worker
59
62
  @worker ||= build_worker
60
63
  end
@@ -82,6 +85,10 @@ module Ferrum
82
85
  #
83
86
  # @return [Worker]
84
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
+
85
92
  Worker.new(client, target_id: id, url: url)
86
93
  end
87
94
 
@@ -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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Ferrum
4
- VERSION = "0.19.2"
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,13 +1,16 @@
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
  #
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.19.2
4
+ version: 0.20.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dmitry Vorotilin
@@ -85,11 +85,15 @@ files:
85
85
  - lib/ferrum/browser/options/chrome.rb
86
86
  - lib/ferrum/browser/process.rb
87
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,7 +162,7 @@ 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
  - - ">="