webkit_remote

webkit_remote

Ruby gem for driving Google Chrome and possibly other WebKit-based browsers via the WebKit remote debugging protocol.

Features

This gem can be used to test Web pages in real browsers with minimal intrusion.

Compared to PhantomJS, webkit_remote tests will take longer, but provide assurance that the code will run as intended on desktop and mobile browsers, and can exercise HTML5 features that are not yet supported by Phantom.

Compared to Selenium, webkit_remote is less mature, and only supports WebKit-based browsers. In return, the gem can support (either directly or via extensions) features that have not made their way into Selenium's WebDriver.

Currently, the following sections of the WebKit remote debugging protocol have been implemented:

• Console
• DOM (incomplete)
• Input
• Network
• Page
• Remote

This gem will only support officially released remote debugging protocol features. If you need to use an unsupported feature, such as CSS debugging, take a look at the webkit_remote_unstable gem.

Requirements

The gem is tested against the OSX and Linux builds of Google Chrome. The only platform-dependent functionality is launching and shutting down the browser process, everything else should work for any WebKit-based browser that implements the remote debugging protocol.

Google Chrome 60 and above can be used in headless mode.

Installation

Use RubyGems.

gem install webkit_remote

Usage

This section only showcases a few features. Read the YARD docs to see everything this gem has to offer.

Session Setup

client = WebkitRemote.local

launches a separate instance of Google Chrome that is not connected to your profile, and sets up a connection to it. Alternatively,

client = WebkitRemote.remote host: 'phone-ip-here', port: 9222

connects to a remote WebKit instance running on a phone.

Load a Page

client.page_events = true
client.navigate_to 'http://translate.google.com'
client.wait_for(type: WebkitRemote::Event::PageLoaded).last

Run JavaScript

Evaluate some JavaScript.

element = client.remote_eval 'document.querySelector("[name=text]")'

Take a look at the result.

element.js_class_name
element.description
element.properties[:tagName].value
element.properties[:tagName].writable?

Pass an object to some JavaScript code.

js_code = <<END_JS
function(element, value) {
  element.value = value;
  return "Check the browser window";
}
END_JS
client.remote_eval('window').bound_call js_code, element, '你好'

Finally, release the WebKit state that the debugger is holding onto.

client.clear_all

Read the Console

Produce some console output.

client.console_events = true
client.remote_eval '(function() { console.warn("hello ruby"); })();'

Take a look at it.

client.wait_for type: WebkitRemote::Event::ConsoleMessage
message = client.console_messages.first
message.text
message.level
message.params
message.stack_trace

Again, release the WebKit state.

client.clear_all

See Network Traffic

Record network requests and reload the page.

client.page_events = true
client.network_events = true
client.clear_cache
client.clear_cookies
client.navigate_to 'http://translate.google.com'
client.wait_for(type: WebkitRemote::Event::PageLoaded).last

See the network traffic generated by the page.

client.network_resources.length
resource = client.network_resources.first
resource.canceled
resource.type
resource.request.url
resource.request.headers
resource.response.mime_type
resource.response.url
resource.response.status
resource.response.headers
resource.body

Clean up.

client.clear_all

Explore the DOM

Find a node and inspect its attributes.

node = client.dom_root.query_selector '[name=text]'
node.attributes['name']
node.attributes['id']

Get the JavaScript DOM object for the node and explore its properties.

node.js_object.properties['nodeName'].value

Close the Browser

client.close

closes the debugging connection and shuts down the Google Chrome instance.

Contributing

Please contribute support for stable features to webkit_remote and support for unstable features at webkit_remote_unstable.

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2012 Victor Costan. See LICENSE.txt for further details.