testable 0.3.0 → 0.8.0

data/lib/testable/capybara/page.rb

@@ -0,0 +1,29 @@
+require "capybara"
+require "testable/capybara/node"
+
+module Testable
+  class Page < Node
+    # The `Page` class wraps an HTML page with an application-specific API.
+    # This can be extended to define an API for manipulating the pages of
+    # the web application.
+    attr_reader :path
+
+    def self.visit
+      new.visit
+    end
+
+    def initialize(node: Capybara.current_session, path: nil)
+      @node = node
+      @path = path
+    end
+
+    def visit
+      @node.visit(path)
+      self
+    end
+
+    def current?
+      @node.current_path == path
+    end
+  end
+end

data/lib/testable/context.rb

@@ -0,0 +1,73 @@
+module Testable
+  module Context
+    # Creates a definition context for actions and establishes the context
+    # for execution. Given an interface definition for a page like this:
+    #
+    #    class TestPage
+    #      include Testable
+    #
+    #      url_is "http://localhost:9292"
+    #    end
+    #
+    # You can do the following:
+    #
+    #    on_visit(TestPage)
+    def on_visit(definition, &block)
+      create_active(definition)
+      @context.visit
+      verify_page(@context)
+      call_block(&block)
+    end
+
+    # Creates a definition context for actions. If an existing context
+    # exists, that context will be re-used. You can use this simply to keep
+    # the context for a script clear. For example, say you have the following
+    # interface definitions for pages:
+    #
+    #    class Home
+    #      include Testable
+    #      url_is "http://localhost:9292"
+    #    end
+    #
+    #    class Navigation
+    #      include Testable
+    #    end
+    #
+    # You could then do this:
+    #
+    #    on_visit(Home)
+    #    on(Navigation)
+    #
+    # The Home definition needs the url_is attribute in order for the on_view
+    # factory to work. But Navigation does not because the `on` method is not
+    # attempting to visit, simply to reference.
+    def on(definition, &block)
+      create_active(definition)
+      call_block(&block)
+    end
+
+    private
+
+    # This method is used to provide a means for checking if a page has been
+    # navigated to correctly as part of a context. This is useful because
+    # the context signature should remain highly readable, and checks for
+    # whether a given page has been reached would make the context definition
+    # look sloppy.
+    def verify_page(context)
+      return unless defined?(context.url_match_attribute)
+      return if context.url_match_attribute.nil?
+      return if context.has_correct_url?
+
+      raise Testable::Errors::PageURLFromFactoryNotVerified
+    end
+
+    def create_active(definition)
+      @context = definition.new unless @context.is_a?(definition)
+    end
+
+    def call_block(&block)
+      yield @context if block
+      @context
+    end
+  end
+end

data/lib/testable/deprecator.rb

@@ -0,0 +1,40 @@
+module Testable
+  class Deprecator
+    class << self
+      def deprecate(current, upcoming = nil, known_version = nil)
+        if upcoming
+          warn(
+            "#{current} is being deprecated and should no longer be used. \
+            Use #{upcoming} instead."
+          )
+        else
+          warn("#{current} is being deprecated and should no longer be used.")
+        end
+
+        warn(
+          "#{current} will be removed in Testable #{known_version}."
+        ) if known_version
+      end
+
+      def soft_deprecate(current, reason, known_version, upcoming = nil)
+        debug("The #{current} method is changing and is now configurable.")
+        debug("REASON: #{reason}.")
+        debug(
+          "Moving forwards into Testable #{known_version}, \
+          the default behavior will change."
+        )
+        debug("It is advised that you change to using #{upcoming}") if upcoming
+      end
+
+      private
+
+      def warn(message)
+        Testable.logger.warn(message)
+      end
+
+      def debug(message)
+        Testable.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/testable/element.rb

@@ -1,14 +1,9 @@
 require "watir"
-require "testable/situation"
 
 module Testable
-  include Situation
-
   module_function
 
-  def elements
-    @elements = Watir::Container.instance_methods unless @elements
-  end
+  NATIVE_QUALIFIERS = %i[visible].freeze
 
   def elements?
     @elements
@@ -18,38 +13,174 @@ module Testable
     @elements.include? method.to_sym
   end
 
-  module Element
-    Testable.elements.each do |element|
-      # This is what allows Watir-based elements to be defined
-      # on an element definition.
-      define_method(element) do |*signature|
-        identifier, locator = parse_signature(signature)
-        define_element_accessor(identifier, locator, element)
+  def elements
+    @elements ||= Watir::Container.instance_methods unless @elements
+  end
+
+  module Pages
+    module Element
+      # This iterator goes through the Watir container methods and
+      # provides a method for each so that Watir-based element names
+      # cane be defined on an interface definition, as part of an
+      # element definition.
+      Testable.elements.each do |element|
+        define_method(element) do |*signature, &block|
+          identifier, signature = parse_signature(signature)
+          context = context_from_signature(signature, &block)
+          define_element_accessor(identifier, signature, element, &context)
+        end
       end
-    end
 
-    private
+      private
+
+      # A "signature" consists of a full element definition. For example:
+      #
+      #    text_field :username, id: 'username'
+      #
+      # The signature of this element definition is:
+      #
+      #    [:username, {:id=>"username"}]
+      #
+      # This is the identifier of the element (`username`) and the locator
+      # provided for it. This method separates out the identifier and the
+      # locator.
+      def parse_signature(signature)
+        [signature.shift, signature.shift]
+      end
 
-    def define_element_accessor(identifier, *locator, element)
-      # This is what allows each identifier to be a method.
-      define_method(identifier.to_s.to_sym) do |*values|
-        no_locator(self.class, identifier) if empty_locator(locator, values)
-        locator = values if locator[0].nil?
-        reference_element(element, locator)
+      # Returns the block or proc that serves as a context for an element
+      # definition. Consider the following element definitions:
+      #
+      #    ul   :facts, id: 'fact-list'
+      #    span :fact, -> { facts.span(class: 'site-item')}
+      #
+      # Here the second element definition provides a proc that contains a
+      # context for another element definition. That leads to the following
+      # construction being sent to the browser:
+      #
+      #    @browser.ul(id: 'fact-list').span(class: 'site-item')
+      def context_from_signature(*signature, &block)
+        if block_given?
+          block
+        else
+          context = signature.shift
+          context.is_a?(Proc) && signature.empty? ? context : nil
+        end
       end
-    end
 
-    def parse_signature(signature)
-      [signature.shift, signature.shift]
-    end
+      # This method provides the means to get the aspects of an accessor
+      # signature. The "aspects" refer to the locator information and any
+      # qualifier information that was provided along with the locator.
+      # This is important because the qualifier is not used to locate an
+      # element but rather to put conditions on how the state of the
+      # element is checked as it is being looked for.
+      #
+      # Note that "qualifiers" here refers to Watir boolean methods.
+      def accessor_aspects(element, *signature)
+        identifier = signature.shift
+        locator_args = {}
+        qualifier_args = {}
+        gather_aspects(identifier, element, locator_args, qualifier_args)
+        [locator_args, qualifier_args]
+      end
 
-    module Locator
-      private
+      # This method is used to separate the two aspects of an accessor --
+      # the locators and the qualifiers. Part of this process involves
+      # querying the Watir driver library to determine what qualifiers
+      # it handles natively. Consider the following:
+      #
+      #    select_list :accounts, id: 'accounts', selected: 'Select Option'
+      #
+      # Given that, this method will return with the following:
+      #
+      #    locator_args: {:id=>"accounts"}
+      #    qualifier_args: {:selected=>"Select Option"}
+      #
+      # Consider this:
+      #
+      #    p :login_form, id: 'open', index: 0, visible: true
+      #
+      # Given that, this method will return with the following:
+      #
+      #    locator_args: {:id=>"open", :index=>0, :visible=>true}
+      #    qualifier_args: {}
+      #
+      # Notice that the `visible` qualifier is part of the locator arguments
+      # as opposed to being a qualifier argument, like `selected` was in the
+      # previous example. This is because Watir 6.x handles the `visible`
+      # qualifier natively. "Handling natively" means that when a qualifier
+      # is part of the locator, Watir knows how to intrpret the qualifier
+      # as a condition on the element, not as a way to locate the element.
+      def gather_aspects(identifier, element, locator_args, qualifier_args)
+        identifier.each_with_index do |hashes, index|
+          next if hashes.nil? || hashes.is_a?(Proc)
+
+          hashes.each do |k, v|
+            methods = Watir.element_class_for(element).instance_methods
+            if methods.include?(:"#{k}?") && !NATIVE_QUALIFIERS.include?(k)
+              qualifier_args[k] = identifier[index][k]
+            else
+              locator_args[k] = v
+            end
+          end
+        end
+        [locator_args, qualifier_args]
+      end
 
-      def reference_element(element, locator)
-        @browser.__send__(element, *locator).to_subtype
-      rescue NoMethodError
-        @browser.__send__(element, *locator)
+      # Defines an accessor method for an element that allows the "friendly
+      # name" (identifier) of the element to be proxied to a Watir element
+      # object that corresponds to the element type. When this identifier
+      # is referenced, it generates an accessor method for that element
+      # in the browser. Consider this element definition defined on a class
+      # with an instance of `page`:
+      #
+      #    text_field :username, id: 'username'
+      #
+      # This allows:
+      #
+      #    page.username.set 'tester'
+      #
+      # So any element identifier can be called as if it were a method on
+      # the interface (class) on which it is defined. Because the method
+      # is proxied to Watir, you can use the full Watir API by calling
+      # methods (like `set`, `click`, etc) on the element identifier.
+      #
+      # It is also possible to have an element definition like this:
+      #
+      #    text_field :password
+      #
+      # This would allow access like this:
+      #
+      #    page.username(id: 'username').set 'tester'
+      #
+      # This approach would lead to the *values variable having an array
+      # like this: [{:id => 'username'}].
+      #
+      # A third approach would be to utilize one element definition within
+      # the context of another. Consider the following element definitions:
+      #
+      #    article :practice, id: 'practice'
+      #
+      #    a :page_link do |text|
+      #      practice.a(text: text)
+      #    end
+      #
+      # This would allow access like this:
+      #
+      #    page.page_link('Drag and Drop').click
+      #
+      # This approach would lead to the *values variable having an array
+      # like this: ["Drag and Drop"].
+      def define_element_accessor(identifier, *signature, element, &block)
+        locators, qualifiers = accessor_aspects(element, signature)
+        define_method(identifier.to_s) do |*values|
+          if block_given?
+            instance_exec(*values, &block)
+          else
+            locators = values[0] if locators.empty?
+            access_element(element, locators, qualifiers)
+          end
+        end
       end
     end
   end

data/lib/testable/errors.rb

@@ -4,8 +4,12 @@ module Testable
     NoUrlMatchForDefinition = Class.new(StandardError)
     NoUrlMatchPossible = Class.new(StandardError)
     NoTitleForDefinition = Class.new(StandardError)
-    NoLocatorForDefinition = Class.new(StandardError)
     PageNotValidatedError = Class.new(StandardError)
-    NoBlockForWhenReady = Class.new(StandardError)
+
+    class PageURLFromFactoryNotVerified < StandardError
+      def message
+        "The page URL was not verified during a factory setup."
+      end
+    end
   end
 end

data/lib/testable/extensions/core_ruby.rb

@@ -0,0 +1,13 @@
+class String
+  # This is only required if using a version of Ruby before 2.4. A match?
+  # method for String was added in version 2.4.
+  def match?(string, pos = 0)
+    !!match(string, pos)
+  end unless //.respond_to?(:match?)
+end
+
+class FalseClass
+  def exists?
+    false
+  end
+end

data/lib/testable/extensions/data_setter.rb

@@ -0,0 +1,144 @@
+class Object
+  # This method is necessary to dynamically chain method calls. The reason
+  # this is necessary the data setter initially has no idea of the actual
+  # object it's going to be dealing with, particularly because part of its
+  # job is to find that object and map a data string to it. Not only this,
+  # but that element will have been called on a specific instance of a
+  # interface class. With the example provide in the comments below for the
+  # `using` method, the following would be the case:
+  #
+  # method_chain: warp_factor.set
+  # o (object):   <WarpTravel:0x007f8b23224218>
+  # m (method):   warp_factor
+  # data:         1
+  #
+  # Thus what you end up with is:
+  #
+  #    <WarpTravel:0x007f8b23224218>.warp_factor.set 1
+  def chain(method_chain, data = nil)
+    return self if method_chain.empty?
+
+    method_chain.split('.').inject(self) do |o, m|
+      if data.nil?
+        o.send(m.intern)
+      else
+        o.send(m.intern, data)
+      end
+    end
+  end
+end
+
+module Testable
+  module DataSetter
+    # The `using` method tells Testable to match up whatever data is passed
+    # in via the action with element definitions. If those elements are found,
+    # they will be populated with the specified data. Consider the following:
+    #
+    #    class WarpTravel
+    #      include Testable
+    #
+    #      text_field :warp_factor, id: 'warpInput'
+    #      text_field :velocity,    id: 'velocityInput'
+    #      text_field :distance,    id: 'distInput'
+    #    end
+    #
+    # Assuming an instance of this class called `page`, you could do the
+    # following:
+    #
+    #    page.using_data(warp_factor: 1, velocity: 1, distance: 4.3)
+    #
+    # This is based on conventions. The idea is that element definitions are
+    # written in the form of "snake case" -- meaning, underscores between
+    # each separate word. In the above example, "warp_factor: 1" would be
+    # matched to the `warp_factor` element and the value used for that
+    # element would be "1". The default operation for a text field is to
+    # enter the value in. It is also possible to use strings:
+    #
+    #    page.using_data("warp factor": 1, velocity: 1, distance: 4.3)
+    #
+    # Here "warp factor" would be converted to "warp_factor".
+    def using(data)
+      data.each do |key, value|
+        use_data_with(key, value.to_s) if object_enabled_for(key)
+      end
+    end
+
+    alias using_data   using
+    alias use_data     using
+    alias using_values using
+    alias use_values   using
+    alias use          using
+
+    private
+
+    # This is the method that is delegated to in order to make sure that
+    # elements are interacted with appropriately. This will in turn delegate
+    # to `set_and_select` and `check_and_uncheck`, which determines what
+    # actions are viable based on the type of element that is being dealt
+    # with. These aspects are what tie this particular implementation to
+    # Watir.
+    def use_data_with(key, value)
+      value = preprocess_value(value, key)
+
+      element = send(key.to_s.tr(' ', '_'))
+      set_and_select(key, element, value)
+      check_and_uncheck(key, element, value)
+      click(key, element)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
+    def preprocess_value(value, key)
+      return value unless value =~ /\(\(.*\)\)/
+
+      starter = value.index("((")
+      ender = value.index("))")
+      qualifier = value[starter + 2, ender - starter - 2]
+
+      if qualifier == "random_large"
+        value[starter..ender + 1] = rand(1_000_000_000_000).to_s
+      elsif qualifier == "random_ssn"
+        value = rand(9**9).to_s.rjust(9, '0')
+        value.insert 5, "-"
+        value.insert 3, "-"
+      elsif qualifier == "random_selection"
+        list = chain("#{key}.options.to_a")
+
+        selected = list.sample.text
+        selected = list.sample.text if selected.nil?
+        value = selected
+      end
+
+      value
+    end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+
+    def set_and_select(key, element, value)
+      key = key.to_s.tr(' ', '_')
+      chain("#{key}.set", value)    if element.class == Watir::TextField
+      chain("#{key}.set")           if element.class == Watir::Radio
+      chain("#{key}.select", value) if element.class == Watir::Select
+    end
+
+    def check_and_uncheck(key, element, value)
+      key = key.to_s.tr(' ', '_')
+      return chain("#{key}.check") if element.class == Watir::CheckBox && value
+
+      chain("#{key}.uncheck")      if element.class == Watir::CheckBox
+    end
+
+    def click(key, element)
+      chain("#{key}.click")        if element.class == Watir::Label
+    end
+
+    # This is a sanity check method to make sure that whatever element is
+    # being used as part of the data setting, it exists in the DOM, is
+    # visible (meaning, display is not 'none'), and is capable of accepting
+    # input, thus being enabled.
+    def object_enabled_for(key)
+      web_element = send(key.to_s.tr(' ', '_'))
+      web_element.enabled? && web_element.present?
+    end
+  end
+end