Class: Capybara::UI::FieldGroup

Inherits:
Widget
  • Object
show all
Defined in:
lib/capybara/ui/widgets/field_group.rb

Overview

TODO:

Explain how to use locators when defining fields, including what happens when locators are omitted.

A group of form fields.

Direct Known Subclasses

Form

Constant Summary

Constants included from Capybara::UI

VERSION

Instance Attribute Summary

Attributes inherited from Widget

#root

Field definition macros collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Widget

action, #class?, #classes, #click, #double_click, filter, filter?, find_all_in, find_in, #has_action?, #hover, #html, #id, #initialize, not_present_in?, present_in?, #right_click, root, selector, #text, #to_cell, #to_s, #value, widget_delegator

Methods included from Widgets::DSL

#form, #list, #widget

Methods included from WidgetParts::Container

#has_widget?, #not_visible?, #visible?, #widget, #widgets

Methods included from Capybara::UI

#deprecate

Methods included from Constructors

#Decimal, #Integer, #Widget

Methods included from WidgetParts::Struct

included

Constructor Details

This class inherits a constructor from Capybara::UI::Widget

Class Method Details

.check_box(name, locator = nil) ⇒ Object

TODO:

Handle checkbox access when the field is disabled (raise an exception?)

Creates a new checkbox accessor.

Adds the following methods to the widget:

<name>

Gets the current checkbox state, as a boolean. Returns true if the corresponding check box is checked, false otherwise.

<name>=

Sets the current checkbox state. Pass true to check the checkbox, false otherwise.

Examples:

# Given the following HTML:
#
# <form>
#   <p>
#     <label for="checked-box">
#     <input type="checkbox" value="1" id="checked-box" checked>
#   </p>
#   <p>
#     <label for="unchecked-box">
#     <input type="checkbox" value="1" id="unchecked-box">
#   </p>
# </form>
class MyFieldGroup < Capybara::UI::FieldGroup
  root 'form'

  check_box :checked_box, 'checked-box'
  check_box :unchecked_box, 'unchecked-box'
end

form = widget(:my_field_group)

form.checked_box          #=> true
form.unchecked_box        #=> false

form.unchecked_box = true
form.unchecked_box        #=> true

Parameters:

  • name —

    the name of the checkbox accessor.

  • locator (defaults to: nil) —

    the locator for the checkbox. If nil the locator will be derived from name.



73
74
75
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 73

def self.check_box(name, locator = nil)
  field name, locator, CheckBox
end

.default_locator(type = nil, &block) ⇒ Object 



10
11
12
13
14
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 10

def self.default_locator(type = nil, &block)
  alias_method :name_to_locator, type if type

  define_method :name_to_locator, &block if block
end

.field(name, locator, type) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Defines a new field.

Parameters:

  • name —

    the name of the field accessor.

  • locator —

    the field locator.

  • type —

    the field class name.

Raises:

  • (TypeError) 


84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 84

def self.field(name, locator, type)
  raise TypeError, "can't convert `#{name}' to Symbol" \
    unless name.respond_to?(:to_sym)

  field_names << name.to_sym

  label     = name.to_s.gsub(/_/, ' ').capitalize
  locator ||= label

  widget name, locator, type do
    define_method :label do
      label
    end
  end

  define_method "#{name}=" do |val|
    widget(name).set val
  end

  define_method name do
    widget(name).get
  end
end

.field_names ⇒ Set

The names of all the fields that belong to this field group.

Field names are automatically added to this group as long as you use the field definition macros.

Returns:

  • (Set) —

    the field names.

See Also:



24
25
26
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 24

def self.field_names
  @field_names ||= Set.new
end

.radio_button(name, locator = nil) ⇒ Object

Creates a new radio button group accessor.

Adds the following methods to the widget:

<name>

Gets the text of the current checked button, or nil, if no button is checked.

<name>_value

Gets the value of the current checked button, or nil, if no button is checked.

<name>=

Checks a button in the current container. Pass the text of the label or the id or value of the button you want to choose.

Examples:

# Given the following HTML:
#
# <form>
#   <p class='checked'>
#     <label for="checked">Checked button</label>
#     <input type="radio" id="checked" name="c" value="checked_value" checked>
#     <label for="checked_two">Checked button two</label>
#     <input type="radio" id="checked_two" name="c" value="checked_two_value">
#   </p>
#   <p class='unchecked'>
#     <label for="unchecked">Unchecked button</label>
#     <input type="radio" id="unchecked" name="u" value="unchecked_value_one">
#     <label for="unchecked_two">Unchecked button two</label>
#     <input type="radio" id="unchecked_two" name="u" value="unchecked_value_two">
#   </p>
# </form>
class MyFieldGroup < Capybara::UI::FieldGroup
  root 'form'

  radio_button :checked, '.checked'
  radio_button :unchecked, '.unchecked'
end

form = widget(:my_field_group)

form.checked                            #=> "Checked button"
form.unchecked                          #=> nil

form.unchecked = "Unchecked button" # Choose by label text
form.unchecked                          #=> "Unchecked button"
form.unchecked_value                    #=> "unchecked_value_one"

form.unchecked = "unchecked_two" # Choose by id
form.unchecked                          #=> "Unchecked button two"
form.unchecked_value                    #=> "unchecked_value_two"

form.unchecked = "unchecked_value_one" # Choose by value
form.unchecked                          #=> "Unchecked button"

Parameters:

  • name —

    the name of the radio_button group accessor.

  • locator (defaults to: nil) —

    the locator for the radio_button group.



232
233
234
235
236
237
238
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 232

def self.radio_button(name, locator = nil)
  field name, locator, RadioButton

  define_method "#{name}_value" do
    widget(name).value
  end
end

.select(name, locator = nil) ⇒ Object

TODO:

Handle select access when the field is disabled (raise an exception?)

TODO:

Raise an exception when an option doesn’t exist.

TODO:

Allow passing the option value to set an option.

TODO:

Ensure an option with no text returns the empty string.

TODO:

What to do when nil is passed to the writer?

Creates a new select accessor.

Adds the following methods to the widget:

<name>

Gets the text of the current selected option, or nil, if no option is selected.

<name>_value

Gets the value of the current selected option, or nil, if no option is selected.

<name>=

Selects an option on the current select. Pass the text or value of the option you want to select.

Examples:

# Given the following HTML:
#
# <form>
#   <p>
#     <label for="selected">
#     <select id="selected">
#       <option value ="1s" selected>Selected option</option>
#       <option value ="2s">Selected option two</option>
#     </select>
#   </p>
#   <p>
#     <label for="unselected">
#     <select id="unselected">
#       <option value="1u">Unselected option</option>
#       <option value="2u">Unselected option two</option>
#     </select>
#   </p>
# </form>
class MyFieldGroup < Capybara::UI::FieldGroup
  root 'form'

  select :selected, 'selected'
  select :unselected, 'unselected'
end

form = widget(:my_field_group)

form.selected                         #=> "Selected option"
form.selected_value                   #=> "1s"

# Select by text
form.unselected                       #=> nil
form.unselected = "Unselected option"
form.unselected                       #=> "Unselected option"

# Select by value
form.unselected = "2u"
form.unselected                       #=> "Unselected option two"
form.unselected_value                 #=> "2u"

Parameters:

  • name —

    the name of the select accessor.

  • locator (defaults to: nil) —

    the locator for the select. If nil the locator will be derived from name.



170
171
172
173
174
175
176
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 170

def self.select(name, locator = nil)
  field name, locator, Select

  define_method "#{name}_value" do
    widget(name).value
  end
end

.text_field(name, locator = nil) ⇒ Object

TODO:

Handle text field access when the field is disabled (raise an exception?)

Creates a new text field accessor.

Adds the following methods to the widget:

<name>

Returns the current text field value, or nil if no value has been set.

<name>=

Sets the current text field value.

<name>? Returns true if the current text field has content or

+false+ otherwise

Examples:

# Given the following HTML:
#
# <form>
#   <p>
#     <label for="text-field">
#     <input type="text" value="Content" id="text-field">
#   </p>
#   <p>
#     <label for="empty-field">
#     <input type="text" id="empty-field">
#   </p>
# </form>
class MyFieldGroup < Capybara::UI::FieldGroup
  root 'form'

  text_field :filled_field, 'text-field'
  text_field :empty_field, 'empty-field'
end

form = widget(:my_field_group)

form.filled_field                #=> "Content"
form.empty_field                 #=> nil

form.filled_field?                #=> true
form.empty_field?                 #=> false

form.empty_field = "Not anymore"
form.empty_field                 #=> "Not anymore"

Parameters:

  • name —

    the name of the text field accessor.

  • locator (defaults to: nil) —

    the locator for the text field. If nil the locator will be derived from name.



287
288
289
290
291
292
293
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 287

def self.text_field(name, locator = nil)
  define_method "#{name}?" do
    widget(name).content?
  end

  field name, locator, TextField
end

Instance Method Details

#fields ⇒ Object

Returns This field group’s field widgets.

Returns:

  • This field group’s field widgets.



298
299
300
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 298

def fields
  self.class.field_names.map { |name| widget(name) }
end

#set(attributes) ⇒ Object

Sets the given form attributes.

Parameters:

  • attributes (Hash) —

    the attributes and values we want to set.

Returns:

  • the current widget.



307
308
309
310
311
312
313
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 307

def set(attributes)
  attributes.each do |k, v|
    send "#{k}=", v
  end

  self
end

#to_table ⇒ Array<Array>

Converts the current field group into a table suitable for diff’ing with Cucumber::MultilineArgument::DataTable.

Field labels are determined by the widget name.

Field values correspond to the return value of each field’s to_s.

Returns:

  • (Array<Array>) —

    the table.



323
324
325
326
327
328
 
# File 'lib/capybara/ui/widgets/field_group.rb', line 323

def to_table
  headers = fields.map { |field| field.label.downcase }
  body    = fields.map { |field| field.to_s.downcase }

  [headers, body]
end