testable 0.3.0 → 0.4.0

data/examples/testable-watir.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+
+class Home
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/"
+  url_matches(/heroku/)
+  title_is "Veilus"
+
+  # Elements can be defined with HTML-style names as found in Watir.
+  p          :login_form, id:    "open", visible: true
+  text_field :username,   id:    "username"
+  text_field :password
+  button     :login,      id:    "login-button"
+  div        :message,    class: "notice"
+
+  # Elements can be defined with a generic name.
+  # element :login_form, id:    "open", visible: true
+  # element :username,   id:    "username"
+  # element :password
+  # element :login,      id:    "login-button"
+  # element :message,    class: "notice"
+end
+
+# You can pass argument options to the driver:
+
+# args = ['user-data-dir=~/Library/Application\ Support/Google/Chrome']
+# Testable.start_browser :chrome, options: {args: args}
+
+# You can pass switches to the driver:
+
+# Testable.set_browser :chrome, switches: %w[--ignore-certificate-errors
+#                                            --disable-popup-blocking
+#                                            --disable-translate
+#                                            --disable-notifications
+#                                            --disable-gpu
+#                                            --disable-login-screen-apps
+#                                           ]
+
+Testable.start_browser :firefox
+
+page = Home.new
+
+# You can specify a URL to visit or you can rely on the provided
+# url_is attribute on the page definition. So you could do this:
+# page.visit("https://veilus.herokuapp.com/")
+page.visit
+
+expect(page.url).to eq(page.url_attribute)
+expect(page.url).to match(page.url_match_attribute)
+expect(page.title).to eq(page.title_attribute)
+
+expect(page.has_correct_url?).to be_truthy
+expect(page).to have_correct_url
+
+expect(page.displayed?).to be_truthy
+expect(page).to be_displayed
+
+expect(page.has_correct_title?).to be_truthy
+expect(page).to have_correct_title
+
+expect(page.secure?).to be_truthy
+expect(page).to be_secure
+
+expect(page.html.include?('<article id="index">')).to be_truthy
+expect(page.text.include?("Running a Local Version")).to be_truthy
+
+page.login_form.click
+page.username.set "admin"
+page.password(id: 'password').set "admin"
+page.login.click
+expect(page.message.text).to eq('You are now logged in as admin.')
+
+page.run_script("alert('Testing');")
+
+expect(page.browser.alert.exists?).to be_truthy
+expect(page.browser.alert.text).to eq("Testing")
+page.browser.alert.ok
+expect(page.browser.alert.exists?).to be_falsy
+
+# You have to sometimes go down to Selenium to do certain things with
+# the browser. Here the browser (which is a Watir Browser) that is part
+# of the definition (page) is referencing the driver (which is a Selenium
+# Driver) and is then calling into the `manage` subsystem, which gives
+# access to the window.
+page.browser.driver.manage.window.minimize
+
+# Sleeps are a horrible thing. But they are useful for demonstrations.
+# In this case, the sleep is there just to let you see that the browser
+# did minimize before it gets maximized.
+sleep 2
+
+page.maximize
+
+# Another brief sleep just to show that the maximize did fact work.
+sleep 2
+
+page.resize_to(640, 480)
+
+# A sleep to show that the resize occurs.
+sleep 2
+
+page.move_to(page.screen_width / 2, page.screen_height / 2)
+
+# A sleep to show that the move occurs.
+sleep 2
+
+page.screenshot("testing.png")
+
+Testable.quit_browser

data/lib/testable/attribute.rb

@@ -0,0 +1,38 @@
+require "testable/situation"
+
+module Testable
+  module Pages
+    module Attribute
+      include Situation
+
+      def url_is(url = nil)
+        url_is_empty if url.nil? && url_attribute.nil?
+        url_is_empty if url.nil? || url.empty?
+        @url = url
+      end
+
+      def url_attribute
+        @url
+      end
+
+      def url_matches(pattern = nil)
+        url_match_is_empty if pattern.nil?
+        url_match_is_empty if pattern.is_a?(String) && pattern.empty?
+        @url_match = pattern
+      end
+
+      def url_match_attribute
+        @url_match
+      end
+
+      def title_is(title = nil)
+        title_is_empty if title.nil? || title.empty?
+        @title = title
+      end
+
+      def title_attribute
+        @title
+      end
+    end
+  end
+end

data/lib/testable/context.rb

@@ -0,0 +1,72 @@
+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)
+      @active.visit
+      verify_page(@active)
+      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 if context.url_match_attribute.nil?
+      return if context.has_correct_url?
+
+      raise Testable::Errors::PageURLFromFactoryNotVerified
+    end
+
+    def create_active(definition)
+      @active = definition.new unless @active.is_a?(definition)
+    end
+
+    def call_block(&block)
+      yield @active if block
+      @active
+    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/data_setter.rb

@@ -0,0 +1,109 @@
+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) 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)
+      element = send(key.to_s.tr(' ', '_'))
+      set_and_select(key, element, value)
+      check_and_uncheck(key, element, value)
+    end
+
+    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
+
+    # 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

data/lib/testable/extensions/dom_observer.js

@@ -1,8 +1,35 @@
-// WebDriver arguments
-var element = arguments[0];
-var delay = arguments[1] * 1000;
+/*
+This functionality will only work for browsers that support it.
+See: http://caniuse.com/#feat=mutationobserver
+*/
+
+// WebDriver arguments, which are passed to the MutationObserver.
+var element  = arguments[0];
+var delay    = arguments[1] * 1000;
 var callback = arguments[2];
 
+/*
+The two functions below are similar in what they are doing. Both are
+disconneting the observer. Both are also invoking WebDriver's callback
+function.
+
+notStartedUpdating passes true to the callback, which indicates that the
+DOM has not yet begun updating.
+
+startedUpdating passes false to the callback, which indicates that the
+DOM has begun updating.
+
+The disconnect is important. You only want to be listening (observing) for the
+period required, removing the listeners when done. Since there be many DOM
+operations, you want to disconnet when there is interaction with the page by
+the automated scripts.
+
+When observing a node for changes, the callback will not be fired until the
+DOM has finished changing. That is the only granularity that is required for
+the Cogent implementation. What specific events occurred is not important
+because the goal is not to conditionally respond to them; rather just to know
+when the process has completed.
+*/
 var notStartedUpdating = function() {
     return setTimeout(function() {
         observer.disconnect();
@@ -16,7 +43,34 @@ var startedUpdating = function() {
     callback(false);
 };
 
-// Observer
+/*
+Mutation Observer
+The W3C DOM4 specification initially introduced mutation observers as a
+replacement for the deprecated mutation events.
+
+The MutationObserver is a JavaScript native object that allows for observing
+a change on any node-like DOM Element. "Mutation" means the addition or the
+removal of a node as well as changes to the node's attribute and data.
+
+The general approach is to create a MutationObserver object with a defined
+callback function. The function will execute on every mutation observed by
+the MutationObserver. The MutationObserver must be bound to a target, which
+for Cogent would mean the element whose context it is being called upon.
+
+A MutationObserver can be provided with a set of options, which indicate
+what kind of events should be observed.
+
+The childList option checks for additions and removals of the target node's
+child elements, including text nodes. This is basically looking for any
+nodes added or removed from documentElement.
+
+The subtree option checks for mutations to the target as well the target's
+descendants. So that means every child node of documentElement.
+
+The attribute option checks for mutations to the target's attributes.
+
+The characterData option checks for mutations to the target's data.
+*/
 var observer = new MutationObserver(startedUpdating);
 var config = { attributes: true, childList: true, characterData: true, subtree: true };
 observer.observe(element, config);