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


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.


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 can be used in a headless environment with Xvfb.

Install Xvfb on Fedora.

bash sudo yum install xorg-x11-server-Xvfb

Install Xvfb on Ubuntu.

bash sudo apt-get install xvfb

Xvfb is included in OSX.


Use RubyGems.

bash gem install webkit_remote


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

Session Setup

ruby 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,

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

connects to a remote WebKit instance running on a phone.

Load a Page

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

Run JavaScript

Evaluate some JavaScript.

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

Take a look at the result.

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

Pass an object to some JavaScript code.

ruby 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.

ruby client.clear_all

Read the Console

Produce some console output.

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

Take a look at it.

ruby 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.

ruby client.clear_all

See Network Traffic

Record network requests and reload the page.

ruby 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.

ruby 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.

ruby client.clear_all

Explore the DOM

Find a node and inspect its attributes.

ruby 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.

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

Close the Browser

ruby client.close

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


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 (c) 2012 Victor Costan. See LICENSE.txt for further details.