webkit_remote 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,16 @@
+source 'http://rubygems.org'
+gem 'eventmachine', '>= 1.0.0'
+gem 'faye-websocket', '>= 0.4.6'
+gem 'posix-spawn', '>= 0.3.6'
+
+group :development do
+  gem 'bundler', '>= 1.2.1'
+  gem 'jeweler', '>= 1.8.4'
+  gem 'minitest', '>= 4.1.0'
+  gem 'puma', '>= 1.6.3'
+  gem 'rack', '>= 1.4.1'
+  gem 'rdoc', '>= 3.12'
+  gem 'ruby-prof', '>= 0.11.2'
+  gem 'simplecov', '>= 0.7.1'
+  gem 'yard', '>= 0.8.3'
+end

data/Gemfile.lock

@@ -0,0 +1,45 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    eventmachine (1.0.0)
+    faye-websocket (0.4.6)
+      eventmachine (>= 0.12.0)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    minitest (4.1.0)
+    multi_json (1.3.6)
+    posix-spawn (0.3.6)
+    puma (1.6.3)
+      rack (~> 1.2)
+    rack (1.4.1)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    ruby-prof (0.11.2)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.2.1)
+  eventmachine (>= 1.0.0)
+  faye-websocket (>= 0.4.6)
+  jeweler (>= 1.8.4)
+  minitest (>= 4.1.0)
+  posix-spawn (>= 0.3.6)
+  puma (>= 1.6.3)
+  rack (>= 1.4.1)
+  rdoc (>= 3.12)
+  ruby-prof (>= 0.11.2)
+  simplecov (>= 0.7.1)
+  yard (>= 0.8.3)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Victor Costan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,114 @@
+# webkit_remote
+
+Ruby gem for driving
+[Google Chrome](https://www.google.com/chrome/) and possibly other
+WebKit-based browsers via the
+[WebKit remote debugging protocol](https://www.webkit.org/blog/1875/announcing-remote-debugging-protocol-v1-0/).
+
+
+## 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.
+
+
+## Installation
+
+Use RubyGems.
+
+```bash
+gem install webkit_remote
+```
+
+
+## Usage
+
+This section only showcases a few features. Read the
+[latest gem release YARD docs](http://rubydoc.info/gems/webkit_remote)
+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](https://developers.google.com/chrome/mobile/docs/debugging).
+
+### Load a Page
+
+```ruby
+client.page_events = true
+client.navigate_to 'http://translate.google.com'
+client.wait_for type: WebkitRemote::Event::PageLoaded
+```
+
+### 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 JavaScript objects that the debugger is holding onto.
+
+```ruby
+element.group.release_all
+```
+
+### Clean Up
+
+```ruby
+client.close
+```
+
+closes the debugging connection and shuts down the Google Chrome instance.
+
+
+## Contributing
+
+* 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.
+

data/Rakefile

@@ -0,0 +1,38 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "webkit_remote"
+  gem.homepage = "http://github.com/pwnall/webkit_remote"
+  gem.license = "MIT"
+  gem.summary = %Q{Client for the Webkit Remote Debugging server}
+  gem.description = %Q{Launches Google Chrome instances and controls them via the Remote Debugging server}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/webkit_remote/browser.rb

@@ -0,0 +1,150 @@
+require 'json'
+require 'net/http'
+
+module WebkitRemote
+
+# The master connection to the remote debugging server in a Webkit process.
+class Browser
+  # Sets up a debugging connection to a Webkit processr.
+  #
+  # @param [Hash] opts info on the browser to connect to
+  # @option opts [String] host the hostname / IP address of the Webkit remote
+  #     debugging server
+  # @option opts [Integer] port the port that the Webkit remote debugging
+  #     server listens to
+  # @option opts [WebkitRemote::Process] process a process on the local machine
+  #     to connect to; the process will automatically be stopped when the
+  #     debugging connection is closed; the host and port will be configured
+  #     automatically
+  # @option opts [Boolean] stop_process if true, the WebkitRemote::Process
+  #     passed to the constructor will be automatically stopped
+  # @raise [SystemCallError] if the connection could not be established; this
+  #     most likely means that there is no remote debugging server at the given
+  #     host / port
+  def initialize(opts = {})
+    if opts[:process]
+      @process = opts[:process]
+      @stop_process = opts.fetch :stop_process, false
+      @host = 'localhost'
+      @port = process.port
+    else
+      @process = nil
+      @stop_process = false
+      @host = opts[:host] || 'localhost'
+      @port = opts[:port] || 9292
+    end
+    @closed = false
+
+    @http = Net::HTTP.start @host, @port
+  end
+
+  # Closes the connection the browser.
+  #
+  # If the Browser instance was given a WebkitRemote::Process, the process will
+  # also be stopped. This instance becomes useless after closing.
+  #
+  # @return [WebkitRemote::Browser] self
+  def close
+    return self if @closed
+    @closed = true
+    @http.finish
+    @http = nil
+    @process.stop if @stop_process
+    self
+  end
+
+  # Retrieves the tabs that are currently open in the browser.
+  #
+  # These tabs can be used to start debugging.
+  #
+  # @return [Array<WebkitRemote::Browser::Tab>] the open tabs
+  def tabs
+    http_response = @http.request Net::HTTP::Get.new('/json')
+    tabs = JSON.parse(http_response.body).map do |json_tab|
+      title = json_tab['title']
+      url = json_tab['url']
+      debug_url = json_tab['webSocketDebuggerUrl']
+      Tab.new self, debug_url, title: title, url: url
+    end
+  end
+
+  # @return [Boolean] if true, a WebkitRemote::Process will be stopped when
+  #     this browser connection is closed
+  attr_reader :stop_process
+  alias_method :stop_process?, :stop_process
+
+  # Changes the automated WebkitRemote::Process stopping behavior.
+  #
+  # This should only be set to true if this Browser instance was given a
+  # WebkitRemote::Process at creation time.
+  #
+  # @param [Boolean] new_stop_process if true, the WebkitRemote::Process
+  #     passed to this instance's constructor will be stopped when this
+  #     connection is closed
+  # @return [Boolean] new_stop_process
+  def stop_process=(new_stop_process)
+    if new_stop_process
+      unless @process
+        raise ArgumentError, "Browser instance not backed by a Webkit process"
+      end
+      @stop_process = true
+    else
+      @stop_process = false
+    end
+    new_stop_process
+  end
+
+  # @return [WebkitRemote::Process, nil] Process instance passed to this
+  #     connection's constructor
+  attr_reader :process
+
+  # @return [String] hostname or IP of the Webkit remote debugging server
+  attr_reader :host
+
+  # @return [Integer] port that the Webkit remote debugging server listens on
+  attr_reader :port
+
+  # @return [Boolean] if true, the connection to the remote debugging server
+  #     has been closed, and this instance is mostly useless
+  attr_reader :closed
+  alias_method :closed?, :closed
+
+  # Clean up when garbage collected.
+  def finalize
+    close unless @closed
+  end
+
+# References a tab open in a Webkit process with a remote debugging server.
+class Tab
+  # @return [Webkit::Remote] connection to the browser that this tab belongs to
+  attr_reader :browser
+
+  # @return [String] URL of the tab's remote debugging endpoint
+  attr_reader :debug_url
+
+  # @return [String, nil] title of the Web page open in the browser tab
+  attr_reader :title
+
+  # @return [String, nil] URL of the Web page open in the browser tab
+  attr_reader :url
+
+  # Creates a tab reference.
+  #
+  # @param [WebkitRemote::Browser] browser the master debugging connection to
+  #     the Webkit process
+  # @param [String] debug_url URL of the tab's remote debugging endpoint
+  # @param [Hash] metadata non-essential information about the tab
+  # @option metadata [String, nil] title title of the page open in the browser
+  #     tab
+  # @option metadata [String, nil] url URL of the page open in the browser tab
+  def initialize(browser, debug_url, metadata)
+    @browser = browser
+    @debug_url = debug_url
+    @title = metadata[:title]
+    @url = metadata[:url]
+  end
+end  # class WebkitRemote::Browser::Tab
+
+end  # class WebkitRemote::Browser
+
+end  # namespace WebkitRemote

data/lib/webkit_remote/client/page.rb

@@ -0,0 +1,59 @@
+module WebkitRemote
+
+class Client
+
+# API for the Page domain.
+module Page
+  # Loads a new URL into the tab under debugging.
+  #
+  # @param [String] url the URL to be loaded into the tab
+  # @return [WebkitRemote::Client] self
+  def navigate_to(url)
+    @rpc.call 'Page.navigate', url: url
+    self
+  end
+
+  # Reloads
+  #
+  # @param [Hash] opts quirky behavior bits
+  # @option opts [Boolean] skip_cache if true, the cache is not used; this is
+  #     what happens when the user presses Shift+refresh
+  # @option opts [String] onload a JavaScript that will be injected in all the
+  #     page's frames after reloading
+  # @return [WebkitRemote::Client] self
+  def refresh(opts = {})
+    options = {}
+    options[:ignoreCache] = true if opts[:skip_cache]
+    options[:scriptToEvaluateOnLoad] = opts[:onload] if opts[:onload]
+    @rpc.call 'Page.refresh', options
+    self
+  end
+
+  # Enables or disables the generation of events in the Page domain.
+  #
+  # @param [Boolean] new_page_events if true, the browser debugger will
+  #     generate Page.* events
+  def page_events=(new_page_events)
+    if !!new_page_events != page_events
+      @page_events = !!new_page_events
+      @rpc.call(@page_events ? 'Page.enable' : 'Page.disable')
+    end
+    new_page_events
+  end
+
+  # @return [Boolean] true if the debugger generates Page.* events
+  attr_reader :page_events
+
+  # @private Called by the Client constructor to set up Page data structures.
+  def initialize_page
+    @page_events = nil
+  end
+
+end  # module WebkitRemote::Client::Page
+
+initializer :initialize_page
+include WebkitRemote::Client::Page
+
+end  # namespace WebkitRemote::Client
+
+end  # namespace WebkitRemote