Selenium/Ruby/Very Basic Howto

WORK IN PROGRESS, INCOMPLEETE

The work of creating browser tests is all conceptual and abstracted until the very last step. Here is a step by step description of a proper test development process.

Describe the behavior by which we will know that the feature being tested functions correctly
If you've installed all the stuff you need, you create a feature file in the /tests/browser/features folder, for example my_test.feature.

In my_test.feature, you'll have a Scenario and a Feature:

Feature: My First Cucumber Test

Scenario: My First Scenario Given I am on my page that has the setup I need to test When I click the link on my page that takes me somewhere I need to test Then I see the special thing that tells me that the test has passed

Generate the steps file
You execute the tests at this point

$ bundle exec cucumber features/my_test.feature

And the resulting output tells you what comes next:

Feature: My First Cucumber Test

Scenario: My First Scenario                                              # features/my_test.feature:3 Given I am on my page that has the setup I need to test                # features/my_test.feature:4 When I click the link on my page that takes me somewhere I need to test # features/my_test.feature:5 Then I see the special thing that tells me that the test has passed    # features/my_test.feature:6

1 scenario (1 undefined) 3 steps (3 undefined) 0m3.074s

You can implement step definitions for undefined steps with these snippets:

Given(/^I am on my page that has the setup I need to test$/) do pending # express the regexp above with the code you wish you had end

When(/^I click the link on my page that takes me somewhere I need to test$/) do pending # express the regexp above with the code you wish you had end

Then(/^I see the special thing that tells me that the test has passed$/) do pending # express the regexp above with the code you wish you had end

Fill in a step in the test
This work is done step by step by step. Take the first "pending" step and paste it into a file in the /features/step_definitions directory with the title "my_test_steps.rb"

Given(/^I am on my page that has the setup I need to test$/) do pending # express the regexp above with the code you wish you had end

and fill in the pending step

Given(/^I am on my page that has the setup I need to test$/) do visit(MyPage) end

and run the test and see the failure:

$ bundle exec cucumber features/my_test.feature Feature: My First Cucumber Test

Scenario: My First Scenario                                              # features/my_test.feature:3 Given I am on my page that has the setup I need to test                # features/step_definitions/my_test_steps.rb:1 uninitialized constant MyPage (NameError) ./features/step_definitions/my_test_steps.rb:2:in `/^I am on my page that has the setup I need to test$/' features/my_test.feature:4:in `Given I am on my page that has the setup I need to test' When I click the link on my page that takes me somewhere I need to test # features/my_test.feature:5 Then I see the special thing that tells me that the test has passed    # features/my_test.feature:6

Failing Scenarios: cucumber features/my_test.feature:3 # Scenario: My First Scenario

1 scenario (1 failed) 3 steps (1 failed, 2 undefined) 0m2.731s

Make the Page Object (if it does not already exist)
In the features/support/pages directory you'll need a file called my_page.rb. Inside you'll need to put

class MyPage include PageObject include URL page_url URL.url("<%=params[:article_name]%><%=params[:hash]%>")

end

There is a little bit of magic happening in that business of "<%=params[:article_name]%><%=params[:hash]%>" but don't worry about that for now...

Run the test again and the error is gone:

$ bundle exec cucumber features/my_test.feature Feature: My First Cucumber Test

Scenario: My First Scenario                                              # features/my_test.feature:3 Given I am on my page that has the setup I need to test                # features/step_definitions/my_test_steps.rb:1 When I click the link on my page that takes me somewhere I need to test # features/my_test.feature:5 Then I see the special thing that tells me that the test has passed    # features/my_test.feature:6

1 scenario (1 undefined) 3 steps (2 undefined, 1 passed) 0m5.427s

Implement the When step
Go back to /features/step_definitions/my_test_steps.rb and add the pending step

When(/^I click the link on my page that takes me somewhere I need to test$/) do pending # express the regexp above with the code you wish you had end

Decide what the pending step should do:

When(/^I click the link on my page that takes me somewhere I need to test$/) do on(MyPage).my_special_link_element.click end

and run the test to watch it fail:

$ bundle exec cucumber features/my_test.feature Feature: My First Cucumber Test

Scenario: My First Scenario                                              # features/my_test.feature:3 Given I am on my page that has the setup I need to test                # features/step_definitions/my_test_steps.rb:1 When I click the link on my page that takes me somewhere I need to test # features/step_definitions/my_test_steps.rb:5 undefined method `my_special_link_element' for # (NoMethodError) ./features/step_definitions/my_test_steps.rb:6:in `/^I click the link on my page that takes me somewhere I need to test$/' features/my_test.feature:5:in `When I click the link on my page that takes me somewhere I need to test' Then I see the special thing that tells me that the test has passed    # features/my_test.feature:6

Failing Scenarios: cucumber features/my_test.feature:3 # Scenario: My First Scenario

1 scenario (1 failed) 3 steps (1 failed, 1 undefined, 1 passed)

This tells us that the MyPage object does not contain a method called "my_special_link_element", which of course is true.

So far everything we have done has been conceptual and abstract. This next part is where we actually tie the test to the page being tested. Read over the documentation at https://github.com/cheezy/page-object/wiki/Elements and then add this to your page object:

class MyPage include PageObject include URL page_url URL.url("<%=params[:article_name]%><%=params[:hash]%>")

a(:my_special_link, href: /Special:UserLogin/) end

Note that appending "_element" to a label in a Page Object has some special properties, noted in the documentation linked above.

Run the test again:

$ bundle exec cucumber features/my_test.feature Feature: My First Cucumber Test

Scenario: My First Scenario                                              # features/my_test.feature:3 Given I am on my page that has the setup I need to test                # features/step_definitions/my_test_steps.rb:1 When I click the link on my page that takes me somewhere I need to test # features/step_definitions/my_test_steps.rb:5 Then I see the special thing that tells me that the test has passed    # features/my_test.feature:6

1 scenario (1 undefined) 3 steps (1 undefined, 2 passed) 0m5.609s