123456789_123456789_123456789_123456789_123456789_

Class: Selenium::WebDriver::AccessibilitySnapshotter Private

Relationships & Source Files
Namespace Children
Exceptions:
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Atoms
Inherits: Object
Defined in: rb/lib/selenium/webdriver/common/accessibility_snapshot.rb

Overview

Takes accessibility snapshots for one BiDi session: runs the atom's wire entry in the sandbox realm of each document and stitches child frames into the tree.

Constant Summary

Class Method Summary

Instance Method Summary

Atoms - Included

Constructor Details

.new(bridge) ⇒ AccessibilitySnapshotter

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 221

def initialize(bridge)
  @bridge = bridge
  @bidi = bridge.bidi
end

Instance Method Details

#atom (private)

The atom's wire entry, a JavaScript function expression, read once from the gem.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 342

def atom
  @atom ||= read_atom(:accessibilitySnapshot)
end

#call(context, arguments) (private)

Runs the atom's wire entry in the sandbox of context and returns the remote value of its result.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 279

def call(context, arguments)
  raw = @bidi.send_cmd('script.callFunction',
                       functionDeclaration: "(interestingOnly, root) => (#{atom})(root, {interestingOnly})",
                       awaitPromise: false,
                       target: {context: context, sandbox: SANDBOX},
                       arguments: arguments,
                       resultOwnership: 'none',
                       serializationOptions: SERIALIZATION_OPTIONS)
  return raw['result'] || {} unless raw['type'] == 'exception'

  details = raw['exceptionDetails'] || {}
  raise Error::WebDriverError, "accessibility snapshot failed in the page: #{details['text'] || details}"
rescue Error::WebDriverError => e
  # The BiDi "no such node" error: the document of this context does not own the
  # root's shared id, either because the root lives in another frame or because
  # its document is gone.
  raise NotOwnedError, e.message if e.message.include?('no such node')

  raise
end

#contexts(top) (private)

The window's browsing contexts, top-level first, then each frame depth-first.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 322

def contexts(top)
  tree = @bidi.send_cmd('browsingContext.getTree', root: top)
  contexts = [top]
  stack = tree['contexts'] || []
  until stack.empty?
    info = stack.shift
    contexts << info['context'] unless info['context'] == top
    stack = (info['children'] || []) + stack
  end
  contexts
end

#element(shared_id) (private)

Through the bridge's configured element class, as every other element lookup.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 317

def element(shared_id)
  Remote::Bridge.element_class.new(@bridge, shared_id)
end

#frame_unreachable?(error) ⇒ Boolean (private)

Whether an error says a frame or its document is gone, rather than that a command failed.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 335

def frame_unreachable?(error)
  return true if error.is_a?(NotOwnedError)

  error.message.include?('no such frame') || error.message.include?('no such node')
end

#snapshot(root = nil, interesting_only: true) ⇒ AccessibilityNode

Snapshots the whole page, or the subtree under Selenium::WebDriver.root.

Parameters:

  • root (Element, nil) (defaults to: nil) —

    the element whose subtree to snapshot, or nil for the page of the current window's top-level browsing context

Returns:

  • (AccessibilityNode) —

    the snapshot, with every reachable child frame's tree attached under its iframe node

Raises:

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 236

def snapshot(root = nil, interesting_only: true)
  top = @bridge.window_handle
  if root.nil?
    node = snapshot_context(top, nil, interesting_only)
    raise Error::WebDriverError, 'accessibility snapshot: the script returned nothing' if node.nil?

    return node
  end

  # The element may live in any frame of the window. Chromium resolves its shared
  # id only in the document that owns it; Firefox resolves it in any document of
  # the browsing context group, so the atom checks ownership itself and each
  # context is tried until the owner is found.
  contexts(top).each do |context|
    node = snapshot_context(context, root.ref.last, interesting_only)
    return node unless node.nil?
  rescue NotOwnedError
    next
  end
  raise Error::StaleElementReferenceError, STALE_MESSAGE
end

#snapshot_context(context, root_id, interesting_only = true) (private)

The snapshot of context, or nil when another document owns the root. The interestingOnly flag goes first, so a whole-page call sends no placeholder for a root.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 262

def snapshot_context(context, root_id, interesting_only = true)
  arguments = [{type: 'boolean', value: interesting_only}]
  arguments << {sharedId: root_id} if root_id
  result = call(context, arguments)
  return nil if result['type'] == 'null'

  fields = AccessibilityNode::Wire.object_fields(result)
  # The only error the atom reports as data: the root left its document.
  raise Error::StaleElementReferenceError, STALE_MESSAGE if fields.key?('error')

  elements = fields.fetch('elements').fetch('value', []).map { |node| element(AccessibilityNode::Wire.shared_id(node)) }
  windows = fields.fetch('windows').fetch('value', []).map { |window| AccessibilityNode::Wire.context_of(window) }
  data = JSON.parse(AccessibilityNode::Wire.string(fields.fetch('json')))
  AccessibilityNode.from_wire(data, elements) { |index| stitch(windows.fetch(index), interesting_only) }
end

#stitch(context, interesting_only) (private)

The document of a frame as the frame node's one child, or no children when unreachable.

[ GitHub ]

  
# File 'rb/lib/selenium/webdriver/common/accessibility_snapshot.rb', line 301

def stitch(context, interesting_only)
  return [] if context.nil?

  document = snapshot_context(context, nil, interesting_only)
  document.nil? ? [] : [document]
rescue Error::WebDriverError => e
  # Gone between discovery and the call, or mid-navigation: the frame stays a
  # leaf (ADR §1). Anything else is a real failure.
  raise unless frame_unreachable?(e)

  WebDriver.logger.debug("accessibility snapshot: frame #{context} not reachable: #{e.message}",
                         id: :accessibility_snapshot)
  []
end