poltergeist 0.4.0 → 0.5.0

data/README.md

@@ -1,8 +1,9 @@
 # Poltergeist - A PhantomJS driver for Capybara #
 
-Version: 0.4.0
+Version: 0.5.0
 
 [![Build Status](https://secure.travis-ci.org/jonleighton/poltergeist.png)](http://travis-ci.org/jonleighton/poltergeist)
+[![Dependency Status](https://gemnasium.com/jonleighton/poltergeist.png)](https://gemnasium.com/jonleighton/poltergeist)
 
 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,
@@ -10,7 +11,7 @@ provided by [PhantomJS](http://www.phantomjs.org/).
 
 ## Installation ##
 
-Add `poltergeist` to your Gemfile, and add in your test setup add:
+Add `poltergeist` to your Gemfile, and in your test setup add:
 
 ``` ruby
 require 'capybara/poltergeist'
@@ -172,6 +173,51 @@ makes debugging easier). Running `rake autocompile` will watch the
 
 ## Changes ##
 
+### 0.5.0 ###
+
+#### Features ####
+
+*   Detect if clicking an element will fail. If the click will actually
+    hit another element (because that element is in front of the one we
+    want to click), the user will now see an exception explaining what
+    happened and which element would actually be targeted by the click. This
+    should aid debugging. [Issue #25]
+
+*   Click elements at their middle position rather than the top-left.
+    This is presumed to be more likely to succeed because the top-left
+    may be obscured by overlapping elements, negative margins, etc. [Issue #26]
+
+*   Add experimental support for using the remote WebKit web inspector.
+    This will only work with PhantomJS 1.5, which is not yet released,
+    so it won't be officially supported by Poltergeist until 1.5 is
+    released. [Issue #31]
+
+*   Add `page.driver.quit` method. If you spawn additional Capybara
+    sessions, you might want to use this to reap the child phantomjs
+    process. [Issue #24]
+
+*   Errors produced by Javascript on the page will now generate an
+    exception within Ruby. [Issue #27]
+
+#### Bug fixes ####
+
+*   Fix bug where we could end up interacting with an obsolete element. [Issue #30]
+
+*   Raise an suitable error if PhantomJS returns a non-zero exit status.
+    Previously a version error would be raised, indicating that the
+    PhantomJS version was too old when in fact it did not start at all. [Issue #23]
+
+*   Ensure the `:timeout` option is actually used. [Issue #36]
+
+*   Nodes need to know which page they are associated with. Before this,
+    if Javascript caused a new page to load, existing node references
+    would be wrong, but wouldn't raise an ObsoleteNode error. [Issue #39]
+
+*   In some circumstances, we could end up missing an inline element
+    when attempting to click it. This is due to the use of
+    `getBoundingClientRect()`. We're now using `getClientRects()` to
+    address this.
+
 ### 0.4.0 ###
 
 *   Element click position is now calculated using the native

data/lib/capybara/poltergeist.rb

@@ -9,6 +9,9 @@ module Capybara
     autoload :Server,          'capybara/poltergeist/server'
     autoload :WebSocketServer, 'capybara/poltergeist/web_socket_server'
     autoload :Client,          'capybara/poltergeist/client'
+    autoload :Util,            'capybara/poltergeist/util'
+    autoload :Inspector,       'capybara/poltergeist/inspector'
+    autoload :Spawn,           'capybara/poltergeist/spawn'
 
     require 'capybara/poltergeist/errors'
   end

data/lib/capybara/poltergeist/browser.rb

@@ -1,23 +1,13 @@
-require 'json'
+require 'multi_json'
 
 module Capybara::Poltergeist
   class Browser
-    attr_reader :options, :server, :client
+    attr_reader :server, :client, :logger
 
-    DEFAULT_TIMEOUT = 30
-
-    def initialize(options = {})
-      @options = options
-      @server  = Server.new(options.fetch(:timeout, DEFAULT_TIMEOUT))
-      @client  = Client.start(server.port, options[:phantomjs])
-    end
-
-    def timeout
-      server.timeout
-    end
-
-    def timeout=(sec)
-      server.timeout = sec
+    def initialize(server, client, logger = nil)
+      @server = server
+      @client = client
+      @logger = logger
     end
 
     def restart
@@ -25,7 +15,7 @@ module Capybara::Poltergeist
       client.restart
     end
 
-    def visit(url, attributes = {})
+    def visit(url)
       command 'visit', url
     end
 
@@ -41,36 +31,41 @@ module Capybara::Poltergeist
       command 'source'
     end
 
-    def find(selector, id = nil)
-      command 'find', selector, id
+    def find(selector)
+      result = command('find', selector)
+      result['ids'].map { |id| [result['page_id'], id] }
     end
 
-    def text(id)
-      command 'text', id
+    def find_within(page_id, id, selector)
+      command 'find_within', page_id, id, selector
     end
 
-    def attribute(id, name)
-      command 'attribute', id, name
+    def text(page_id, id)
+      command 'text', page_id, id
     end
 
-    def value(id)
-      command 'value', id
+    def attribute(page_id, id, name)
+      command 'attribute', page_id, id, name.to_s
     end
 
-    def set(id, value)
-      command 'set', id, value
+    def value(page_id, id)
+      command 'value', page_id, id
     end
 
-    def select_file(id, value)
-      command 'select_file', id, value
+    def set(page_id, id, value)
+      command 'set', page_id, id, value
     end
 
-    def tag_name(id)
-      command('tag_name', id).downcase
+    def select_file(page_id, id, value)
+      command 'select_file', page_id, id, value
     end
 
-    def visible?(id)
-      command 'visible', id
+    def tag_name(page_id, id)
+      command('tag_name', page_id, id).downcase
+    end
+
+    def visible?(page_id, id)
+      command 'visible', page_id, id
     end
 
     def evaluate(script)
@@ -87,24 +82,20 @@ module Capybara::Poltergeist
       command 'pop_frame'
     end
 
-    def reset
-      visit('about:blank')
+    def click(page_id, id)
+      command 'click', page_id, id
     end
 
-    def click(id)
-      command 'click', id
+    def drag(page_id, id, other_id)
+      command 'drag', page_id, id, other_id
     end
 
-    def drag(id, other_id)
-      command 'drag', id, other_id
+    def select(page_id, id, value)
+      command 'select', page_id, id, value
     end
 
-    def select(id, value)
-      command 'select', id, value
-    end
-
-    def trigger(id, event)
-      command 'trigger', id, event
+    def trigger(page_id, id, event)
+      command 'trigger', page_id, id, event.to_s
     end
 
     def reset
@@ -119,23 +110,19 @@ module Capybara::Poltergeist
       command 'resize', width, height
     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)))
+      json = MultiJson.decode(server.send(MultiJson.encode(message)))
       log json.inspect
 
       if json['error']
-        raise BrowserError.new(json['error'])
+        if json['error']['name'] == 'Poltergeist.JavascriptError'
+          raise JavascriptError.new(json['error'])
+        else
+          raise BrowserError.new(json['error'])
+        end
       else
         json['response']
       end
@@ -144,5 +131,11 @@ module Capybara::Poltergeist
       restart
       raise
     end
+
+    private
+
+    def log(message)
+      logger.puts message if logger
+    end
   end
 end

data/lib/capybara/poltergeist/client.rb

@@ -1,11 +1,8 @@
-require 'sfl'
-
 module Capybara::Poltergeist
   class Client
     PHANTOMJS_SCRIPT  = File.expand_path('../client/compiled/main.js', __FILE__)
-    PHANTOMJS_VERSION = "1.4.1"
-
-    attr_reader :pid, :port, :path
+    PHANTOMJS_VERSION = '1.4.1'
+    PHANTOMJS_NAME    = 'phantomjs'
 
     def self.start(*args)
       client = new(*args)
@@ -13,19 +10,33 @@ module Capybara::Poltergeist
       client
     end
 
-    def initialize(port, path = nil)
-      @port = port
-      @path = path || 'phantomjs'
-      at_exit { stop }
+    attr_reader :pid, :port, :path, :inspector
+
+    def initialize(port, inspector = nil, path = nil)
+      @port      = port
+      @inspector = inspector
+      @path      = path || PHANTOMJS_NAME
+
+      pid = Process.pid
+      at_exit { stop if Process.pid == pid }
     end
 
     def start
       check_phantomjs_version
-      @pid = Kernel.spawn("#{path} #{PHANTOMJS_SCRIPT} #{port}")
+      @pid = Spawn.spawn(*command)
     end
 
     def stop
-      Process.kill('TERM', pid) if pid
+      if pid
+        begin
+          Process.kill('TERM', pid)
+          Process.wait(pid)
+        rescue Errno::ESRCH, Errno::ECHILD
+          # Zed's dead, baby
+        end
+
+        @pid = nil
+      end
     end
 
     def restart
@@ -33,15 +44,34 @@ module Capybara::Poltergeist
       start
     end
 
+    def command
+      @command ||= begin
+        parts = [path]
+
+        if inspector
+          parts << "--remote-debugger-port=#{inspector.port}"
+          parts << "--remote-debugger-autorun=yes"
+        end
+
+        parts << PHANTOMJS_SCRIPT
+        parts << port
+        parts
+      end
+    end
+
     private
 
     def check_phantomjs_version
       return if @phantomjs_version_checked
 
       version = `#{path} --version`.chomp
-      if version < PHANTOMJS_VERSION
+
+      if $? != 0
+        raise PhantomJSFailed.new($?)
+      elsif version < PHANTOMJS_VERSION
         raise PhantomJSTooOld.new(version)
       end
+
       @phantomjs_version_checked = true
     end
   end

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

@@ -7,18 +7,28 @@ class PoltergeistAgent
     @windows  = []
     this.pushWindow(window)
 
+  externalCall: (name, arguments) ->
+    try
+      { value: this[name].apply(this, arguments) }
+    catch error
+      { error: error.toString() }
+
   pushWindow: (new_window) ->
     @windows.push(new_window)
 
     @window   = new_window
     @document = @window.document
 
+    null
+
   popWindow: ->
     @windows.pop()
 
     @window   = @windows[@windows.length - 1]
     @document = @window.document
 
+    null
+
   pushFrame: (id) ->
     this.pushWindow @document.getElementById(id).contentWindow
 
@@ -28,9 +38,8 @@ class PoltergeistAgent
   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)
+  find: (selector, within = @document) ->
+    results = @document.evaluate(selector, within, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
     ids     = []
 
     for i in [0...results.snapshotLength]
@@ -51,8 +60,12 @@ class PoltergeistAgent
 
   nodeCall: (id, name, arguments) ->
     node = this.get(id)
+    throw new PoltergeistAgent.ObsoleteNode if node.isObsolete()
     node[name].apply(node, arguments)
 
+class PoltergeistAgent.ObsoleteNode
+  toString: -> "PoltergeistAgent.ObsoleteNode"
+
 class PoltergeistAgent.Node
   @EVENTS = {
     FOCUS: ['blur', 'focus', 'focusin', 'focusout'],
@@ -65,6 +78,9 @@ class PoltergeistAgent.Node
   parentId: ->
     @agent.register(@element.parentNode)
 
+  find: (selector) ->
+    @agent.find(selector, @element)
+
   isObsolete: ->
     obsolete = (element) =>
       if element.parentNode?
@@ -151,8 +167,16 @@ class PoltergeistAgent.Node
       true
 
   position: ->
-    rect = @element.getBoundingClientRect()
-    { top: rect.top, left: rect.left }
+    rect = @element.getClientRects()[0]
+
+    {
+      top:    rect.top,
+      right:  rect.right,
+      left:   rect.left,
+      bottom: rect.bottom,
+      width:  rect.width,
+      height: rect.height
+    }
 
   trigger: (name) ->
     if Node.EVENTS.MOUSE.indexOf(name) != -1
@@ -169,6 +193,25 @@ class PoltergeistAgent.Node
 
     @element.dispatchEvent(event)
 
+  clickTest: (x, y) ->
+    el = origEl = document.elementFromPoint(x, y)
+
+    while el
+      if el == @element
+        return { status: 'success' }
+      else
+        el = el.parentNode
+
+    { status: 'failure', selector: origEl && this.getSelector(origEl) }
+
+  getSelector: (el) ->
+    selector = if el.tagName != 'HTML' then this.getSelector(el.parentNode) + ' ' else ''
+    selector += el.tagName.toLowerCase()
+    selector += "##{el.id}" if el.id
+    for className in el.classList
+      selector += ".#{className}"
+    selector
+
 window.__poltergeist = new PoltergeistAgent
 
 document.addEventListener(

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

@@ -1,11 +1,12 @@
 class Poltergeist.Browser
   constructor: (@owner) ->
-    @state = 'default'
+    @state   = 'default'
+    @page_id = 0
+
     this.resetPage()
 
   resetPage: ->
     @page.release() if @page?
-
     @page = new Poltergeist.WebPage
 
     @page.onLoadStarted = =>
@@ -13,37 +14,58 @@ class Poltergeist.Browser
 
     @page.onLoadFinished = (status) =>
       if @state == 'loading'
-        @owner.sendResponse(status)
+        this.sendResponse(status)
         @state = 'default'
 
+    @page.onInitialized = =>
+      @page_id += 1
+
+  sendResponse: (response) ->
+    errors = @page.errors()
+
+    if errors.length > 0
+      @page.clearErrors()
+      @owner.sendError(new Poltergeist.JavascriptError(errors))
+    else
+      @owner.sendResponse(response)
+
+  node: (page_id, id) ->
+    if page_id == @page_id
+      @page.get(id)
+    else
+      throw new Poltergeist.ObsoleteNode
+
   visit: (url) ->
     @state = 'loading'
     @page.open(url)
 
   current_url: ->
-    @owner.sendResponse @page.currentUrl()
+    this.sendResponse @page.currentUrl()
 
   body: ->
-    @owner.sendResponse @page.content()
+    this.sendResponse @page.content()
 
   source: ->
-    @owner.sendResponse @page.source()
+    this.sendResponse @page.source()
+
+  find: (selector) ->
+    this.sendResponse(page_id: @page_id, ids: @page.find(selector))
 
-  find: (selector, id) ->
-    @owner.sendResponse @page.find(selector, id)
+  find_within: (page_id, id, selector) ->
+    this.sendResponse this.node(page_id, id).find(selector)
 
-  text: (id) ->
-    @owner.sendResponse @page.get(id).text()
+  text: (page_id, id) ->
+    this.sendResponse this.node(page_id, id).text()
 
-  attribute: (id, name) ->
-    @owner.sendResponse @page.get(id).getAttribute(name)
+  attribute: (page_id, id, name) ->
+    this.sendResponse this.node(page_id, id).getAttribute(name)
 
-  value: (id) ->
-    @owner.sendResponse @page.get(id).value()
+  value: (page_id, id) ->
+    this.sendResponse this.node(page_id, id).value()
 
-  set: (id, value) ->
-    @page.get(id).set(value)
-    @owner.sendResponse(true)
+  set: (page_id, id, value) ->
+    this.node(page_id, id).set(value)
+    this.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
@@ -52,8 +74,8 @@ class Poltergeist.Browser
   # 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)
+  select_file: (page_id, id, value) ->
+    element = this.node(page_id, id)
 
     multiple = element.isMultiple()
 
@@ -65,38 +87,38 @@ class Poltergeist.Browser
     element.removeAttribute('_poltergeist_selected')
     element.setAttribute('multiple', 'multiple') if multiple
 
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
-  select: (id, value) ->
-    @owner.sendResponse @page.get(id).select(value)
+  select: (page_id, id, value) ->
+    this.sendResponse this.node(page_id, id).select(value)
 
-  tag_name: (id) ->
-    @owner.sendResponse @page.get(id).tagName()
+  tag_name: (page_id, id) ->
+    this.sendResponse this.node(page_id, id).tagName()
 
-  visible: (id) ->
-    @owner.sendResponse @page.get(id).isVisible()
+  visible: (page_id, id) ->
+    this.sendResponse this.node(page_id, id).isVisible()
 
   evaluate: (script) ->
-    @owner.sendResponse JSON.parse(@page.evaluate("function() { return JSON.stringify(#{script}) }"))
+    this.sendResponse JSON.parse(@page.evaluate("function() { return JSON.stringify(#{script}) }"))
 
   execute: (script) ->
     @page.execute("function() { #{script} }")
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
   push_frame: (id) ->
     @page.pushFrame(id)
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
   pop_frame: ->
     @page.popFrame()
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
-  click: (id) ->
+  click: (page_id, id) ->
     # If the click event triggers onLoadStarted, we will transition to the 'loading'
     # state and wait for onLoadFinished before sending a response.
     @state = 'clicked'
 
-    @page.get(id).click()
+    this.node(page_id, 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.
@@ -104,22 +126,22 @@ class Poltergeist.Browser
       =>
         if @state == 'clicked'
           @state = 'default'
-          @owner.sendResponse(true)
+          this.sendResponse(true)
       ,
       10
     )
 
-  drag: (id, other_id) ->
-    @page.get(id).dragTo(@page.get(other_id))
-    @owner.sendResponse(true)
+  drag: (page_id, id, other_id) ->
+    this.node(page_id, id).dragTo(@page.get(other_id))
+    this.sendResponse(true)
 
-  trigger: (id, event) ->
-    @page.get(id).trigger(event)
-    @owner.sendResponse(event)
+  trigger: (page_id, id, event) ->
+    this.node(page_id, id).trigger(event)
+    this.sendResponse(event)
 
   reset: ->
     this.resetPage()
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
   render: (path, full) ->
     dimensions = @page.validatedDimensions()
@@ -135,11 +157,11 @@ class Poltergeist.Browser
       @page.setClipRect(left: 0, top: 0, width: viewport.width, height: viewport.height)
       @page.render(path)
 
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
   resize: (width, height) ->
     @page.setViewportSize(width: width, height: height)
-    @owner.sendResponse(true)
+    this.sendResponse(true)
 
   exit: ->
     phantom.exit()