5. Forms

5.1 Text Field

Input

To simulate a user typing into a text field, use the set method:

browser.text_field.set("first")
p browser.text_field.value
#=> "first"

Note that the set method will overwrite the previous text:

browser.text_field.set("first")
browser.text_field.set("second")
p browser.text_field.value
#=> "second"

If you want to add additional text, use the append method instead:

browser.text_field.set("first")
browser.text_field.append("second")
p browser.text_field.value
#=> "firstsecond"

To make the text field blank, use the clear method:

browser.text_field.clear
p browser.text_field.value
#=> ""

Inspect

The text that a user sees in a text field is stored in the input’s value attribute. Therefore, to get the text of the text field, use the standard attribute methods:

browser.text_field.set('some text')
p browser.text_field.value
#=> "some text"

Textarea

While textareas can be located differently than text fields, they are set and inspected using the same methods. What makes textareas special on web pages is that they can have multi-line text. A real user would create multiple lines by pressing the Enter key on the keyboard. With Watir, you can do the exact same keystrokes:

browser.textarea.set('first line', :return, 'second line')
puts browser.textarea.value
#=> first line
#=> second line

However, it is often more convenient to send a double-quoted String with the line break character (“\n”):

browser.textarea.set("first line\nsecond line")
puts browser.textarea.value
#=> first line
#=> second line

5.2 Select List

A select list, often called a dropdown, consists of:

  • A select element - the overall control
  • Option elements - the items that the user picks

The HTML:

<select id="language">
  <option value="ar">Arabic</option>
  <option value="en">English</option>
  <option value="hi">Hindi</option>
  <option value="zh">Mandarin</option>
  <option value="es">Spanish</option>
</select>

Input

The most straight forward way to select an option is to use the text visible to the user:

# Exact match
browser.select_list.select('English')

# Partial match
browser.select_list.select(/Eng/)

For localized applications, the visible text may change based on the language. For example, a user may see “English” or “Anglais” depending on if they are viewing the page in English or French. In this scenario, it is better to select options based on their value attribute, which is language independent.

browser.select_list.select_value('en')

If you need more control, you can directly locate the option element and call its select method.

# Select option based on multiple attributes
browser.select_list.option(text: 'English', value: 'en').select

# Select first option
browser.select_list.option.select

# Select last option
browser.select_list.options.last.select

Inspect

To check the currently selected option, you can use the value method. For example, let us assume that “English” has been selected.

browser.select_list.value
#=> "en"

Note that the returned value is the value attribute of the selected option. If you want other details of the selected option, for example the user visible text, you can use the selected_options method. This will return an Array of option elements, where the first and only element is the one of interest. 

browser.select_list.selected_options.first.text
#=> "English"

Multi-Select

By default, the select element only allows a user to select a single option. An application can allow for multiple selections by adding the multiple attribute.

<select id="language" multiple>
  <option value="ar">Arabic</option>
  <option value="en">English</option>
  <option value="hi">Hindi</option>
  <option value="zh">Mandarin</option>
  <option value="es">Spanish</option>
</select>

The Watir methods available to multi-select lists are the same as a dropdown list. Selecting multiple options is as simple as calling select or select_value multiple times.

browser.select_list.select_value('ar')
browser.select_list.selected_options.map(&:text)
#=> ["Arabic"]

browser.select_list.select('English')
browser.select_list.selected_options.map(&:text)
#=> ["Arabic", "English"]

You will notice that each selection does not clear the previous selections. If you want to unselect the selected options, call the clear method.

browser.select_list.clear
browser.select_list.selected_options.map(&:text)
#=> []

When inspecting the selected options, you should use the selected_options approach over the value method. The value only returns the first selected option, which will be wrong when multiple are selected.

browser.select_list.select('Arabic')
browser.select_list.select('English')
browser.select_list.selected_options.map(&:value) # good
#=> ["ar", "en"]
browser.select_list.value # bad
#=> "ar"

Look-alikes

More and more web pages are using controls that look like dropdowns, but are actually a combination of links, text fields, etc. In other words, there is no select element in the HTML. These cannot be located and interacted with using the select_list method.

For example, the Dojo Combobox looks like a select list, but creates the following HTML (simplified to fit the book):

<div id="widget_stateSelect" role="combobox">
  <div class="dijitArrowButton">
    <input value="? " type="text" tabindex="-1">
  </div>
  <div>
    <input id="stateSelect" value="Alabama">
  </div>
</div>
<div>
  <div>
    <div class="dijitMenuItem">Alabama</div>
    <div class="dijitMenuItem">Alaska</div>
    <div class="dijitMenuItem">American Samoa</div>
  </div>
</div>

In this case, you need to interact with the individual elements that create the control.

# Expand combo box
combo_box = browser.div(id: 'widget_stateSelect')
combo_box.div(class: 'dijitArrowButton').click
 
# Select an option
dropdown = browser.div(id: 'widget_stateSelect_dropdown')
dropdown.div(class: 'dijitMenuItem', text: 'Alabama').when_present.click
 
# Get the selected option
browser.text_field(id: 'stateSelect').value
#=> "Alabama"

5.3 Checkbox

Input

A checkbox is checked by using the set method:

browser.checkbox.set

It can be unchecked by using the clear method:

browser.checkbox.clear

The set method can take a boolean parameter, where true will check the box and false will uncheck the box:

# Check
browser.checkbox.set(true)

# Uncheck
browser.checkbox.set(false)

This is useful when the checkbox needs to be set based on a condition. For example, an if-else statement:

if condition_met?
  browser.checkbox.set
else
  browser.checkbox.clear
end

Can be re-written as:

browser.checkbox.set(condition_met?)

Inspect

The state of the checkbox, whether it is checked or unchecked, can be determined by the set? method:

browser.checkbox.set
p browser.checkbox.set?
#=> true

browser.checkbox.clear
p browser.checkbox.set?
#=> false

5.4 Radio

Input

A radio button is selected by using the set method:

browser.radio.set

Inspect

The set? method is used to determine if a radio button is turned on:

p browser.radio.set?
#=> false

browser.radio.set

p browser.radio.set?
#=> true

Up next

6. Element Collections