capybara-ui 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23fc0acf5fe588ee3f45849a2874646086bd6ee5
-  data.tar.gz: cc92aa9e22aa4c98962fe0f69cf932064199eb44
+  metadata.gz: 8569e04fe7e820a732b875283667700db0021f11
+  data.tar.gz: eab7f283b1ac93ceb0a1ff5db4d4319bf4f8b687
 SHA512:
-  metadata.gz: c7e1e9fe1f240f81740fd5069ed9a28fdadb8c0243cc46c614a6172cb6e88ed0e8e08ab58611093780b66eeea5356d5d6a5b8c7e1016ac897c77f49d078e24d5
-  data.tar.gz: a7cb453961ba99e4ef31daf00e0016fc8c9b802a018efdf030191b99cfe13878d65651514d35e43e89bb504f04ddc45845a66612a0361a70b210a009807172e8
+  metadata.gz: 703a2e188f63c0e896b1a9df815dad5df846bcb30882d6618168b207b2f19a6736f84ddfe3c2751ed2cd92f536355c0320e0ea53de0964c562aa0704ac9db33d
+  data.tar.gz: cd41f9dd5368aba4585a365c321b399aa3c55c329990f68f66b4ebbd1181de4f98dc429c9d85f959176b559035db89e6003d8945ea4cfd0feeb8196d5d18a3cb

data/lib/capybara/ui.rb

@@ -0,0 +1,33 @@
+require 'chronic'
+require 'nokogiri'
+require 'capybara'
+
+require 'capybara/ui/optional_dependencies'
+require 'capybara/ui/conversions'
+require 'capybara/ui/instance_conversions'
+require 'capybara/ui/checkpoint'
+require 'capybara/ui/widgets'
+require 'capybara/ui/text_table'
+require 'capybara/ui/text_table/mapping'
+require 'capybara/ui/text_table/void_mapping'
+require 'capybara/ui/text_table/transformations'
+require 'capybara/ui/text_table/cell_text'
+require 'capybara/ui/capybara'
+require 'capybara/ui/dsl'
+
+module Capybara
+  module UI
+    # An exception that signals that something is missing.
+    class Missing < StandardError; end
+    class MissingWidget < StandardError; end
+    class AmbiguousWidget < StandardError; end
+    class InvalidOption < StandardError; end
+    class InvalidRadioButton < StandardError; end
+
+    def deprecate(method, alternate_method, once=false)
+      @deprecation_notified ||= {}
+      warn "DEPRECATED: ##{method} is deprecated, please use ##{alternate_method} instead" unless once and @deprecation_notified[method]
+      @deprecation_notified[method] = true
+    end
+  end
+end

data/lib/capybara/ui/assertions.rb

@@ -0,0 +1,21 @@
+module Capybara
+  module UI
+    module Assertions
+      def assert_visible(role, widget_name, *args)
+        eventually do
+          assert role.see?(widget_name, *args)
+
+          true
+        end
+      end
+
+      def assert_not_visible(role, widget_name, *args)
+        eventually do
+          refute role.see?(widget_name, *args)
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/checkpoint.rb

@@ -0,0 +1,113 @@
+module Capybara
+  module UI
+    # A point in time where some condition, or some set of conditions, should be
+    # verified.
+    #
+    # @see http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Base#synchronize-instance_method,
+    #   which inspired this class.
+    class Checkpoint
+      class ConditionNotMet < StandardError; end
+
+      class << self
+        attr_accessor :rescuable_errors
+      end
+
+      self.rescuable_errors = [StandardError]
+
+      if defined?(RSpec)
+        require 'rspec/expectations'
+        self.rescuable_errors << RSpec::Expectations::ExpectationNotMetError
+      end
+
+      class Timer
+        class Frozen < StandardError; end
+
+        def initialize(duration)
+          @duration = duration
+        end
+
+        attr_reader :duration
+
+        def expired?
+          duration < elapsed
+        end
+
+        def elapsed
+          now - start_time
+        end
+
+        def start
+          @start_time = now
+        end
+
+        def tick
+          sleep tick_duration
+
+          raise Frozen, 'time appears to be frozen' if frozen?
+        end
+
+        protected
+
+        def now
+          Time.now
+        end
+
+        attr_reader :start_time
+
+        def frozen?
+          now == start_time
+        end
+
+        def tick_duration
+          0.05
+        end
+      end
+
+      # Shortcut for instance level wait_for.
+      def self.wait_for(wait_time = Capybara.default_max_wait_time, &block)
+        new(wait_time).call(&block)
+      end
+
+      # Initializes a new Checkpoint.
+      #
+      # @param wait_time how long this checkpoint will wait for its conditions to
+      #   be met, in seconds.
+      def initialize(wait_time = Capybara.default_max_wait_time)
+        @timer = Timer.new(wait_time)
+      end
+
+      # Executes +block+ repeatedly until it returns a "truthy" value or
+      # +wait_time+ expires.
+      #
+      # Swallows any StandardError or StandardError descendent until +wait_time+
+      # expires. If an exception is raised and the time has expired, that
+      # exception will be raised again.
+      #
+      # If the block does not return a "truthy" value until +wait_time+ expires,
+      # raises a Capybara::UI::Checkpoint::ConditionNotMet error.
+      #
+      # Returns whatever value is returned by the block.
+      def call(&condition)
+        timer.start
+
+        begin
+          yield or raise ConditionNotMet
+        rescue *rescuable_errors
+          raise if timer.expired?
+
+          timer.tick
+
+          retry
+        end
+      end
+
+      protected
+
+      def rescuable_errors
+        self.class.rescuable_errors
+      end
+
+      attr_reader :timer
+    end
+  end
+end

data/lib/capybara/ui/conversions.rb

@@ -0,0 +1,33 @@
+module Capybara
+  module UI
+    module Conversions
+      extend self
+
+      def Boolean(val)
+        case val
+        when 'yes', 'true', true
+          true
+        when 'no', 'false', false, nil, ''
+          false
+        else
+          raise ArgumentError, "can't convert #{val.inspect} to boolean"
+        end
+      end
+
+      def List(valstr, &block)
+        vs = valstr.strip.split(/\s*,\s*/)
+
+        block ? vs.map(&block) : vs
+      end
+
+      def Timeish(val)
+        raise ArgumentError, "can't convert nil to Timeish" if val.nil?
+
+        return val if Date === val || Time === val || DateTime === val
+
+        Chronic.parse(val) or
+          raise ArgumentError, "can't parse #{val.inspect} to Timeish"
+      end
+    end
+  end
+end

data/lib/capybara/ui/cucumber.rb

@@ -0,0 +1,5 @@
+require 'capybara/cucumber'
+require 'capybara/ui/rails'
+require 'capybara/ui/matchers'
+
+World(Capybara::UI::DSL)

data/lib/capybara/ui/dsl.rb

@@ -0,0 +1,109 @@
+module Capybara
+  module UI
+    module DSL
+      attr_writer :widget_lookup_scope
+
+      # Clicks the widget defined by +name+ and optional +args+.
+      #
+      # Makes no distinction between links or buttons.
+      #
+      #   class MyWidget < Capybara::UI::Widget
+      #     root { |text| ['.my-widget', text: text] }
+      #   end
+      #
+      #   #  <a href="#one" class="my-widget">One</li>
+      #   #  <a href="#two" class="my-widget">Two</li> <!-- clicks this node -->
+      #   click :my_widget, 'Two'
+      def click(name, *args)
+        widget(name, *args).click
+      end
+
+      # Hovers the widget defined by +name+ and optional +args+.
+      def hover(name, *args)
+        widget(name, *args).hover
+      end
+
+      # Double clicks the widget defined by +name+ and optional +args+.
+      def double_click(name, *args)
+        widget(name, *args).double_click
+      end
+
+      # Right clicks the widget defined by +name+ and optional +args+.
+      def right_click(name, *args)
+        widget(name, *args).right_click
+      end
+
+      # @return [Document] the current document with the class of the
+      #   current object set as the widget lookup scope.
+      def document
+        Document.new(widget_lookup_scope)
+      end
+
+      # @return [Boolean] Whether one or more widgets exist in the current
+      #   document.
+      def has_widget?(name, *args)
+        document.has_widget?(name, *args)
+      end
+
+      alias_method :widget?, :has_widget?
+
+      def visible?(name, *args)
+        document.visible?(name, *args)
+      end
+
+      def not_visible?(name, *args)
+        document.not_visible?(name, *args)
+      end
+
+      def set(name, fields)
+        widget(name).set fields
+      end
+
+      def submit(name, fields = {})
+        widget(name).submit_with fields
+      end
+
+      def value(name, *args)
+        widget(name, *args).value
+      end
+
+      def values(name, *args)
+        widgets(name, *args).map(&:value)
+      end
+
+      def visit(path)
+        Capybara.current_session.visit path
+      end
+
+      # Returns a widget instance for the given name.
+      #
+      # @param name [String, Symbol]
+      def widget(name, *args)
+        eventually { document.widget(name, *args) }
+      end
+
+      # Returns a list of widget instances for the given name.
+      #
+      # @param name [String, Symbol]
+      def widgets(name, *args)
+        document.widgets(name, *args)
+      end
+
+      def widget_lookup_scope
+        @widget_lookup_scope ||= default_widget_lookup_scope
+      end
+
+      # re-run one or more assertions until either they all pass,
+      # or Capybara::UI times out, which will result in a test failure.
+      def eventually(wait_time = Capybara.default_max_wait_time, &block)
+        Checkpoint.wait_for wait_time, &block
+      end
+
+      private
+
+      def default_widget_lookup_scope
+        Module === self ? self : self.class
+      end
+    end
+  end
+end

data/lib/capybara/ui/instance_conversions.rb

@@ -0,0 +1,21 @@
+module Capybara
+  module UI
+    module InstanceConversions
+      def self.included(base)
+        base.send :include, Capybara::UI::Conversions
+      end
+
+      def to_boolean
+        Boolean(self)
+      end
+
+      def to_a
+        List(self)
+      end
+
+      def to_time
+        Timeish(self)
+      end
+    end
+  end
+end

data/lib/{capybara-ui → capybara/ui}/matchers.rb

@@ -2,9 +2,9 @@ begin
   require 'rspec/matchers'
   require 'rspec/version'
 
-  unless Gem::Version.new(RSpec::Version::STRING) >= Gem::Version.new(CapybaraUI::OptionalDependencies::RSPEC_VERSION)
+  unless Gem::Version.new(RSpec::Version::STRING) >= Gem::Version.new(Capybara::UI::OptionalDependencies::RSPEC_VERSION)
     raise LoadError,
-      "requires RSpec version #{CapybaraUI::OptionalDependencies::RSPEC_VERSION} or later. " \
+      "requires RSpec version #{Capybara::UI::OptionalDependencies::RSPEC_VERSION} or later. " \
       "You have #{RSpec::Version::STRING}."
   end
 
@@ -12,7 +12,7 @@ begin
     match do |role|
       begin
         eventually { role.see?(widget_name, *args) }
-      rescue CapybaraUI::Checkpoint::ConditionNotMet
+      rescue Capybara::UI::Checkpoint::ConditionNotMet
         false
       end
     end
@@ -20,7 +20,7 @@ begin
     match_when_negated do |role|
       begin
         eventually { !role.see?(widget_name, *args) }
-      rescue CapybaraUI::Checkpoint::ConditionNotMet
+      rescue Capybara::UI::Checkpoint::ConditionNotMet
         false
       end
     end

data/lib/capybara/ui/optional_dependencies.rb

@@ -0,0 +1,7 @@
+module Capybara
+  module UI
+    module OptionalDependencies
+      RSPEC_VERSION = '3.0'
+    end
+  end
+end

data/lib/capybara/ui/rails.rb

@@ -0,0 +1,5 @@
+require 'action_dispatch/testing/integration'
+
+require 'capybara/ui/rails/role'
+require 'capybara/ui'
+require 'capybara/ui/role'

data/lib/capybara/ui/rails/role.rb

@@ -0,0 +1,11 @@
+module Capybara
+  module UI
+    module Rails
+      class Role < ActionDispatch::IntegrationTest
+        def initialize
+          super self.class.name
+        end
+      end
+    end
+  end
+end

data/lib/capybara/ui/role.rb

@@ -0,0 +1,21 @@
+module Capybara
+  module UI
+    class Role < Capybara::UI::Rails::Role
+      extend Widgets::DSL
+
+      include Capybara::UI::DSL
+
+      def see?(name, *args)
+        if respond_to?("see_#{name}?")
+          send("see_#{name}?", *args)
+        else
+          visible?(name, *args)
+        end
+      end
+
+      def inspect
+        self.class.name
+      end
+    end
+  end
+end

data/lib/capybara/ui/text_table.rb

@@ -0,0 +1,109 @@
+module Capybara
+  module UI
+    class TextTable
+      extend Forwardable
+
+      include Enumerable
+      include Conversions
+
+      class << self
+        def Array(table)
+          new(table).to_a
+        end
+
+        def Hash(table)
+          new(table).to_h
+        end
+
+        def map(name, options = {}, &block)
+          case name
+          when :*
+            set_default_mapping options, &block
+          else
+            set_mapping name, options, &block
+          end
+        end
+
+        def mappings
+          @mappings ||= Hash.
+           new { |h, k| h[k] = Mapping.new }.
+           merge(with_parent_mappings)
+        end
+
+        def skip(name)
+          case name
+          when :*
+            set_default_mapping VoidMapping
+          else
+            raise ArgumentError, "can't convert #{name.inspect} to name"
+          end
+        end
+
+        private
+
+        def set_default_mapping(options, &block)
+          case options
+          when Hash
+            @mappings = Hash.
+             new { |h, k|
+              h[k] = Mapping.new(key_transformer:   options[:to],
+                                 value_transformer: block) }.
+             merge(mappings)
+          when Class
+            @mappings = Hash.new { |h, k| h[k] = options.new }.merge(mappings)
+          else
+            raise ArgumentError, "can't convert #{options.inspect} to mapping"
+          end
+        end
+
+        def set_mapping(name, options, &block)
+          mappings[name] = Mapping.
+           new(key: options[:to], value_transformer: block)
+        end
+
+        def with_parent_mappings
+          if superclass.respond_to?(:mappings)
+            superclass.send(:mappings).dup
+          else
+            {}
+          end
+        end
+      end
+
+      def_delegators 'self.class', :mappings
+
+      def initialize(table)
+        self.table = table
+      end
+
+      def each(&block)
+        rows.each(&block)
+      end
+
+      def rows
+        @rows ||= table.hashes.map { |h| new_row(h) }
+      end
+
+      def single_row
+        @single_row ||= new_row(table.rows_hash)
+      end
+
+      alias_method :to_a, :rows
+      alias_method :to_h, :single_row
+
+      private
+
+      attr_accessor :table
+
+      def new_row(hash)
+        hash.each_with_object({}) { |(k, v), h|
+          mapping_for(k).set(self, h, k, CellText.new(v))
+        }
+      end
+
+      def mapping_for(header)
+        mappings[header]
+      end
+    end
+  end
+end