Ruby Raider

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:.

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:

Settings

Three keys in config/config.yml control all of this:

timeout: 10
strict: true
actionability: true

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

For the full reference, see the Ruby Raider README.