poltergeist 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jonathan Leighton
+
+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.md

@@ -0,0 +1,85 @@
+# Poltergeist - A PhantomJS driver for Capybara #
+
+Version: 0.1.0
+
+Poltergeist is a driver for [Capybara](https://github.com/jnicklas/capybara). It allows you to
+run your Capybara tests on a headless [WebKit](http://webkit.org) browser,
+provided by [PhantomJS](http://www.phantomjs.org/).
+
+## Installation ##
+
+Add `poltergeist` to your Gemfile, and add `Capybara.javascript_driver = :poltergeist`
+in your test setup.
+
+You will also need PhantomJS 1.3+ on your system.
+[Here's how to do that](http://code.google.com/p/phantomjs/wiki/BuildInstructions).
+
+Currently PhantomJS is not 'truly headless', so to run it on a continuous integration
+server you will need to use [Xvfb](http://en.wikipedia.org/wiki/Xvfb). You can either use the
+[headless gem](https://github.com/leonid-shevtsov/headless) for this,
+or make sure that Xvfb is running and the `DISPLAY` environment variable is set.
+
+## What's supported? ##
+
+Poltergeist supports basically everything that is supported by the stock Selenium driver,
+including Javascript, drag-and-drop, etc.
+
+Additionally, you can grab screenshots of the page at any point by calling
+`page.driver.render('/path/to/file.png')` (this works the same way as the PhantomJS
+render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
+
+## Customisation ##
+
+You can customise the way that Capybara sets up Poltegeist via the following code in your
+test setup:
+
+    Capybara.register_driver :poltergeist do |app|
+      Capybara::Poltergeist::Driver.new(app, options)
+    end
+
+`options` is a hash of options. The following options are supported:
+
+  * `:phantomjs` (String) - A custom path to the phantomjs executable
+  * `:debug` (Boolean) - When true, debug output is logged to `STDERR`
+  * `:logger` (Object responding to `puts`) - When present, debug output is written to this object
+
+## Bugs ##
+
+Please file bug reports on Github and include example code to reproduce the problem wherever
+possible. (Tests are even better.)
+
+## Why not use [capybara-webkit](https://github.com/thoughtbot/capybara-webkit)? ##
+
+If capybara-webkit works for you, then by all means carry on using it.
+
+However, I have had some trouble with it, and Poltergeist basically started
+as an experiment to see whether a PhantomJS driver was possible. (It turned out it
+was, but only thanks to some new features in the recent 1.3.0 release.)
+
+In the long term, I think having a PhantomJS driver makes sense, because that allows
+PhantomJS to concentrate on being an awesome headless browser, while the capybara driver
+(Poltergeist) is able to be the minimal amount of glue code necessary to drive the
+browser.
+
+## License ##
+
+Copyright (c) 2011 Jonathan Leighton
+
+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/lib/capybara/poltergeist/browser.rb

@@ -0,0 +1,130 @@
+require 'json'
+
+module Capybara::Poltergeist
+  class Browser
+    attr_reader :options, :server, :client
+
+    def initialize(options = {})
+      @options = options
+      @server  = Server.new
+      @client  = Client.new(server.port, options[:phantomjs])
+    end
+
+    def restart
+      server.restart
+      client.restart
+    end
+
+    def visit(url, attributes = {})
+      command 'visit', url
+    end
+
+    def current_url
+      command 'current_url'
+    end
+
+    def body
+      command 'body'
+    end
+
+    def source
+      command 'source'
+    end
+
+    def find(selector, id = nil)
+      command 'find', selector, id
+    end
+
+    def text(id)
+      command 'text', id
+    end
+
+    def attribute(id, name)
+      command 'attribute', id, name
+    end
+
+    def value(id)
+      command 'value', id
+    end
+
+    def set(id, value)
+      command 'set', id, value
+    end
+
+    def select_file(id, value)
+      command 'select_file', id, value
+    end
+
+    def tag_name(id)
+      command('tag_name', id).downcase
+    end
+
+    def visible?(id)
+      command 'visible', id
+    end
+
+    def evaluate(script)
+      command 'evaluate', script
+    end
+
+    def execute(script)
+      command 'execute', script
+    end
+
+    def within_frame(id, &block)
+      command 'push_frame', id
+      yield
+      command 'pop_frame'
+    end
+
+    def reset
+      visit('about:blank')
+    end
+
+    def click(id)
+      command 'click', id
+    end
+
+    def drag(id, other_id)
+      command 'drag', id, other_id
+    end
+
+    def select(id, value)
+      command 'select', id, value
+    end
+
+    def trigger(id, event)
+      command 'trigger', id, event
+    end
+
+    def reset
+      command 'reset'
+    end
+
+    def render(path)
+      command 'render', path
+    end
+
+    def logger
+      options[:logger]
+    end
+
+    def log(message)
+      logger.puts message if logger
+    end
+
+    def command(name, *args)
+      message = { 'name' => name, 'args' => args }
+      log message.inspect
+
+      json = JSON.parse(server.send(JSON.generate(message)))
+      log json.inspect
+
+      if json['error']
+        raise BrowserError.new(json['error'])
+      else
+        json['response']
+      end
+    end
+  end
+end

data/lib/capybara/poltergeist/client/agent.coffee

@@ -0,0 +1,175 @@
+# This is injected into each page that is loaded
+
+class PoltergeistAgent
+  constructor: ->
+    @elements = []
+    @nodes    = {}
+    @windows  = []
+    this.pushWindow(window)
+
+  pushWindow: (new_window) ->
+    @windows.push(new_window)
+
+    @window   = new_window
+    @document = @window.document
+
+  popWindow: ->
+    @windows.pop()
+
+    @window   = @windows[@windows.length - 1]
+    @document = @window.document
+
+  pushFrame: (id) ->
+    this.pushWindow @document.getElementById(id).contentWindow
+
+  popFrame: ->
+    this.popWindow()
+
+  currentUrl: ->
+    window.location.toString()
+
+  find: (selector, id) ->
+    context = if id? then @elements[id] else @document
+    results = @document.evaluate(selector, context, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
+    ids     = []
+
+    for i in [0...results.snapshotLength]
+      ids.push(this.register(results.snapshotItem(i)))
+
+    ids
+
+  register: (element) ->
+    @elements.push(element)
+    @elements.length - 1
+
+  documentSize: ->
+    height: @document.documentElement.scrollHeight,
+    width:  @document.documentElement.scrollWidth
+
+  get: (id) ->
+    @nodes[id] or= new PoltergeistAgent.Node(this, @elements[id])
+
+  nodeCall: (id, name, arguments) ->
+    node = this.get(id)
+    node[name].apply(node, arguments)
+
+class PoltergeistAgent.Node
+  @EVENTS = {
+    FOCUS: ['blur', 'focus', 'focusin', 'focusout'],
+    MOUSE: ['click', 'dblclick', 'mousedown', 'mouseenter', 'mouseleave', 'mousemove',
+            'mouseover', 'mouseout', 'mouseup']
+  }
+
+  constructor: (@agent, @element) ->
+
+  parentId: ->
+    @agent.register(@element.parentNode)
+
+  isObsolete: ->
+    obsolete = (element) =>
+      if element.parentNode?
+        if element.parentNode == @agent.document
+          false
+        else
+          obsolete element.parentNode
+      else
+        true
+    obsolete @element
+
+  changed: ->
+    event = document.createEvent('HTMLEvents')
+    event.initEvent("change", true, false)
+    @element.dispatchEvent(event)
+
+  text: ->
+    @element.textContent
+
+  getAttribute: (name) ->
+    if name == 'checked' || name == 'selected'
+      @element[name]
+    else
+      @element.getAttribute(name)
+
+  value: ->
+    if @element.tagName == 'SELECT' && @element.multiple
+      option.value for option in @element.children when option.selected
+    else
+      @element.value
+
+  set: (value) ->
+    if (@element.maxLength >= 0)
+      value = value.substr(0, @element.maxLength)
+
+    @element.value = value
+    this.changed()
+
+  isMultiple: ->
+    @element.multiple
+
+  setAttribute: (name, value) ->
+    @element.setAttribute(name, value)
+
+  removeAttribute: (name) ->
+    @element.removeAttribute(name)
+
+  select: (value) ->
+    if value == false && !@element.parentNode.multiple
+      false
+    else
+      @element.selected = value
+      this.changed()
+      true
+
+  tagName: ->
+    @element.tagName
+
+  elementVisible: (element) ->
+
+  isVisible: (id) ->
+    visible = (element) ->
+      if @window.getComputedStyle(element).display == 'none'
+        false
+      else if element.parentElement
+        visible element.parentElement
+      else
+        true
+    visible @element
+
+  position: (id) ->
+    pos = (element) ->
+      x = element.offsetLeft
+      y = element.offsetTop
+
+      if element.offsetParent
+        parentPos = pos(element.offsetParent)
+
+        x += parentPos.x
+        y += parentPos.y
+
+      { x: x, y: y }
+    pos @element
+
+  trigger: (name) ->
+    if Node.EVENTS.MOUSE.indexOf(name) != -1
+      event = document.createEvent('MouseEvent')
+      event.initMouseEvent(
+        name, true, true, @agent.window, 0, 0, 0, 0, 0,
+        false, false, false, false, 0, null
+      )
+    else if Node.EVENTS.FOCUS.indexOf(name) != -1
+      event = document.createEvent('HTMLEvents')
+      event.initEvent(name, true, true)
+    else
+      throw "Unknown event"
+
+    @element.dispatchEvent(event)
+
+window.__poltergeist = new PoltergeistAgent
+
+document.addEventListener(
+  'DOMContentLoaded',
+  -> console.log('__DOMContentLoaded')
+)
+
+# Important to return true here - Phantom seems to choke otherwise
+true

data/lib/capybara/poltergeist/client/browser.coffee

@@ -0,0 +1,121 @@
+class Poltergeist.Browser
+  constructor: (@owner) ->
+    @awaiting_response = false
+    this.resetPage()
+
+  resetPage: ->
+    @page.release() if @page?
+
+    @page = new Poltergeist.WebPage
+    @page.onLoadFinished = (status) =>
+      if @awaiting_response
+        @owner.sendResponse(status)
+        @awaiting_response = false
+
+  visit: (url) ->
+    @awaiting_response = true
+    @page.open(url)
+
+  current_url: ->
+    @owner.sendResponse @page.currentUrl()
+
+  body: ->
+    @owner.sendResponse @page.content()
+
+  source: ->
+    @owner.sendResponse @page.source()
+
+  find: (selector, id) ->
+    @owner.sendResponse @page.find(selector, id)
+
+  text: (id) ->
+    @owner.sendResponse @page.get(id).text()
+
+  attribute: (id, name) ->
+    @owner.sendResponse @page.get(id).getAttribute(name)
+
+  value: (id) ->
+    @owner.sendResponse @page.get(id).value()
+
+  set: (id, value) ->
+    @page.get(id).set(value)
+    @owner.sendResponse(true)
+
+  # PhantomJS only allows us to reference the element by CSS selector, not XPath,
+  # so we have to add an attribute to the element to identify it, then remove it
+  # afterwards.
+  #
+  # PhantomJS does not support multiple-file inputs, so we have to blatently cheat
+  # by temporarily changing it to a single-file input. This obviously could break
+  # things in various ways, which is not ideal, but it works in the simplest case.
+  select_file: (id, value) ->
+    element = @page.get(id)
+
+    multiple = element.isMultiple()
+
+    element.removeAttribute('multiple') if multiple
+    element.setAttribute('_poltergeist_selected', '')
+
+    @page.uploadFile('[_poltergeist_selected]', value)
+
+    element.removeAttribute('_poltergeist_selected')
+    element.setAttribute('multiple', 'multiple') if multiple
+
+    @owner.sendResponse(true)
+
+  select: (id, value) ->
+    @owner.sendResponse @page.get(id).select(value)
+
+  tag_name: (id) ->
+    @owner.sendResponse @page.get(id).tagName()
+
+  visible: (id) ->
+    @owner.sendResponse @page.get(id).isVisible()
+
+  evaluate: (script) ->
+    @owner.sendResponse @page.evaluate("function() { return #{script} }")
+
+  execute: (script) ->
+    @page.execute("function() { return #{script} }")
+    @owner.sendResponse(true)
+
+  push_frame: (id) ->
+    @page.pushFrame(id)
+    @owner.sendResponse(true)
+
+  pop_frame: ->
+    @page.popFrame()
+    @owner.sendResponse(true)
+
+  click: (id) ->
+    # Detect if the click event triggers a page load. If it does, don't send
+    # a response here, because the response will be sent once the page has loaded.
+    @page.onLoadStarted = => @awaiting_response = true
+
+    @page.get(id).click()
+
+    # Use a timeout in order to let the stack clear, so that the @page.onLoadStarted
+    # callback can (possibly) fire, before we decide whether to send a response.
+    setTimeout(
+      =>
+        @page.onLoadStarted = null
+        @owner.sendResponse(true) unless @awaiting_response
+      ,
+      0
+    )
+
+  drag: (id, other_id) ->
+    @page.get(id).dragTo(@page.get(other_id))
+    @owner.sendResponse(true)
+
+  trigger: (id, event) ->
+    @page.get(id).trigger(event)
+    @owner.sendResponse(event)
+
+  reset: ->
+    this.resetPage()
+    @owner.sendResponse(true)
+
+  render: (path) ->
+    @page.render(path)
+    @owner.sendResponse(true)