poltergeist 1.3.0 → 1.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f710cbda8c2d259e3f8819259d0e207871fe7276
+  data.tar.gz: db63a077b1335c06eb9cd91d09c0ef81ef3f11b9
+SHA512:
+  metadata.gz: 75f64909a5703a3a34802a01817a2b02dd76310102513208bd909cfed38cff551930793c3c07514f3efbb9a9ef5051187ba88b2189ea20c9030a0119559c4248
+  data.tar.gz: 20a98f89b9e22ec9d3207ce34ffdcf6bf117194669b001001bf9419ac1efd1471fda11811dbab0128a9e80adfa710d3750d10237416234eb795fd4bddb175c35

data/README.md

@@ -105,6 +105,8 @@ and the following optional features:
 * `page.status_code`
 * `page.response_headers`
 * `page.save_screenshot`
+* `page.render_base64`
+* `page.scroll_to`
 * cookie handling
 * drag-and-drop
 
@@ -119,6 +121,15 @@ render feature, so you can specify other extensions like `.pdf`, `.gif`, etc.)
 By default, only the viewport will be rendered (the part of the page that is in view). To render
 the entire page, use `save_screenshot('/path/to/file.png', :full => true)`.
 
+You also have an ability to render selected element. Pass option `selector` with
+any valid element selector to make a screenshot bounded by that element
+`save_screenshot('/path/to/file.png', :selector => '#id')`.
+
+If you need for some reasons base64 encoded screenshot you can simply call
+`render_base64` that will return you encoded image. Additional options are the
+same as for `save_screenshot` except the first argument which is format (:png by
+default, acceptable :png, :gif, :jpeg).
+
 ### Resizing the window ###
 
 Sometimes the window size is important to how things are rendered. Poltergeist sets the window
@@ -153,17 +164,33 @@ Capybara.javascript_driver = :poltergeist_debug
 [Read more
 here](http://jonathanleighton.com/articles/2012/poltergeist-0-6-0/)
 
-### Setting request headers ###
+### Manipulating request headers ###
+
+You can manipulate HTTP request headers with these methods:
+
+``` ruby
+page.driver.headers # => {}
+page.driver.headers = { "User-Agent" => "Poltergeist" }
+page.driver.add_headers("Referer" => "https://example.com")
+page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "https://example.com" }
+```
 
-Additional HTTP request headers can be set like so:
+Notice that `headers=` will overwrite already set headers. You should use
+`add_headers` if you want to add a few more. These headers will apply to all
+subsequent HTTP requests (including requests for assets, AJAX, etc). They will
+be automatically cleared at the end of the test. You have ability to set headers
+only for the initial request:
 
 ``` ruby
 page.driver.headers = { "User-Agent" => "Poltergeist" }
+page.driver.add_header("Referer", "http://example.com", permanent: false)
+page.driver.headers # => { "User-Agent" => "Poltergeist", "Referer" => "http://example.com" }
+visit(login_path)
+page.driver.headers # => { "User-Agent" => "Poltergeist" }
 ```
 
-The extra headers will apply to all subsequent HTTP requests (including
-requests for assets, AJAX, etc). They will be automatically cleared at
-the end of the test.
+This way your temporary headers will be sent only for the initial request, all
+subsequent request will only contain your permanent headers.
 
 ### Inspecting network traffic ###
 
@@ -186,6 +213,32 @@ The following methods are used to inspect and manipulate cookies:
   object.
 * `page.driver.remove_cookie(name)` - remove a cookie
 
+### Window switching ###
+
+The following methods can be used to execute commands inside different windows:
+
+* `page.driver.window_handles` - an array containing the names of all
+  the open windows.
+
+* `page.within_window(name) { # actions }` -  executes
+  the passed block in the context of the named window.
+
+Example:
+
+``` ruby
+find_link("Login with Facebook").trigger("click")
+
+sleep(0.1)
+
+fb_popup = page.driver.window_handles.last
+page.within_window fb_popup do
+  fill_in "email", :with => "facebook_email@email.tst"
+  fill_in "pass", :with => "my_pass"
+  click_button "Log In"
+end
+```
+
+
 ## Customization ##
 
 You can customize the way that Capybara sets up Poltegeist via the following code in your
@@ -205,7 +258,7 @@ end
     output, but this goes to `STDOUT` due to technical limitations.
 *   `:logger` (Object responding to `puts`) - When present, debug output is written to this object
 *   `:phantomjs_logger` (`IO` object) - Where the `STDOUT` from PhantomJS is written to. This is
-    where you `console.log` statements will show up. Default: `STDOUT`
+    where your `console.log` statements will show up. Default: `STDOUT`
 *   `:timeout` (Numeric) - The number of seconds we'll wait for a response
     when communicating with PhantomJS. Default is 30.
 *   `:inspector` (Boolean, String) - See 'Remote Debugging', above.
@@ -294,6 +347,13 @@ documentation on asynchronous
 Javascript](https://github.com/jnicklas/capybara#asynchronous-javascript-ajax-and-friends)
 which explains the tools that Capybara provides for dealing with this.
 
+### Memory leak ###
+
+If you run a few capybara sessions manually please make sure you've called
+`session.driver.quit` when you don't need session anymore. Forgetting about this
+causes memory leakage and your system's resources can be exhausted earlier than
+you may expect.
+
 ### General troubleshooting hints ###
 
 * Configure Poltergeist with `:debug` turned on so you can see its
@@ -324,263 +384,8 @@ Include as much information as possible. For example:
 
 ## Changes ##
 
-### 1.3.0 ###
-
-#### Features ####
-
-*   Add support for PhantomJS 1.7's `cookiesEnabled` API
-    (Micah Frost)
-
-#### Bug fixes ####
-
-*   Fix logging of mouse event co-ordinates
-*   Invalid selectors throw a useful error message
-*   Tie us to the 0.4 version of faye-websocket since the 0.5 version
-    contains breaking changes.
-
-### 1.2.0 ###
-
-#### Features ####
-
-*   Support for Windows hosted Poltergeist (Aaron Tull).
-*   Capybara 2.1 support
-
-#### Bug fixes ####
-
-*   Reverted the "native" implementation for filling in form fields,
-    which was introduced in 1.0. This implementation caused various bugs
-    and in general doesn't seem to be worth the trouble at the moment.
-    It can be reconsidered in the future when PhantomJS has upgraded its
-    WebKit version. [Issue #176, #223]
-*   Run phantomjs in a new process group so ^C doesn't trigger a
-    DeadClient error [Issue #252]
-
-### 1.1.1 ###
-
-#### Features ####
-
-*   Changed Capybara dependency to `~> 2.0.1` because Poltergeist 1.1 is
-    not compatible with Capybara 2.1.
-
-### 1.1.0 ###
-
-#### Features ####
-
-*   Add support for custom phantomjs loggers via `:phantomjs_logger` option.
-    (Gabe Bell)
-*   Add `page.driver.click(x, y)` to click precise coordinates.
-    (Micah Geisel)
-*   Add Capybara 2.0 support. Capybara 1.1 and Ruby 1.8 are *no
-    longer supported*. (Mauro Asprea) [Issue #163]
-*   Add `node.base.double_click` to double click the node.
-    (Andy Shen)
-*   The `:debug` option now causes the PhantomJS portion of Poltergeist
-    to output some additional debug info, which may be useful in
-    figuring out timeout errors.
-*   Add the ability to extend the phantomjs environment via browser
-    options. e.g.
-    `Capybara::Poltergeist::Driver.new( app, :extensions => ['file.js', 'another.js'])`
-    (Jon Rowe)
-
-#### Bug fixes ####
-
-*   Fix timing issue when using `within_frame` that could cause errors.
-    [Issue #183, #211] (@errm, @motemen)
-*   Fix bug with `within_frame` not properly switching the context back
-    after the block has executed. [Issue #242]
-*   Fix calculation of click position when clicking within a frame.
-    [Issue #222, #225]
-*   Fix error raising when calling `expires` if not set on cookie.
-    [Issue #203] (@arnvald)
-*   Fix the `:js_errors` option. Previously errors were not being
-    reported, but would still cause commands to fail. [Issue #229]
-*   Fix incorrect time zone handling when setting cookie expiry time
-    [Issue #228]
-*   Send SIGKILL to PhantomJS if it doesn't exit within 2 seconds
-    [Issue #196]
-*   Provide a more informative message for the `ObsoleteNode` error.
-    [Issue #192]
-*   Fix `ObsoleteNode` error when using `attach_file` with the `jQuery
-    File Upload` plugin. [Issue #115]
-*   Ensure that a `String` is passed over-the-wire to PhantomJS for
-    file input paths, allowing `attach_file` to be called with arbitry
-    objects such as a Pathname. (@mjtko) [Issue #215]
-*   Cookies can now be set before the first request. [Issue #193]
-
-### 1.0.2 ###
-
-#### Bug fixes ####
-
-*   Clearing the value before setting a new value by sending a backspace.
-    This fixes the issue that you can't set an empty value. [Issue #184]
-
-### 1.0.1 ###
-
-#### Bug fixes ####
-
-*   Don't use a fixed port number by default; find an available port.
-    The port can still be configured to a fixed value using the `:port`
-    option. The reverts the default behaviour to how it was before the
-    1.0 release. [Issue #174]
-
-### 1.0 ###
-
-#### Features ####
-
-*   Click co-ordinates are shown in the debug log. You can use this in
-    combination with `page.driver.render` to work out where clicks are
-    actually happening if you are having trouble.
-*   Added `:port` configuration option and made the default port 44678
-    rather than a random available port.
-*   Support for Capybara's `page.response_headers` API to retrieve the
-    headers of the last page load.
-*   Support for cookie manipulation. [Issue #12]
-*   Frame switching support now uses native PhantomJS APIs. (This might
-    make it work better, but in general it's a badly tested area both in
-    Capybara and Poltergeist.)
-*   Support for the Capybara window switching API (`page.within_window`).
-
-#### Bug fixes ####
-
-*   Prevent `TypeError: 'undefined' is not an object (evaluating
-    'rect.top')` error when clicking an element with `display: none`.
-    The click will fail, but an obsolete node error will be raised, meaning
-    that Capybara's retry mechanisms will kick in. [Issue #130]
-*   Mouse over the element we will click, before clicking it. This
-    enables `:hover` effects etc to trigger before the click happens,
-    which can affect the click in some cases. [Issue #120]
-*   Don't blow up when `evaluate_script` is called with a cyclic
-    structure.
-*   Fix the text method for title elements, so it doesn't return an
-    empty string.
-*   Fixed problem with cookies not being clearer between tests on
-    PhantomJS 1.7
-*   Fixed Javascript errors during page load causes TimeoutErrors.
-    [Issue #124]
-*   Ensure the User-Agent header can be set successfully. (Klaus Hartl)
-    [Issue #127]
-*   Use `el.innerText` for `Node#text`. This ensures that e.g. `<br>` is
-    returned as a space. It also simplifies the method. [Issue #139]
-*   Fix status code support when a response redirects to another URL.
-    This was previously tested to ensure it would return the status code
-    of the redirected URL, but the test was falsely broken and the
-    implementation was also broken.
-*   Fixed visiting URLs where only a hash change occurs (no HTTP
-    request). [Issue #79]
-*   Setting `page.driver.headers` now applies the headers to all
-    requests, not just calls to `visit`. (So XHR, asset requests, etc
-    will all receive the headers.) [Issue #149]
-
-### 0.7 ###
-
-#### Features ####
-
-*   Added an option `:js_errors`, allowing poltergeist to continue
-    running after JS errors. (John Griffin & Tom Stuart) [Issue #62] [Issue #69]
-*   Added an option `:window_size`, allowing users to specify
-    dimensions to which the browser window will be resized.
-    (Tom Stuart) [Issue #53]
-*   Capybara 1.0 is no longer supported. Capybara ~> 1.1 is required.
-*   Added ability to set arbitrary http request headers
-*   Inspect network traffic on the page via
-    `page.driver.network_traffic` (Doug McInnes) [Issue #77]
-*   Added an option `:phantomjs_options`, allowing users to specify
-    additional command-line options passed to phantomjs executable.
-    (wynst) [Issue #97]
-*   Scroll element into viewport if needed on click (Gabriel Sobrinho)
-    [Issue #83]
-*   Added status code support. (Dmitriy Nesteryuk and Jon Leighton) [Issue #37]
-
-#### Bug fixes ###
-
-*   Fix issue with `ClickFailed` exception happening with a negative
-    co-ordinate (which should be impossible). (Jon Leighton, Gabriel
-    Sobrinho, Tom Stuart) [Issue #60]
-*   Fix issue with `undefined method map for "[]":String`, which
-    happened when dealing with pages that include JS rewriting
-    Array.prototype.toJSON. (Tom Stuart) [Issue #63]
-
-### 0.6 ###
-
-#### Features ####
-
-*   Updated to PhantomJS 1.5.0, giving us proper support for reporting
-    Javascript exception backtraces.
-
-### 0.5 ###
-
-#### 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]
-*   JRuby support. [Issue #20]
-
-#### 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 ###
-
-*   Element click position is now calculated using the native
-    `getBoundingClientRect()` method, which will be faster and less
-    buggy.
-*   Handle `window.confirm()`. Always returns true, which is the same
-    as capybara-webkit. [Issue #10]
-*   Handle `window.prompt()`. Returns the default value, if present, or
-    null.
-*   Fix bug with page Javascript page loading causing problems. [Issue #19]
-
-### 0.3 ###
-
-*   There was a bad bug to do with clicking elements in a page where the
-    page is smaller than the window. The incorrect position would be
-    calculated, and so the click would happen in the wrong place. This is
-    fixed. [Issue #8]
-*   Poltergeist didn't work in conjunction with the Thin web server,
-    because that server uses Event Machine, and Poltergeist was assuming
-    that it was the only thing in the process using EventMachine.
-
-    To solve this, EventMachine usage has been completely removed, which
-    has the welcome side-effect of being more efficient because we
-    no longer have the overhead of running a mostly-idle event loop.
-
-    [Issue #6]
-*   Added the `:timeout` option to configure the timeout when talking to
-    PhantomJS.
-
-### 0.2 ###
-
-*   First version considered 'ready', hopefully fewer problems.
-
-### 0.1 ###
-
-*   First version, various problems.
+Version history and a list of next-release features and fixes can be found in
+the [changelog](CHANGELOG.md).
 
 ## License ##
 

data/lib/capybara/poltergeist.rb

@@ -15,6 +15,7 @@ module Capybara
     require 'capybara/poltergeist/web_socket_server'
     require 'capybara/poltergeist/client'
     require 'capybara/poltergeist/inspector'
+    require 'capybara/poltergeist/json'
     require 'capybara/poltergeist/network_traffic'
     require 'capybara/poltergeist/errors'
     require 'capybara/poltergeist/cookie'

data/lib/capybara/poltergeist/browser.rb

@@ -1,5 +1,5 @@
 require "capybara/poltergeist/errors"
-require 'json'
+require 'multi_json'
 require 'time'
 
 module Capybara::Poltergeist
@@ -118,6 +118,10 @@ module Capybara::Poltergeist
       command 'pop_frame'
     end
 
+    def window_handles
+      command 'pages'
+    end
+
     def within_window(name, &block)
       command 'push_window', name
       yield
@@ -153,8 +157,18 @@ module Capybara::Poltergeist
       command 'reset'
     end
 
+    def scroll_to(left, top)
+      command 'scroll_to', left, top
+    end
+
     def render(path, options = {})
-      command 'render', path.to_s, !!options[:full]
+      check_render_options!(options)
+      command 'render', path.to_s, !!options[:full], options[:selector]
+    end
+
+    def render_base64(format, options = {})
+      check_render_options!(options)
+      command 'render_base64', format.to_s, !!options[:full], options[:selector]
     end
 
     def resize(width, height)
@@ -174,10 +188,22 @@ module Capybara::Poltergeist
       command('equals', page_id, id, other_id)
     end
 
+    def get_headers
+      command 'get_headers'
+    end
+
     def set_headers(headers)
       command 'set_headers', headers
     end
 
+    def add_headers(headers)
+      command 'add_headers', headers
+    end
+
+    def add_header(header, permanent)
+      command 'add_header', header, permanent
+    end
+
     def response_headers
       command 'response_headers'
     end
@@ -221,7 +247,7 @@ module Capybara::Poltergeist
       message = { 'name' => name, 'args' => args }
       log message.inspect
 
-      json = JSON.load(server.send(JSON.generate(message)))
+      json = JSON.load(server.send(JSON.dump(message)))
       log json.inspect
 
       if json['error']
@@ -240,5 +266,12 @@ module Capybara::Poltergeist
     def log(message)
       logger.puts message if logger
     end
+
+    def check_render_options!(options)
+      if !!options[:full] && options.has_key?(:selector)
+        warn "Ignoring :selector in #render since :full => true was given at #{caller.first}"
+        options.delete(:selector)
+      end
+    end
   end
 end