Writing tests
This page is for tests you write by hand. Recorded tests follow the same rules. Every project loads the Raider runtime (ruby_raider/runtime), which adds locators, waiting and assertions to Selenium itself: there is no implicit wait and no sleep.
A test, start to finish
A page object finds the elements. The spec uses them and checks the result:
# page_objects/pages/login.rb
require_relative '../abstract/page'
class Login < Page
def url(_page)
'index.php?rt=account/login'
end
def login(username, password)
username_field.send_keys(username)
password_field.send_keys(password)
login_button.click
end
private
def username_field
driver.find_element(label: 'Login name')
end
def password_field
driver.find_element(label: 'Password')
end
def login_button
driver.find_element(by_role('button', name: 'Login'))
end
end
# spec/login_spec.rb
require_relative '../helpers/spec_helper'
require_relative '../page_objects/pages/login'
require_relative '../page_objects/pages/account'
describe 'Login' do
let(:login_page) { Login.new(driver) }
let(:account_page) { Account.new(driver) }
it 'welcomes the user back' do
login_page.visit
login_page.login('aguspe', ENV.fetch('RAIDER_SECRET_PASSWORD'))
expect { account_page.welcome_message }.to have_text('Welcome back')
end
end
Nothing waits by hand: find_element waits for each field, click waits until the button can be clicked, and have_text retries until the message appears. To start a new one, raider g page login creates page_objects/pages/login.rb with class LoginPage < Page, and raider g spec login creates spec/login_page_spec.rb; see Scaffolding.
Locators
Find elements the way a person sees them:
| Key | Finds | Example |
|---|---|---|
label: |
the field with that label, aria-label or aria-labelledby |
driver.find_element(label: 'Email') |
placeholder: |
the field with that placeholder | driver.find_element(placeholder: 'Search') |
alt: |
the element with that alt text, such as an image |
driver.find_element(alt: 'Logo') |
title: |
the element with that title |
driver.find_element(title: 'Close') |
text: |
the innermost element whose text contains it | driver.find_element(text: 'Sign in') |
test_id: |
the element whose data-testid equals it |
driver.find_element(test_id: 'submit') |
Selenium's own keys still work: id:, css:, xpath:, name:, class: and link_text:.
- Text keys match part of the text and ignore extra spaces. For the whole text, pass the value and
{ exact: true }in an array:driver.find_element(label: ['Email', { exact: true }]). test_id:reads another attribute when you settest_id_attribute: data-qainconfig/config.yml,RAIDER_TEST_ID_ATTRIBUTE=data-qa, orRaider.test_id_attribute = 'data-qa'.
By role
by_role finds an element by its ARIA role and name, the way a screen reader does:
driver.find_element(by_role('button', name: 'Login'))
driver.find_element(by_role('button', name: 'Save', exact: true))
driver.find_element(by_role('heading', level: 1))
driver.find_element(by_role('dialog', include_hidden: true))
name: matches part of the name unless you pass exact: true. level: is for headings only.
Strict matching
find_element fails with Raider::AmbiguousMatch when a locator matches more than one element. The message lists the first three. Narrow the locator, or use driver.find_elements, which never fails on many matches.
Waiting and actions
find_element and find_elements wait for a match, for up to timeout seconds. A missing element fails with no such element: { id: "x" } (waited 10s). find_elements returns [] at the deadline.
Before an action, the runtime waits until the element is ready:
| Action | Waits until the element is |
|---|---|
click |
visible, enabled, not inert, stable and not covered |
send_keys |
visible, enabled, editable and not inert |
clear |
visible, enabled, editable and not inert |
submit |
visible, enabled and not inert |
If the element is not ready in time, the action raises Raider::NotActionable, which names the check that failed and how long it waited.
force: true skips the checks for one call. The element must still be on the page:
login_button.click(force: true)
Assertions
Write the element lookup in a block. The matcher looks the element up again on every try and retries until the page matches or timeout runs out:
expect { account_page.welcome_message }.to have_text('Welcome back')
expect { driver.find_element(label: 'Email') }.to have_value('ana@example.com')
expect { driver.find_element(test_id: 'spinner') }.to be_hidden
expect(driver).to have_title('My Account')
| Matcher | Passes when |
|---|---|
have_text('x'), have_text('x', exact: true) |
the element's text contains, or equals, x |
have_value('x') |
a field holds x |
have_attribute('name', 'x') |
the element has that attribute, with that value if you pass one |
be_visible, be_hidden |
the element is shown, or is hidden or gone |
be_enabled, be_disabled |
the element can, or cannot, be used |
be_checked |
a checkbox or radio button is ticked |
have_count(3) |
the block returns that many elements, for example expect { driver.find_elements(css: '.item') }.to have_count(3) |
have_title('x'), have_url('x') |
the page has exactly that title, or that address (or matches a Regexp you pass) |
have_element(label: 'Email'), have_css('.x'), have_xpath('//x') |
the page has a matching element |
Pass wait: 5 to one matcher to change its time, for example be_visible(wait: 5).
A block also retries any other RSpec value matcher:
expect { driver.find_element(id: 'status').text }.to eq('done')
Three limits to know:
expect(value)without a block does not retry for a value matcher such aseq. The value is read once.- A block with side effects runs once per try.
- RSpec's block matchers (
raise_error,change,output,throw_symbol,yield_*) work as in RSpec and do not retry.
Settings
Three keys in config/config.yml control all of this:
timeout: 10
strict: true
actionability: true
timeoutis the number of seconds that finds, actions and assertions wait before failing. Test timeout on the Files tab sets it.strictmakesfind_elementfail when a locator matches more than one element.actionabilitymakes actions wait until the element is ready.
raider u strict on|off and raider u actionability on|off change them. For one run, set RAIDER_TIMEOUT, RAIDER_STRICT or RAIDER_ACTIONABILITY. RAIDER_QUIET=1 hides the one-line [raider] actionability on notice.
Also in every project
- Failure trace. A failing test keeps a step-by-step trace in
raider-results/attachments/<n>-trace.zip. Open it on the Dashboard with View trace.TRACE=onkeeps passing tests too;TRACE=offturns it off. - Failure video. A failing test keeps a video, attached to the report.
VIDEO=offturns it off for one run. - Network mocking. Answer a request with your own response, or block it, on Chrome, Edge and Firefox:
mock_request('**/api/users', json: { users: [] }) block_request('**/*.png') - Screenshot comparison.
match_screenshot('home')compares the page with a saved picture.SCREENSHOTS=updatesaves new ones. See Screenshot comparison. - Login reuse. Tag an example
:logged_into log in once and reuse the session. - Reporting. raider_reporter writes the results to
raider-results/, which the Dashboard reads.
For the full reference, see the Ruby Raider README.