Rails Capybara Setup

Capybara is a web-based automation framework tool for testing Rails apps. It helps you to create **functional tests** that simulate how users would interact with your application through the browser.

**It is a fantastic tool for testing your application through the browser!**

**Capybara** doesn't interact with the website, it's just a layer between you and the web driver. For this, you can use **Selenium** web driver or any of the other drivers that Capybara supports.
##Configuring Capybara
**Capybara** can easily integrate with common test frameworks used in Rails. It is mostly used together with RSpec for writing feature test. 

Before you get started, you need to add the following gems to the :test group in your Gemfile and run `bundle install`:

```
group :test do
  gem 'capybara'
  gem 'selenium-webdriver'
end
```
##Testing with Capybara
Capybara comes with a user-friendly **DSL** (**D**omain **S**pecific **L**anguage), which offers helper methods for extracting information, inputting data, testing, or clicking around.
>*By default, Capybara will only locate visible elements. This is because a real user would not be able to interact with non-visible elements. You can read more about this at [rubydoc.info](http://www.rubydoc.info/github/teamcapybara/capybara/master#the-dsl)*.
>

###Common DSL options
Here we will cover the most comonly used **DSL actions** for interacting with elements on your web application:

* **Find** specific elements and manipulate them:

```
find_field('field_name').value
find_field(id: 'field_id').value
find_link('link_name', visible: all).visible?
find_button('button_name').click
```
This is one of the most important functions if you want to manipulate your elements. You can use it to find your links, buttons and fields and check if they are visible to the user, or click on them. `Find` will always wait for an element to appear on the page before raising an error.

* Interact with the web application by **following links and buttons**:

```
click_link('link_id')
click_link('link_text')
click_button('button_name')
click_on('link_text') # clicks on either link or button
```
Always use one of these options when you want to access a link or a button. You can do this by using id, title, text within tag or value of the element.

* Interact with **form elements**:

```
fill_in('Title', :with => 'Example')
choose('radio_button')
check('checkbox')
uncheck('checkbox')
attach_file('image', 'image_path') # upload a file
select('option', from: 'select_box') # select from dropdown
```
Whenever you want to fill up your form you should use one of these possibilities. Depending on the type of the element the present values are: id, name or related label element. The only exeption is attach_file, it can only accept id and name.

* **Navigate trough pages** with:

```
visit('url_name')
```
You can easily navigate trough page with this simple command or only access the current page with:

```
expect(page).to have_current_path(path_name)
```
* **Query** the page for the existence of certain elements:

```
expect(page).to have_selector('table tr')
expect(page).to have_content('content_name')
```

* Restrict certain actions within a specific area of the page with **scoping**:

```
# within(:xpath, 'actual_xpath') do
  fill_in 'Title', with: 'Example'
end
```
Use the `within` method when you want to use actions only in a specific area or use these special methods: `within_fieldset` for a specific fieldset and `within_table` for a specific table.

* **Debug** with the following methods:

```
save_and_open_page # current snapshot of the page
save_sceenshot('screenshot_name.png')
save_and_open_screenshot # saves and automatically opens the screenshot
```
When you want to save the snapshot of the page, just add one of these lines to your code, or you can also retrieve the current state of an element with:

```
print page_name.html
```
###Matchers
When trying to find an element by using the DSL or XPath, it is common to have two or more **matches**. You can customize the way Capybara find elements by using:

* **Capybara.exact** – Finds exact matches of an element.
* **Capybara.match** – Controls how Capybara behaves when multiple elements match. 

To avoid getting **Ambiguous match** error when more than one match is found, you should  consider using the following matching strategies supported by Capybara:

* **:first** – This will simply pick the first element that matches.
* **:one** – This will raise an error if more than one element is found.
* **:prefer_exact** – This finds all matching elements but only the first exactly matching element is returned and the rest is discarded.
* **:smart** – If **Capybara.exact** is set to **true**, it will behave like **:one**. Otherwise, it will try to find the exact element. Once again, an error is raised if multiple elements are found. If no element is found, a new search is performed.
###JavaScript and Asynchronous Calls
**Asynchronous JavaScript** allows you to interact with an element on the page that isn't present yet. This can happen when using JavaScript to creates a new element on the page:
  ```
  click_link('test')
  click_link('foo')
  ```
Once you click on the 'test' link it will trigger an asynchronous process, which will show the 'foo' link. Clicking on the 'foo' will most likely raise an error since that link doesn't exist yet. 
 
Capybara can handle this by waiting for a brief period of time. You can adjust the default waiting period (the default is 2 seconds) with: `Capybara.default_max_wait_time`.
## Capybara and RSpec
Using **Capybara together with RSpec** is as simple as adding `require 'capybara/rails'` in the `rspec_helper.rb` file. To be able to do this, you will need [RSpec installed](https://kolosek.com/rails-rspec-setup/) beforehand.

```
describe 'users' do
  let! :each do
    @user = FactoryGirl.create(:user)
    login_as(@user)
  end

  describe GET user#edit' do
    it 'should update user' do
      visit edit_user_path(@user)
      within('#edit_user_path') do
        fill_in 'email', with: 'john@example.com'
      end
      click_button 'Save'
      find_button('Save').click
      expect(page).to have_content 'Success'
    end
  end
end
```
This was a simple example that shows how you can use Capybara and RSpec at the same time by editing user.

Hope this article helped you to understand what Capybara the rodent can do to your test environment!

Originally published on [kolosek.com](https://kolosek.com/rails-capybara-setup/).