capybara-ui 0.10.0 → 1.0.0

data/lib/capybara/ui/text_table/cell_text.rb

@@ -0,0 +1,9 @@
+module Capybara
+  module UI
+    class TextTable
+      class CellText < String
+        include InstanceConversions
+      end
+    end
+  end
+end

data/lib/capybara/ui/text_table/mapping.rb

@@ -0,0 +1,42 @@
+module Capybara
+  module UI
+    class TextTable
+      class Mapping
+        def initialize(settings = {})
+          self.key               = settings[:key]
+          self.value_transformer = transformer(settings[:value_transformer], :pass)
+          self.key_transformer   = transformer(settings[:key_transformer], :keyword)
+        end
+
+        def set(instance, row, key, value)
+          row[transform_key(instance, key)] = transform_value(instance, value)
+        end
+
+        private
+
+        attr_accessor :key, :value_transformer, :key_transformer
+
+        def transform_key(_, k)
+          key || key_transformer.(k)
+        end
+
+        def transform_value(instance, value)
+          instance.instance_exec(value, &value_transformer)
+        end
+
+        def transformer(set, fallback)
+          case set
+          when Symbol
+            Transformations.send(set)
+          when Proc
+            set
+          when nil
+            Transformations.send(fallback)
+          else
+            raise ArgumentError, "can't convert #{set.inspect} to transformer"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/text_table/transformations.rb

@@ -0,0 +1,15 @@
+module Capybara
+  module UI
+    class TextTable
+      module Transformations
+        def self.keyword
+          ->(val) { val.squeeze(' ').strip.gsub(' ', '_').sub(/\?$/, '').to_sym }
+        end
+
+        def self.pass
+          ->(val) { val }
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/text_table/void_mapping.rb

@@ -0,0 +1,10 @@
+module Capybara
+  module UI
+    class TextTable
+      class VoidMapping
+        def set(*)
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/version.rb

@@ -0,0 +1,5 @@
+module Capybara
+  module UI
+    VERSION = '1.0.0'
+  end
+end

data/lib/capybara/ui/widgets.rb

@@ -0,0 +1,63 @@
+# This file describes the organization of the major Widget API components.
+#
+# === Parts
+#
+# Widget parts encapsulate the set of behaviours that constitute a widget.
+module Capybara
+  module UI
+    module Constructors
+      def Widget(*selector, &block)
+        if block_given?
+          WidgetClass.new(selector.flatten) do
+            define_method :value do
+              block.call(text)
+            end
+          end
+        else
+          WidgetClass.new(selector.flatten)
+        end
+      end
+
+      alias_method :String, :Widget
+
+      def Integer(*selector)
+        Widget(selector) { |text| Kernel::Integer(text) }
+      end
+
+      require 'bigdecimal'
+
+      def Decimal(*selector)
+        Widget(selector) { |text|
+          # ensure we can convert to float first
+          Float(text) && BigDecimal.new(text)
+        }
+      end
+    end
+
+    extend Constructors
+  end
+end
+
+module Capybara::UI::WidgetParts; end
+
+require 'capybara/ui/widgets/parts/struct'
+require 'capybara/ui/widgets/parts/container'
+
+require 'capybara/ui/widgets/cucumber_methods'
+require 'capybara/ui/widgets/dsl'
+require 'capybara/ui/widgets/widget_class'
+require 'capybara/ui/widgets/widget_name'
+require 'capybara/ui/widgets/widget'
+require 'capybara/ui/widgets/widget/node_filter'
+require 'capybara/ui/widgets/list_item'
+require 'capybara/ui/widgets/list'
+require 'capybara/ui/widgets/field'
+require 'capybara/ui/widgets/check_box'
+require 'capybara/ui/widgets/radio_button'
+require 'capybara/ui/widgets/select'
+require 'capybara/ui/widgets/text_field'
+require 'capybara/ui/widgets/field_group'
+require 'capybara/ui/widgets/form'
+require 'capybara/ui/widgets/document'
+require 'capybara/ui/widgets/table'
+require 'capybara/ui/widgets/string_value'

data/lib/capybara/ui/widgets/check_box.rb

@@ -0,0 +1,28 @@
+module Capybara
+  module UI
+    # A check box.
+    class CheckBox < Field
+      # @!method set(value)
+      #   Checks or unchecks the current checkbox.
+      #
+      #   @param value [Boolean] +true+ to check the checkbox, +false+
+      #     otherwise.
+      def_delegator :root, :set
+
+      # @return [Boolean] +true+ if the checkbox is checked, +false+
+      #   otherwise.
+      def get
+        !! root.checked?
+      end
+
+      def to_cell
+        to_s
+      end
+
+      # @return +"yes"+ if the checkbox is checked, +"no"+ otherwise.
+      def to_s
+        get ? 'yes' : 'no'
+      end
+    end
+  end
+end

data/lib/capybara/ui/widgets/cucumber_methods.rb

@@ -0,0 +1,75 @@
+module Capybara
+  module UI
+    module CucumberMethods
+      begin
+        require 'cucumber/ast/table'
+
+        # Compares this widget with the given Cucumber +table+.
+        #
+        # === Example
+        #
+        #   Then(/^some step that takes in a cucumber table$/) do |table|
+        #     widget(:my_widget).diff table
+        #   end
+        #
+        # Pass +ignore_case: true+, for a case-insensitive table match
+        #
+        # === Example
+        #
+        #   Then(/^some step that takes in a cucumber table$/) do |table|
+        #     widget(:my_widget).diff table, ignore_case: true
+        #   end
+        #
+        def diff(table, wait_time = Capybara.default_max_wait_time, ignore_case: false)
+          to_table = self.to_table
+
+          if ignore_case == true
+            table = downcase_table(table)
+            to_table = downcase_array(to_table)
+          end
+
+          table.diff!(to_table) || true
+        end
+
+        private
+
+        def downcase_table(table)
+          new_cucumber_table downcase_array(table.raw)
+        end
+
+        def downcase_array(array)
+          array.map do |item|
+            case item
+            when String
+              item.downcase
+            when Array
+              downcase_array(item)
+            when Hash
+              downcase_hash(item)
+            end
+          end
+        end
+
+        def downcase_hash(hash)
+          hash.each do |k, v|
+            case v
+            when String
+              hash[k] = v.downcase
+            when Array
+              downcase_array(v)
+            when Hash
+              downcase_hash(v)
+            end
+          end
+        end
+
+        def new_cucumber_table(table)
+          Cucumber::Ast::Table.new(table)
+        end
+
+      rescue LoadError
+        # *crickets*
+      end
+    end
+  end
+end

data/lib/capybara/ui/widgets/document.rb

@@ -0,0 +1,21 @@
+module Capybara
+  module UI
+    class Document
+      include WidgetParts::Container
+
+      def initialize(widget_lookup_scope)
+        self.widget_lookup_scope = widget_lookup_scope or raise 'No scope given'
+      end
+
+      def root
+        Capybara.current_session
+      end
+
+      def body
+        xml = Nokogiri::HTML(Capybara.page.body).to_xml
+
+        Nokogiri::XML(xml, &:noblanks).to_xhtml
+      end
+    end
+  end
+end

data/lib/capybara/ui/widgets/dsl.rb

@@ -0,0 +1,49 @@
+module Capybara
+  module UI
+    module Widgets
+      module DSL
+        # Declares a new form widget.
+        #
+        # See features/role.feature.
+        def form(name, *rest, &block)
+          widget name, *rest, Capybara::UI::Form, &block
+        end
+
+        # Declares a new list widget.
+        #
+        # See features/roles/list.feature.
+        def list(name, *rest, &block)
+          widget name, *rest, Capybara::UI::List, &block
+        end
+
+        # Declares a new child widget.
+        #
+        # See https://github.com/mojotech/capybara-ui/blob/master/features/roles/widget.feature
+        def widget(name, selector_or_parent, parent = Widget, &block)
+          raise ArgumentError, "`#{name}' is a reserved name" \
+            if WidgetParts::Container.instance_methods.include?(name.to_sym)
+
+          case selector_or_parent
+          when String, Array, Proc
+            selector, type = selector_or_parent, parent
+          when Class
+            selector, type = selector_or_parent.selector, selector_or_parent
+          else
+            raise ArgumentError, "wrong number of arguments (#{rest.size} for 1)"
+          end
+
+          raise TypeError, "can't convert `#{type}' to Widget" \
+            unless type.methods.include?(:selector)
+
+          raise ArgumentError, "missing selector" unless selector || type.selector
+
+          child = WidgetClass.new(selector, type, &block)
+
+          const_set(Capybara::UI::WidgetName.new(name).to_sym, child)
+
+          child
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/widgets/field.rb

@@ -0,0 +1,24 @@
+module Capybara
+  module UI
+    # A form field.
+    class Field < Widget
+      def self.root(selector)
+        super String === selector ? [:field, selector] : selector
+      end
+
+      # @return This field's value.
+      #
+      # Override this to get the actual value.
+      def get
+        raise NotImplementedError
+      end
+
+      # Sets the field value.
+      #
+      # Override this to set the value.
+      def set(value)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/capybara/ui/widgets/field_group.rb

@@ -0,0 +1,331 @@
+module Capybara
+  module UI
+    # A group of form fields.
+    #
+    # @todo Explain how to use locators when defining fields, including what
+    #   happens when locators are omitted.
+    class FieldGroup < Widget
+      root 'fieldset'
+
+      def self.default_locator(type = nil, &block)
+        alias_method :name_to_locator, type if type
+
+        define_method :name_to_locator, &block if block
+      end
+
+      # 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.
+      #
+      # @return [Set] the field names.
+      #
+      # @see field
+      def self.field_names
+        @field_names ||= Set.new
+      end
+
+      # @!group Field definition macros
+
+      # 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.
+      #
+      # @example
+      #   # 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
+      #
+      # @param name the name of the checkbox accessor.
+      # @param locator the locator for the checkbox. If +nil+ the locator will
+      #   be derived from +name+.
+      #
+      # @todo Handle checkbox access when the field is disabled (raise an
+      #   exception?)
+      def self.check_box(name, locator = nil)
+        field name, locator, CheckBox
+      end
+
+      # Defines a new field.
+      #
+      # @param name the name of the field accessor.
+      # @param locator the field locator.
+      # @param type the field class name.
+      #
+      # @api private
+      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
+
+      # 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.
+      #
+      # @example
+      #   # 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"
+      #
+      # @param name the name of the select accessor.
+      # @param locator the locator for the select. If +nil+ the locator will
+      #   be derived from +name+.
+      #
+      # @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?
+      def self.select(name, locator = nil)
+        field name, locator, Select
+
+        define_method "#{name}_value" do
+          widget(name).value
+        end
+      end
+
+      # 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.
+      #
+      # @example
+      #   # 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"
+      #
+      # @param name the name of the radio_button group accessor.
+      # @param locator the locator for the radio_button group.
+      #
+      def self.radio_button(name, locator = nil)
+        field name, locator, RadioButton
+
+        define_method "#{name}_value" do
+          widget(name).value
+        end
+      end
+
+      # 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
+      #
+      # @example
+      #   # 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"
+      #
+      # @param name the name of the text field accessor.
+      # @param locator the locator for the text field. If +nil+ the locator
+      #   will be derived from +name+.
+      #
+      # @todo Handle text field access when the field is disabled (raise an
+      #   exception?)
+      def self.text_field(name, locator = nil)
+        define_method "#{name}?" do
+          widget(name).content?
+        end
+
+        field name, locator, TextField
+      end
+
+      # @!endgroup
+
+      # @return This field group's field widgets.
+      def fields
+        self.class.field_names.map { |name| widget(name) }
+      end
+
+      # Sets the given form attributes.
+      #
+      # @param attributes [Hash] the attributes and values we want to set.
+      #
+      # @return the current widget.
+      def set(attributes)
+        attributes.each do |k, v|
+          send "#{k}=", v
+        end
+
+        self
+      end
+
+      # Converts the current field group into a table suitable for diff'ing
+      # with Cucumber::Ast::Table.
+      #
+      # Field labels are determined by the widget name.
+      #
+      # Field values correspond to the return value of each field's +to_s+.
+      #
+      # @return [Array<Array>] the table.
+      def to_table
+        headers = fields.map { |field| field.label.downcase }
+        body    = fields.map { |field| field.to_s.downcase }
+
+        [headers, body]
+      end
+    end
+  end
+end