2011-02-28 16:01:34 +00:00
capybara-webkit
===============
2013-03-25 15:51:10 +00:00
[![Build Status ](https://secure.travis-ci.org/thoughtbot/capybara-webkit.png?branch=master )](https://travis-ci.org/thoughtbot/capybara-webkit)
[![Code Climate ](https://codeclimate.com/github/thoughtbot/capybara-webkit.png )](https://codeclimate.com/github/thoughtbot/capybara-webkit)
2012-10-12 16:56:48 +00:00
2013-12-04 01:08:36 +00:00
A [capybara ](https://github.com/jnicklas/capybara ) driver that uses [WebKit ](http://webkit.org ) via [QtWebKit ](http://trac.webkit.org/wiki/QtWebKit ).
2011-02-28 16:01:34 +00:00
2012-02-24 14:30:57 +00:00
Qt Dependency and Installation Issues
2012-11-14 16:00:58 +00:00
-------------------------------------
2011-02-28 16:01:34 +00:00
2011-08-28 00:35:58 +00:00
capybara-webkit depends on a WebKit implementation from Qt, a cross-platform
development toolkit. You'll need to download the Qt libraries to build and
2011-09-14 21:14:03 +00:00
install the gem. You can find instructions for downloading and installing QT on
2012-11-14 16:00:58 +00:00
the
[capybara-webkit wiki ](https://github.com/thoughtbot/capybara-webkit/wiki/Installing-Qt-and-compiling-capybara-webkit ).
2012-12-07 02:31:41 +00:00
capybara-webkit requires Qt version 4.8.
2011-04-13 18:55:54 +00:00
2012-03-16 16:09:05 +00:00
Windows Support
---------------
2013-12-20 15:20:00 +00:00
Currently 32-bit Windows will compile capybara-webkit. Support for Windows is
provided by the open source community and Windows related issues should be
posted to [Stack Overflow].
[Stack Overflow]: http://stackoverflow.com/questions/tagged/capybara-webkit
2012-03-16 16:09:05 +00:00
2011-10-01 17:03:07 +00:00
Reporting Issues
----------------
Without access to your application code we can't easily debug most crashes or
2011-10-06 22:56:20 +00:00
generic failures, so we've included a debug version of the driver that prints a
2011-10-01 17:03:07 +00:00
log of what happened during each test. Before filing a crash bug, please see
2013-12-20 15:20:00 +00:00
[Reporting Crashes]. You're much more likely to get a fix if you follow those
instructions.
2011-10-01 17:03:07 +00:00
2013-12-20 15:20:00 +00:00
If you're having trouble compiling or installing, please check out the [wiki].
If you don't have any luck there, please post to [Stack Overflow]. Please don't
2012-02-24 14:30:57 +00:00
open a Github issue for a system-specific compiler issue.
2012-01-13 16:44:20 +00:00
2013-12-20 15:20:00 +00:00
[Reporting Crashes]: http://stackoverflow.com/questions/tagged/capybara-webkit
[capybara-webkit wiki]: https://github.com/thoughtbot/capybara-webkit/wiki
[Stack Overflow]: http://stackoverflow.com/questions/tagged/capybara-webkit
2011-06-05 21:49:16 +00:00
CI
--
If you're like us, you'll be using capybara-webkit on CI.
2011-04-13 18:55:54 +00:00
2011-04-14 20:48:53 +00:00
On Linux platforms, capybara-webkit requires an X server to run, although it doesn't create any visible windows. Xvfb works fine for this. You can setup Xvfb yourself and set a DISPLAY variable, or try out the [headless gem ](https://github.com/leonid-shevtsov/headless ).
2011-04-13 16:17:59 +00:00
2011-03-09 22:55:40 +00:00
Usage
-----
Add the capybara-webkit gem to your Gemfile:
2013-03-07 01:07:55 +00:00
```ruby
gem "capybara-webkit"
```
2011-03-09 22:55:40 +00:00
Set your Capybara Javascript driver to webkit:
2013-03-07 01:07:55 +00:00
```ruby
Capybara.javascript_driver = :webkit
```
2011-03-09 22:55:40 +00:00
2011-11-01 19:36:24 +00:00
In cucumber, tag scenarios with @javascript to run them using a headless WebKit browser.
2011-03-09 22:55:40 +00:00
2013-12-20 21:23:51 +00:00
In RSpec, use the `:js => true` flag. See the [capybara documentation ](http://rubydoc.info/gems/capybara#Using_Capybara_with_RSpec ) for more information about using capybara with RSpec.
2011-11-01 19:36:24 +00:00
2012-01-13 18:10:02 +00:00
Take note of the transactional fixtures section of the [capybara README ](https://github.com/jnicklas/capybara/blob/master/README.md ).
2011-11-01 19:19:28 +00:00
2012-04-17 22:29:28 +00:00
If you're using capybara-webkit with Sinatra, don't forget to set
2013-03-07 01:07:55 +00:00
```ruby
Capybara.app = MySinatraApp.new
```
2012-04-17 22:29:28 +00:00
2012-04-03 23:23:42 +00:00
Non-Standard Driver Methods
---------------------------
capybara-webkit supports a few methods that are not part of the standard capybara API. You can access these by calling `driver` on the capybara session. When using the DSL, that will look like `page.driver.method_name` .
**console_messages**: returns an array of messages printed using console.log
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
console.log("hello")
```
```ruby
# In Ruby:
page.driver.console_messages
2013-12-20 21:22:15 +00:00
=> [{:source=>"http://example.com", :line_number=>1, :message=>"hello"}]
2013-03-07 01:07:55 +00:00
```
2012-04-03 23:23:42 +00:00
**error_messages**: returns an array of Javascript errors that occurred
2013-03-07 01:07:55 +00:00
```ruby
page.driver.error_messages
2013-12-20 21:22:15 +00:00
=> [{:source=>"http://example.com", :line_number=>1, :message=>"SyntaxError: Parse error"}]
2013-03-07 01:07:55 +00:00
```
2012-04-03 23:23:42 +00:00
2012-07-10 13:47:17 +00:00
**alert_messages, confirm_messages, prompt_messages**: returns arrays of Javascript dialog messages for each dialog type
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
alert("HI");
confirm("Ok?");
prompt("Number?", "42");
```
```ruby
# In Ruby:
page.driver.alert_messages
=> ["Hi"]
page.driver.confirm_messages
=> ["Ok?"]
page.driver.prompt_messages
=> ["Number?"]
```
2012-07-10 13:47:17 +00:00
2012-04-03 23:23:42 +00:00
**resize_window**: change the viewport size to the given width and height
2013-03-07 01:07:55 +00:00
```ruby
page.driver.resize_window(500, 300)
page.driver.evaluate_script("window.innerWidth")
=> 500
```
2012-04-03 23:23:42 +00:00
**cookies**: allows read-only access of cookies for the current session
2013-03-07 01:07:55 +00:00
```ruby
page.driver.cookies["alpha"]
=> "abc"
```
2012-04-03 23:23:42 +00:00
2012-07-10 13:47:17 +00:00
**accept_js_confirms!**: accept any Javascript confirm that is triggered by the page's Javascript
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
if (confirm("Ok?"))
console.log("Hi");
else
console.log("Bye");
```
```ruby
# In Ruby:
page.driver.accept_js_confirms!
visit "/"
page.driver.console_messages.first[:message]
=> "Hi"
```
2012-07-10 13:47:17 +00:00
**dismiss_js_confirms!**: dismiss any Javascript confirm that is triggered by the page's Javascript
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
if (confirm("Ok?"))
console.log("Hi");
else
console.log("Bye");
```
```ruby
# In Ruby:
page.driver.dismiss_js_confirms!
visit "/"
page.driver.console_messages.first[:message]
=> "Bye"
```
2012-07-10 13:47:17 +00:00
**accept_js_prompts!**: accept any Javascript prompt that is triggered by the page's Javascript
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
var a = prompt("Number?", "0")
console.log(a);
```
```ruby
# In Ruby:
page.driver.accept_js_prompts!
visit "/"
page.driver.console_messages.first[:message]
=> "0"
```
2012-07-10 13:47:17 +00:00
**dismiss_js_prompts!**: dismiss any Javascript prompt that is triggered by the page's Javascript
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
var a = prompt("Number?", "0")
if (a != null)
console.log(a);
else
console.log("you said no"));
```
```ruby
# In Ruby:
page.driver.dismiss_js_prompts!
visit "/"
page.driver.console_messages.first[:message]
=> "you said no"
```
2012-07-10 13:47:17 +00:00
**js_prompt_input=(value)**: set the text to use if a Javascript prompt is encountered and accepted
2013-03-07 01:07:55 +00:00
```js
// In Javascript:
var a = prompt("Number?", "0")
console.log(a);
```
```ruby
# In Ruby:
page.driver.js_prompt_input = "42"
page.driver.accept_js_prompts!
visit "/"
page.driver.console_messages.first[:message]
=> "42"
```
2012-07-10 13:47:17 +00:00
2012-11-09 18:29:32 +00:00
**header**: set the given HTTP header for subsequent requests
2013-03-07 01:07:55 +00:00
```ruby
page.driver.header 'Referer', 'https://www.thoughtbot.com'
```
2012-11-09 18:29:32 +00:00
2011-07-22 20:59:13 +00:00
Contributing
------------
See the CONTRIBUTING document.
2011-03-09 22:55:40 +00:00
About
-----
2012-11-09 18:11:06 +00:00
The capybara WebKit driver is maintained by Joe Ferris and Matt Horan. It was written by [thoughtbot, inc ](http://thoughtbot.com/community ) with the help of numerous [contributions from the open source community ](https://github.com/thoughtbot/capybara-webkit/contributors ).
2011-03-09 22:55:40 +00:00
2011-07-03 13:39:47 +00:00
Code for rendering the current webpage to a PNG is borrowed from Phantom.js' implementation.
2011-04-13 17:31:27 +00:00
![thoughtbot ](http://thoughtbot.com/images/tm/logo.png )
2011-03-09 22:55:40 +00:00
The names and logos for thoughtbot are trademarks of thoughtbot, inc.
License
-------
2013-01-06 08:34:04 +00:00
capybara-webkit is Copyright (c) 2010-2013 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the LICENSE file.