Understanding Capybara::Session

 

We can script Capybara as we would interact with a browser. Further, the session methods allow us to set and query the current state of our headless “browser.”

Capybara::Session: Visit

First thing first, the visit method takes an address parameter and will fetch the page. Example:

visit “/articles/”

However, when we are running tests against a Rails application, we have access to the named routes directly in our examples like this:

So, visit articles_path

Moreover, this allows your test to delegate the responsibility for understanding that path to the router, allowing greater flexibility in the future.

Capybara::Session: Current Path

Certainly, the current_path method returns the path without the protocol, server, and port. Moreover, this is useful for checking that you arrive on a certain page after a previous action took place. For instance:

page.current_path

However, that would return “/articles/” when you’re on the articles index page.

Capybara::Session: Save and Open Page

Sometimes you can’t tell why a test is passing when it should be failing or vice versa. Certainly, this method is a great debugging tool. At any point in an example you can write:

save_and_open_page

Therefore, it will store the page it fetched to a file and open it in your default web browser.

Whenever a test is doing something mysterious, this is my first debugging step. In the same vein, you’ll see that sample data is different than expected or the browser is on a totally different page than intended. Similarly, note that Capybara is saving a static page of HTML–it’s not clickable and you can’t do much of anything other than look at the page and inspect the DOM.

Within

The within method allows you to scope all your actions down to a certain section of the page. Not to mention, this is awesome when you want to focus your tests down to just one component. For instance:

within(“#articles”) do

page.should have_link(article.title, href: article_path(article))

end

So, this will only look for the link inside the node with ID “articles”, ignoring everything else on the page.

Since, the Session class represents a single user’s interaction with the system. Hence, the Session can use any of the underlying drivers. A session can be initialized manually like this:

session = Capybara::Session.new(:culerity, MyRackApp)

However, the application given as the second argument is optional. So, when running Capybara against an external page, you might want to leave it out:

session = Capybara::Session.new(:culerity)

session.visit(‘http://www.google.com’)

Not to mention, Session provides a number of methods for controlling the navigation of the page, such as visit, +current_path, and so on. Also, It delegates a number of methods to a Capybara::Document, representing the current HTML document. This allows interaction:

session.fill_in(‘q’, :with => ‘Capybara’)

session.click_button(‘Search’)

expect(session).to have_content(‘Capybara’)

Moreover, When using capybara/dsl, the Session is initialized automatically for you.

Instance Attribute Summary

#app -> Object readonly

Returns the value of attribute app.

 

#mode -> Object readonly

Therefore, returns the value of attribute mode.

 

#server -> Object readonly

Also, returns the value of attribute server.

 

#synchronized -> Object

Not to mention, returns the value of attribute synchronized.

Instance Method Summary

#accept_alert(text_or_options = nil, options = {}, &blk) -> String

So, execute the block, accepting a alert.

 

#accept_confirm(text_or_options = nil, options = {}, &blk) -> String

Therefore, execute the block, accepting a confirm.

 

#accept_prompt(text_or_options = nil, options = {}, &blk) -> String

Moreover, execute the block, accepting a prompt, optionally responding to the prompt.

 

#current_host -> String

Host of the current page.

 

#current_path -> String

Certainly, path of the current page, without any domain information.

 

#current_scope -> Object

#current_url -> String

Fully qualified URL of the current page.

 

#current_window -> Capybara::Window

Furhter, Current window.

 

#dismiss_confirm(text_or_options = nil, options = {}, &blk) -> String

So, execute the block, dismissing a confirm.

 

#dismiss_prompt(text_or_options = nil, options = {}, &blk) -> String

Also, execute the block, dismissing a prompt.

 

#document -> Object

#driver -> Object

#evaluate_script(script) -> Object

Thus, evaluate the given JavaScript and return the result.

 

#execute_script(script) -> Object

Further, execute the given script, not returning a result.

 

#go_back -> Object

However, move back a single entry in the browser’s history.

 

 

#go_forward -> Object

In the same vein, move forward a single entry in the browser’s history.

 

#html -> String (also: #body, #source)

Moreover, a snapshot of the DOM of the current document, as it looks right now (potentially modified by JavaScript).

 

#initialize(mode, app = nil) -> Session constructor

A new instance of Session.

 

#inspect -> Object

#open_new_window -> Capybara::Window

So, Open new window.

 

#raise_server_error! -> Object

Further, raise errors encountered in the server.

 

#reset! -> Object (also: #cleanup!, #reset_session!)

Now, reset the session (i.e. remove cookies and navigate to blank page).

 

#response_headers -> Hash{String => String}

Therefore, returns a hash of response headers.

 

#save_and_open_page(path = nil) -> Object

Save a snapshot of the page and open it in a browser for inspection.

 

#save_and_open_screenshot(path = nil, options = {}) -> Object

Save a screenshot of the page and open it for inspection.

 

#save_page(path = nil) -> String

Save a snapshot of the page.

 

#save_screenshot(path = nil, options = {}) -> String

Save a screenshot of page.

 

#status_code -> Integer

Returns the current HTTP status code as an Integer.

 

#switch_to_window(window = nil, options = {}) -> Capybara::Window

Window that has been switched to.

 

#visit(url) -> Object

Navigate to the given URL.

 

#window_opened_by(options = {}, &block) -> Capybara::Window

Get the window that has been opened by the passed block.

 

#windows -> Array<Capybara::Window>

Get all opened windows.

 

#within(*args) -> Object

Executes the given block within the context of a node.

 

#within_fieldset(locator) -> Object

Execute the given block within the a specific fieldset given the id or legend of that fieldset.

 

#within_frame(frame_handle) -> Object

Execute the given block within the given iframe using given frame name or index.

 

#within_table(locator) -> Object

Execute the given block within the a specific table given the id or caption of that table.

 

#within_window(window_or_handle) -> Object

So, this method does the following:.

Methods included from SessionMatchers

#assert_current_path, #assert_no_current_path, #has_current_path?, #has_no_current_path?

Make your resume stand out and become a Certified Capybara Testing Professional. So, Try free practice tests here!

A great career is just a certification away. So, practice and validate your skills to become Certified Capybara Testing Professional