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