Class: Ferrum::Downloads

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

Overview

Tracks files downloaded by a page. Configures the browser's download behavior/destination via #set_behavior, subscribes to the Browser.downloadWillBegin/Browser.downloadProgress CDP events to record their progress in #files, and lets callers block until the current download finishes via #wait.

Constant Summary collapse

VALID_BEHAVIOR = 
%i[deny allow allowAndName default].freeze

Instance Method Summary collapse

Constructor Details

#initialize(page) ⇒ Downloads

Returns a new instance of Downloads.



14
15
16
17
18
 
# File 'lib/ferrum/downloads.rb', line 14

def initialize(page)
  @page = page
  @event = Utils::Event.new.tap(&:set)
  @files = {}
end

Instance Method Details

#files ⇒ Array<Hash>

Returns information about all downloaded files.

Returns:



25
26
27
 
# File 'lib/ferrum/downloads.rb', line 25

def files
  @files.values
end

#set_behavior(save_path:, behavior: :allow) ⇒ void

This method returns an undefined value.

Sets the browser's download behavior and destination directory.

Parameters:

  • Absolute path to the directory downloads should be saved to.

  • (defaults to: :allow)

    Whether/how to allow downloads.

Raises:



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/ferrum/downloads.rb', line 61

def set_behavior(save_path:, behavior: :allow)
  raise ArgumentError unless VALID_BEHAVIOR.include?(behavior.to_sym)
  raise Error, "supply absolute path for `:save_path` option" unless Pathname.new(save_path.to_s).absolute?

  @page.command("Browser.setDownloadBehavior",
                browserContextId: @page.context_id,
                downloadPath: save_path,
                behavior: behavior,
                eventsEnabled: true)
end

#subscribe ⇒ void

This method returns an undefined value.

Subscribes to download related CDP events.



77
78
79
80
 
# File 'lib/ferrum/downloads.rb', line 77

def subscribe
  subscribe_download_will_begin
  subscribe_download_progress
end

#subscribe_download_progress ⇒ void

This method returns an undefined value.

Subscribes to the Browser.downloadProgress event to track download state.



99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/ferrum/downloads.rb', line 99

def subscribe_download_progress
  @page.on("Browser.downloadProgress") do |params|
    @files[params["guid"]].merge!(params)

    case params["state"]
    when "completed", "canceled"
      @event.set
    else
      @event.reset
    end
  end
end

#subscribe_download_will_begin ⇒ void

This method returns an undefined value.

Subscribes to the Browser.downloadWillBegin event to track new downloads.



87
88
89
90
91
92
 
# File 'lib/ferrum/downloads.rb', line 87

def subscribe_download_will_begin
  @page.on("Browser.downloadWillBegin") do |params|
    @event.reset
    @files[params["guid"]] = params
  end
end

#wait(timeout = 5) { ... } ⇒ void

This method returns an undefined value.

Waits until the current download finishes.

Parameters:

  • (defaults to: 5)

    How long to wait in seconds.

Yields:

  • Optional block that triggers the download, e.g. clicking a link.



40
41
42
43
44
45
 
# File 'lib/ferrum/downloads.rb', line 40

def wait(timeout = 5)
  @event.reset
  yield if block_given?
  @event.wait(timeout)
  @event.set
end