capybara-ui 0.10.0 → 1.0.0

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

@@ -0,0 +1,59 @@
+module Capybara
+  module UI
+    # A select.
+    class Select < Field
+      def selected
+        root.all(:xpath, ".//option", visible: true).select(&:selected?).first
+      end
+
+      module Selectable
+        def select
+          root.select_option
+        end
+      end
+
+      widget :option, -> (opt) {
+        opt.is_a?(Regexp) ? ["option", text: opt] : [:option, opt]
+      } do
+        include Selectable
+      end
+
+      widget :option_by_value, -> (opt) { "option[value = #{opt.inspect}]" } do
+        include Selectable
+      end
+
+      # @return [String] The text of the selected option.
+      def get
+        selected.text unless selected.nil?
+      end
+
+      # @return [String] The value of the selected option.
+      def value
+        selected.value unless selected.nil?
+      end
+
+      # Selects the given +option+.
+      #
+      # You may pass in the option text or value.
+      def set(option)
+        widget(:option, option).select
+      rescue
+        begin
+          widget(:option_by_value, option).select
+        rescue Capybara::UI::MissingWidget => e
+          raise InvalidOption.new(e.message).
+            tap { |x| x.set_backtrace e.backtrace }
+        end
+      end
+
+      # @!method to_s
+      #   @return the text of the selected option, or the empty string if
+      #     no option is selected.
+      def_delegator :get, :to_s
+
+      def to_cell
+        get
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+module Capybara
+  module UI
+    class StringValue < String
+      def to_date(format = nil)
+        format ? Date.strptime(self, format) : super()
+      end
+
+      def to_key
+        fst, rest = first, self[1..-1]
+        decamelized = fst + rest.gsub(/([A-Z])/, '_\1')
+        underscored = decamelized.gsub(/[\W_]+/, '_')
+        stripped = underscored.gsub(/^_|_$/, '')
+        downcased = stripped.downcase
+        key = downcased.to_sym
+
+        key
+      end
+
+      class Money
+        extend Forwardable
+
+        delegate %w(to_i to_f) => :str
+
+        def initialize(str)
+          fail ArgumentError, "can't convert `#{str}` to money" \
+            unless str =~ /^-?\$\d+(?:,\d{3})*(?:\.\d+)?/
+
+          @str = (str =~ /^-/ ? '-' : '') + str.gsub(/^-?\$|,/, '')
+        end
+
+        private
+
+        attr_reader :str
+      end
+
+      def to_usd
+        Money.new(self)
+      end
+
+      def to_split
+        split(',').map(&:strip).map { |e| self.class.new(e) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+module Capybara
+  module UI
+    class Table < Capybara::UI::Widget
+      root 'table'
+
+      class Row < Capybara::UI::List
+        def self.column(*args, &block)
+          item(*args, &block)
+        end
+      end
+
+      def self.header_row(selector, &block)
+        widget :header_row, selector, Row, &block
+      end
+
+      header_row 'thead tr' do
+        column 'th'
+      end
+
+      def self.data_row(selector, &block)
+        widget :data_row, selector, Row, &block
+      end
+
+      data_row 'tbody tr' do
+        column 'td'
+      end
+
+      class Columns
+        include Enumerable
+
+        def initialize(parent)
+          @parent = parent
+        end
+
+        def [](header_or_index)
+          case header_or_index
+          when Integer
+            values_by_index(header_or_index)
+          when String
+            values_by_header(header_or_index)
+          else
+            raise TypeError,
+                  "can't convert #{header_or_index.inspect} to Integer or String"
+          end
+        end
+
+        def each(&block)
+          parent.each(&block)
+        end
+
+        private
+
+        attr_reader :parent
+
+        def values_by_index(index)
+          parent.rows.transpose[index]
+        end
+
+        def values_by_header(header)
+          values_by_index(find_header_index(header))
+        end
+
+        def find_header_index(header)
+          parent.widget(:header_row).value.find_index(header) or
+            raise ArgumentError, "header not found: #{header.inspect}"
+        end
+      end
+
+      def columns
+        Columns.new(self)
+      end
+
+      def rows
+        widgets(:data_row).map(&:value)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Capybara
+  module UI
+    # A text field.
+    class TextField < Field
+      # @!method get
+      #   @return The text field value.
+      def_delegator :root, :value, :get
+
+      # @!method set(value)
+      #   Sets the text field value.
+      #
+      #   @param value [String] the value to set.
+      def_delegator :root, :set
+
+      # @!method to_s
+      #   @return the text field value, or the empty string if the field is
+      #     empty.
+      def_delegator :get, :to_s
+
+      def to_cell
+        get
+      end
+
+      def content?
+        get.respond_to?(:empty?) ? ! get.empty? : !! get
+      end
+    end
+  end
+end

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

@@ -0,0 +1,394 @@
+module Capybara
+  module UI
+    class Widget
+      extend Forwardable
+      extend Widgets::DSL
+
+      include WidgetParts::Struct
+      include WidgetParts::Container
+      include CucumberMethods
+
+      class Removed < StandardError; end
+
+      attr_reader :root
+
+      # @!group Widget macros
+
+      # Defines a new action.
+      #
+      # This is a shortcut to help defining a widget and a method that clicks
+      # on that widget. You can then send a widget instance the message given
+      # by +name+.
+      #
+      # You can access the underlying widget by appending "_widget" to the
+      # action name.
+      #
+      # @example
+      #   # Consider the widget will encapsulate the following HTML
+      #   #
+      #   # <div id="profile">
+      #   #  <a href="/profiles/1/edit" rel="edit">Edit</a>
+      #   # </div>
+      #   class PirateProfile < Capybara::UI::Widget
+      #     root "#profile"
+      #
+      #     # Declare the action
+      #     action :edit, '[rel = edit]'
+      #   end
+      #
+      #   pirate_profile = widget(:pirate_profile)
+      #
+      #   # Access the action widget
+      #   action_widget = pirate_profile.widget(:edit_widget)
+      #   action_widget = pirate_profile.edit_widget
+      #
+      #   # Click the link
+      #   pirate_profile.edit
+      #
+      # @param name the name of the action
+      # @param selector the selector for the widget that will be clicked
+      def self.action(name, selector = nil)
+        block = if selector
+                  wname = :"#{name}_widget"
+
+                  widget wname, selector
+
+                  -> { widget(wname).click; self }
+                else
+                  -> { click; self }
+                end
+
+        define_method name, &block
+      end
+
+      # Creates a delegator for one child widget message.
+      #
+      # Since widgets are accessed through {WidgetParts::Container#widget}, we
+      # can't use {Forwardable} to delegate messages to widgets.
+      #
+      # @param name the name of the receiver child widget
+      # @param widget_message the name of the message to be sent to the child widget
+      # @param method_name the name of the delegator. If +nil+ the method will
+      #   have the same name as the message it will send.
+      def self.widget_delegator(name, widget_message, method_name = nil)
+        method_name = method_name || widget_message
+
+        class_eval <<-RUBY
+          def #{method_name}(*args)
+            if args.size == 1
+              widget(:#{name}).#{widget_message} args.first
+            else
+              widget(:#{name}).#{widget_message} *args
+            end
+          end
+        RUBY
+      end
+
+      # @!endgroup
+
+      # Finds a single instance of the current widget in +node+.
+      #
+      # @param node the node we want to search in
+      #
+      # @return a new instance of the current widget class.
+      #
+      # @raise [Capybara::ElementNotFoundError] if the widget can't be found
+      def self.find_in(parent, *args)
+        new(filter.node(parent, *args))
+      rescue Capybara::Ambiguous => e
+        raise AmbiguousWidget.new(e.message).
+          tap { |x| x.set_backtrace e.backtrace }
+      rescue Capybara::ElementNotFound => e
+        raise MissingWidget.new(e.message).
+          tap { |x| x.set_backtrace e.backtrace }
+      end
+
+      def self.find_all_in(parent, *args)
+        filter.nodes(parent, *args).map { |e| new(e) }
+      end
+
+      # Determines if an instance of this widget class exists in
+      # +parent_node+.
+      #
+      # @param parent_node [Capybara::Node] the node we want to search in
+      #
+      # @return +true+ if a widget instance is found, +false+ otherwise.
+      def self.present_in?(parent, *args)
+        filter.node?(parent, *args)
+      end
+
+      def self.not_present_in?(parent, *args)
+        filter.nodeless?(parent, *args)
+      end
+
+      # Sets this widget's default selector.
+      #
+      # You can pass more than one argument to it, or a single Array. Any valid
+      # Capybara selector accepted by Capybara::Node::Finders#find will work.
+      #
+      # === Examples
+      #
+      # Most of the time, your selectors will be Strings:
+      #
+      #   class MyWidget < Capybara::UI::Widget
+      #     root '.selector'
+      #   end
+      #
+      # This will match any element with a class of "selector". For example:
+      #
+      #   <span class="selector">Pick me!</span>
+      #
+      # ==== Composite selectors
+      #
+      # If you're using CSS as the query language, it's useful to be able to use
+      # +text: 'Some text'+ to zero in on a specific node:
+      #
+      #   class MySpecificWidget < Capybara::UI::Widget
+      #     root '.selector', text: 'Pick me!'
+      #   end
+      #
+      # This is especially useful, e.g., when you want to create a widget
+      # to match a specific error or notification:
+      #
+      #   class NoFreeSpace < Capybara::UI::Widget
+      #     root '.error', text: 'No free space left!'
+      #   end
+      #
+      # So, given the following HTML:
+      #
+      #   <body>
+      #     <div class="error">No free space left!</div>
+      #
+      #     <!-- ... -->
+      #   </body>
+      #
+      # You can test for the error's present using the following code:
+      #
+      #   document.visible?(:no_free_space) #=> true
+      #
+      # Note: When you want to match text, consider using +I18n.t+ instead of
+      # hard-coding the text, so that your tests don't break when the text changes.
+      #
+      # Finally, you may want to override the query language:
+      #
+      #   class MyWidgetUsesXPath < Capybara::UI::Widget
+      #     root :xpath, '//some/node'
+      #   end
+      def self.root(*selector, &block)
+        @filter = NodeFilter.new(block || selector)
+      end
+
+      class MissingSelector < StandardError
+      end
+
+      def self.filter
+        @filter || superclass.filter
+      rescue NoMethodError
+        raise MissingSelector, 'no selector defined'
+      end
+
+      def self.filter?
+        filter rescue false
+      end
+
+      def self.selector
+        filter.selector
+      end
+
+      def initialize(root)
+        @root = root
+      end
+
+      # Clicks the current widget, or the child widget given by +name+.
+      #
+      # === Usage
+      #
+      # Given the following widget definition:
+      #
+      #   class Container < Capybara::UI::Widget
+      #     root '#container'
+      #
+      #     widget :link, 'a'
+      #   end
+      #
+      # Send +click+ with no arguments to trigger a +click+ event on +#container+.
+      #
+      #   widget(:container).click
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container').click
+      #
+      # Send +click :link+ to trigger a +click+ event on +a+:
+      #
+      #   widget(:container).click :link
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container a').click
+      def click(*args)
+        if args.empty?
+          root.click
+        else
+          widget(*args).click
+        end
+      end
+
+      # Hovers over the current widget, or the child widget given by +name+.
+      #
+      # === Usage
+      #
+      # Given the following widget definition:
+      #
+      #   class Container < Capybara::UI::Widget
+      #     root '#container'
+      #
+      #     widget :link, 'a'
+      #   end
+      #
+      # Send +hover+ with no arguments to trigger a +hover+ event on +#container+.
+      #
+      #   widget(:container).hover
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container').hover
+      #
+      # Send +hover :link+ to trigger a +hover+ event on +a+:
+      #
+      #   widget(:container).hover :link
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container a').hover
+      def hover(*args)
+        if args.empty?
+          root.hover
+        else
+          widget(*args).hover
+        end
+      end
+
+      # Double clicks the current widget, or the child widget given by +name+.
+      #
+      # === Usage
+      #
+      # Given the following widget definition:
+      #
+      #   class Container < Capybara::UI::Widget
+      #     root '#container'
+      #
+      #     widget :link, 'a'
+      #   end
+      #
+      # Send +double_click+ with no arguments to trigger an +ondblclick+ event on +#container+.
+      #
+      #   widget(:container).double_click
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container').double_click
+      def double_click(*args)
+        if args.empty?
+          root.double_click
+        else
+          widget(*args).double_click
+        end
+      end
+
+      # Right clicks the current widget, or the child widget given by +name+.
+      #
+      # === Usage
+      #
+      # Given the following widget definition:
+      #
+      #   class Container < Capybara::UI::Widget
+      #     root '#container'
+      #
+      #     widget :link, 'a'
+      #   end
+      #
+      # Send +right_click+ with no arguments to trigger an +oncontextmenu+ event on +#container+.
+      #
+      #   widget(:container).right_click
+      #
+      # This is the equivalent of doing the following using Capybara:
+      #
+      #   find('#container').right_click
+      def right_click(*args)
+        if args.empty?
+          root.right_click
+        else
+          widget(*args).right_click
+        end
+      end
+
+      # Determines if the widget underlying an action exists.
+      #
+      # @param name the name of the action
+      #
+      # @raise Missing if an action with +name+ can't be found.
+      #
+      # @return [Boolean] +true+ if the action widget is found, +false+
+      #   otherwise.
+      def has_action?(name)
+        raise Missing, "couldn't find `#{name}' action" unless respond_to?(name)
+
+        visible?(:"#{name}_widget")
+      end
+
+      def id
+        root['id']
+      end
+
+      def classes
+        root['class'].split
+      end
+
+      # Determines if the widget has a specific class
+      #
+      # @param name the name of the class
+      #
+      # @return [Boolean] +true+ if the class is found, +false+ otherwise
+      def class?(name)
+        classes.include?(name)
+      end
+
+      def html
+        xml = Nokogiri::HTML(page.body).at(root.path).to_xml
+
+        Nokogiri::XML(xml, &:noblanks).to_xhtml.gsub("\n", "")
+      end
+
+      def text
+        StringValue.new(root.text.strip)
+      end
+
+      # Converts this widget into a string representation suitable to be displayed
+      # in a Cucumber table cell. By default calls #text.
+      #
+      # This method will be called by methods that build tables or rows (usually
+      # #to_table or #to_row) so, in general, you won't call it directly, but feel
+      # free to override it when needed.
+      #
+      # Returns a String.
+      def to_cell
+        text
+      end
+
+      def to_s
+        text
+      end
+
+      def value
+        text
+      end
+
+      private
+
+      def page
+        Capybara.current_session
+      end
+    end
+  end
+end