Module: Ferrum::Page::Screenshot

Included in:
Ferrum::Page
Defined in:
lib/ferrum/page/screenshot.rb

Overview

Captures screenshots, PDFs, and MHTML snapshots of the page, and exposes viewport/document size helpers used to compute capture areas.

Constant Summary collapse

FULL_WARNING = 
"Ignoring :selector or :area in #screenshot since full: true was given at %s"
AREA_WARNING = 
"Ignoring :area in #screenshot since selector: was given at %s"
DEFAULT_SCREENSHOT_FORMAT = 
"png"
SUPPORTED_SCREENSHOT_FORMAT = 
%w[png jpeg jpg webp].freeze
DEFAULT_RENDER_TIMEOUT = 
60
DEFAULT_PDF_OPTIONS = 
{
  landscape: false,
  paper_width: 8.5,
  paper_height: 11,
  scale: 1.0
}.freeze
PAPER_FORMATS = 
{
  letter: { width: 8.50, height: 11.00 },
  legal: { width: 8.50, height: 14.00 },
  tabloid: { width: 11.00, height: 17.00 },
  ledger: { width: 17.00, height: 11.00 },
  A0: { width: 33.10, height: 46.80 },
  A1: { width: 23.40, height: 33.10 },
  A2: { width: 16.54, height: 23.40 },
  A3: { width: 11.70, height: 16.54 },
  A4: { width:  8.27, height: 11.70 },
  A5: { width:  5.83, height:  8.27 },
  A6: { width:  4.13, height:  5.83 }
}.freeze

Instance Method Summary collapse

Instance Method Details

#device_pixel_ratio ⇒ Float

The ratio of the resolution in physical pixels to the resolution in CSS pixels for the current display device.

Examples:

page.device_pixel_ratio # => 1.0

Returns:

  • (Float) 


195
196
197
198
199
 
# File 'lib/ferrum/page/screenshot.rb', line 195

def device_pixel_ratio
  evaluate "    window.devicePixelRatio\n  JS\nend\n"

#document_size ⇒ (Integer, Integer)

Full size of the document, including the part that is not visible in the viewport.

Examples:

page.document_size # => [1024, 4000]

Returns:

  • ((Integer, Integer)) —

    The scroll width, scroll height of the document.



211
212
213
214
215
216
 
# File 'lib/ferrum/page/screenshot.rb', line 211

def document_size
  evaluate "    [document.documentElement.scrollWidth,\n     document.documentElement.scrollHeight]\n  JS\nend\n"

#mhtml(path: nil) ⇒ Object

Saves MHTML on a disk or returns it as a string.

Examples:

page.go_to("https://google.com/")
page.mhtml(path: "google.mhtml") # => 87742

Parameters:

  • path (String, nil) (defaults to: nil) —

    The path to save a file on the disk.



164
165
166
167
168
169
 
# File 'lib/ferrum/page/screenshot.rb', line 164

def mhtml(path: nil)
  data = command("Page.captureSnapshot", format: :mhtml).fetch("data")
  return data if path.nil?

  save_file(path, data)
end

#pdf(timeout: DEFAULT_RENDER_TIMEOUT, **opts) ⇒ Object

Note:

See other native options you can pass.

Saves PDF on a disk or returns it as Base64.

Examples:

page.go_to("https://google.com/")
# Save to disk as a PDF
page.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true

Parameters:

  • opts (Hash{Symbol => Object})
  • timeout (Numeric) (defaults to: DEFAULT_RENDER_TIMEOUT) —

    How long to wait for the PDF to be generated. Defaults to DEFAULT_RENDER_TIMEOUT since large documents are a known slow outlier among CDP commands.

Options Hash (**opts):

  • :path (String) —

    The path to save a screenshot on the disk. :encoding will be set to :binary automatically.

  • :encoding (:base64, :binary) —

    The encoding the image should be returned in.

  • :landscape (Boolean) — default: false —

    Page orientation.

  • :scale (Float) —

    Zoom in/out.

  • :format (:letter, :legal, :tabloid, :ledger, :A0, :A1, :A2, :A3, :A4, :A5, :A6) —

    The standard paper size.

  • :paper_width (Float) —

    Sets the paper's width.

  • :paper_height (Float) —

    Sets the paper's height.



147
148
149
150
151
152
 
# File 'lib/ferrum/page/screenshot.rb', line 147

def pdf(timeout: DEFAULT_RENDER_TIMEOUT, **opts)
  path, encoding = common_options(**opts)
  options = pdf_options(**opts).merge(transferMode: "ReturnAsStream")
  handle = command("Page.printToPDF", timeout: timeout, **options).fetch("stream")
  stream_to(path: path, encoding: encoding, handle: handle)
end

#screenshot(timeout: DEFAULT_RENDER_TIMEOUT, **opts) ⇒ Object

Saves screenshot on a disk or returns it as base64.

Examples:

page.go_to("https://google.com/")

Save on the disk in PNG:

page.screenshot(path: "google.png") # => 134660

Save on the disk in JPG:

page.screenshot(path: "google.jpg") # => 30902

Save to Base64 in WebP with reduce quality:

page.screenshot(format: "webp", quality: 60) # "iVBORw0KGgoAAAANS...

Save to Base64 the whole page not only viewport and reduce quality:

page.screenshot(full: true, format: "jpeg", quality: 60) # "iVBORw0KGgoAAAANS...

Save with specific background color:

page.screenshot(background_color: Ferrum::RGBA.new(0, 0, 0, 0.0))

Parameters:

  • opts (Hash{Symbol => Object})
  • timeout (Numeric) (defaults to: DEFAULT_RENDER_TIMEOUT) —

    How long to wait for the screenshot to be captured. Defaults to DEFAULT_RENDER_TIMEOUT since a full-page capture is a known slow outlier among CDP commands.

Options Hash (**opts):

  • :path (String) —

    The path to save a screenshot on the disk. :encoding will be set to :binary automatically.

  • :encoding (:base64, :binary) —

    The encoding the image should be returned in.

  • :format ("jpeg", "jpg", "png", "webp") —

    The format the image should be returned in.

  • :quality (Integer) —

    The image quality. Note: 0-100 works for jpeg only.

  • :full (Boolean) —

    Whether you need full page screenshot or a viewport.

  • :selector (String) —

    CSS selector for the given element.

  • :area (Hash) —

    x, y, width, height to screenshot an area.

  • :scale (Float) —

    Zoom in/out.

  • :background_color (Ferrum::RGBA) —

    Sets the background color.



96
97
98
99
100
101
102
103
104
 
# File 'lib/ferrum/page/screenshot.rb', line 96

def screenshot(timeout: DEFAULT_RENDER_TIMEOUT, **opts)
  path, encoding = common_options(**opts)
  options = screenshot_options(path, **opts)
  data = capture_screenshot(options, opts[:full], opts[:background_color], timeout)
  return data if encoding == :base64

  bin = Base64.decode64(data)
  save_file(path, bin)
end

#viewport_size ⇒ (Integer, Integer)

Current viewport size.

Examples:

page.viewport_size # => [1024, 768]

Returns:

  • ((Integer, Integer)) —

    The width, height of the viewport.



180
181
182
183
184
 
# File 'lib/ferrum/page/screenshot.rb', line 180

def viewport_size
  evaluate "    [window.innerWidth, window.innerHeight]\n  JS\nend\n"