capybara-ui 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 23fc0acf5fe588ee3f45849a2874646086bd6ee5
+  data.tar.gz: cc92aa9e22aa4c98962fe0f69cf932064199eb44
+SHA512:
+  metadata.gz: c7e1e9fe1f240f81740fd5069ed9a28fdadb8c0243cc46c614a6172cb6e88ed0e8e08ab58611093780b66eeea5356d5d6a5b8c7e1016ac897c77f49d078e24d5
+  data.tar.gz: a7cb453961ba99e4ef31daf00e0016fc8c9b802a018efdf030191b99cfe13878d65651514d35e43e89bb504f04ddc45845a66612a0361a70b210a009807172e8

data/lib/capybara-ui.rb

@@ -0,0 +1,31 @@
+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 CapybaraUI
+  # 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

data/lib/capybara-ui/assertions.rb

@@ -0,0 +1,19 @@
+module CapybaraUI
+  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

data/lib/capybara-ui/capybara.rb

@@ -0,0 +1,7 @@
+Capybara.configure do |config|
+  config.match = :one
+  config.exact = true
+  config.exact_options = true
+  config.ignore_hidden_elements = true
+  config.visible_text_only = true
+end

data/lib/capybara-ui/checkpoint.rb

@@ -0,0 +1,111 @@
+module CapybaraUI
+  # 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 CapybaraUI::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

data/lib/capybara-ui/conversions.rb

@@ -0,0 +1,31 @@
+module CapybaraUI
+  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

data/lib/capybara-ui/cucumber.rb

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

data/lib/capybara-ui/dsl.rb

@@ -0,0 +1,107 @@
+module CapybaraUI
+  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 < CapybaraUI::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 CapybaraUI 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

data/lib/capybara-ui/instance_conversions.rb

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

data/lib/capybara-ui/matchers.rb

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

data/lib/capybara-ui/optional_dependencies.rb

@@ -0,0 +1,5 @@
+module CapybaraUI
+  module OptionalDependencies
+    RSPEC_VERSION = '3.0'
+  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,9 @@
+module CapybaraUI
+  module Rails
+    class Role < ActionDispatch::IntegrationTest
+      def initialize
+        super self.class.name
+      end
+    end
+  end
+end

data/lib/capybara-ui/role.rb

@@ -0,0 +1,19 @@
+module CapybaraUI
+  class Role < CapybaraUI::Rails::Role
+    extend Widgets::DSL
+
+    include CapybaraUI::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

data/lib/capybara-ui/text_table.rb

@@ -0,0 +1,107 @@
+module CapybaraUI
+  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