testable 0.3.0 → 0.8.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.rb

@@ -1,34 +1,160 @@
 require "testable/version"
-
+require "testable/page"
 require "testable/ready"
-require "testable/factory"
+require "testable/logger"
+require "testable/context"
 require "testable/element"
-require "testable/interface"
-require "testable/dom_update"
-require "testable/data_setter"
+require "testable/locator"
+require "testable/attribute"
+require "testable/deprecator"
+
+require "testable/capybara/page"
+
+require "testable/extensions/core_ruby"
+require "testable/extensions/data_setter"
+require "testable/extensions/dom_observer"
 
 require "watir"
-require "selenium-webdriver"
+require "capybara"
+require "webdrivers"
 
 module Testable
   def self.included(caller)
-    caller.extend Testable::Element
-    caller.extend Testable::Interface::Page::Attribute
+    caller.extend Testable::Pages::Attribute
+    caller.extend Testable::Pages::Element
     caller.__send__ :include, Testable::Ready
-    caller.__send__ :include, Testable::DataSetter
-    caller.__send__ :include, Testable::Interface::Page
+    caller.__send__ :include, Testable::Pages
     caller.__send__ :include, Testable::Element::Locator
+    caller.__send__ :include, Testable::DataSetter
   end
 
   def initialize(browser = nil, &block)
     @browser = Testable.browser unless Testable.browser.nil?
     @browser = browser if Testable.browser.nil?
+    begin_with if respond_to?(:begin_with)
     instance_eval(&block) if block
   end
 
+  # This accessor is needed so that internal API calls, like `markup` or
+  # `text`, have access to the browser instance. This is also necessary
+  # in order for element handling to be called appropriately on the a
+  # valid browser instance. This is an instance-level access to whatever
+  # browser Testable is using.
   attr_accessor :browser
 
   class << self
+    # Provides a means to allow a configure block on Testable. This allows you
+    # to setup Testable, as such:
+    #
+    #  Testable.configure do |config|
+    #    config.driver_timeout = 5
+    #    config.wire_level_logging = :info
+    #    config.log_level = :debug
+    #  end
+    def configure
+      yield self
+    end
+
+    # Watir provides a default timeout of 30 seconds. This allows you to change
+    # that in the Testable context. For example:
+    #
+    #   Testable.driver_timeout = 5
+    #
+    # This would equivalent to doing this:
+    #
+    #    Watir.default_timeout = 5
+    def driver_timeout=(value)
+      Watir.default_timeout = value
+    end
+
+    # The Testable logger object. To log messages:
+    #
+    #   Testable.logger.info('Some information.')
+    #   Testable.logger.debug('Some diagnostics')
+    #
+    # To alter or check the current logging level, you can call `.log_level=`
+    # or `.log_level`. By default the logger will output all messages to the
+    # standard output ($stdout) but it can be altered to log to a file or to
+    # another IO location by calling `.log_path=`.
+    def logger
+      @logger ||= Testable::Logger.new.create
+    end
+
+    # To enable logging, do this:
+    #
+    #   Testable.log_level = :DEBUG
+    #   Testable.log_level = 'DEBUG'
+    #   Testable.log_level = 0
+    #
+    # This can accept any of a Symbol / String / Integer as an input
+    # To disable all logging, which is the case by default, do this:
+    #
+    #   Testable.log_level = :UNKNOWN
+    def log_level=(value)
+      logger.level = value
+    end
+
+    # To query what level is being logged, do this:
+    #
+    #   Testable.log_level
+    #
+    # The logging level will be UNKNOWN by default.
+    def log_level
+      %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][logger.level]
+    end
+
+    # The writer method allows you to configure where you want the output of
+    # the Testable logs to go, with the default being standard output. Here
+    # is how you could change this to a specific file:
+    #
+    #   Testable.log_path = 'testable.log'
+    def log_path=(logdev)
+      logger.reopen(logdev)
+    end
+
+    # The wire logger provides logging from Watir, which is very similar to the
+    # logging provided by Selenium::WebDriver::Logger. The default level is set
+    # to warn. This means you will see any deprecation notices as well as any
+    # warning messages. To see details on each element interaction the level
+    # can be set to info. To see details on what Watir is doing when it takes a
+    # selector hash and converts it into XPath, the level can be set to debug.
+    # If you want to ignore specific warnings that are appearing during test
+    # execution:
+    #
+    # Watir.logger.ignore :warning_name
+    #
+    # If you want to ignore all deprecation warnings in your tests:
+    #
+    # Watir.logger.ignore :deprecations
+    #
+    # To have the wire logger generate output to a file:
+    #
+    # Watir.logger.output = "wire.log"
+
+    def wire_path=(logdev)
+      Watir.logger.reopen(logdev)
+    end
+
+    def wire_level_logging=(value)
+      Watir.logger.level = value
+    end
+
+    def wire_level_logging
+      %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][Watir.logger.level]
+    end
+
+    def watir_api
+      browser.methods - Object.public_methods -
+        Watir::Container.instance_methods
+    end
+
+    def selenium_api
+      browser.driver.methods - Object.public_methods
+    end
+
+    # This accessor is needed so that Testable itself can provide a browser
+    # reference to indicate connection to WebDriver. This is a class-level
+    # access to the browser.
     attr_accessor :browser
 
     def set_browser(app = :chrome, *args)
@@ -36,8 +162,14 @@ module Testable
       Testable.browser = @browser
     end
 
+    alias start_browser set_browser
+
     def quit_browser
       @browser.quit
     end
+
+    def api
+      methods - Object.public_methods
+    end
   end
 end

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/capybara/dsl.rb

@@ -0,0 +1,82 @@
+module Testable
+  module DSL
+    # The DSL module is mixed into the Node class to provide the DSL for
+    # defining elements and components.
+    def self.included(caller)
+      caller.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # The ClassMethods provide a set of macro-like methods for wrapping
+      # HTML fragments in Node objects.
+
+      # Defines an element that wraps an HTML fragment.
+      def element(name, selector, options = {})
+        define_method(name.to_s) do
+          Node.new(node: @node.find(selector, options))
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a collection of elements that wrap HTML fragments.
+      def elements(name, selector, options = {})
+        options = { minimum: 1 }.merge(options)
+
+        define_method(name.to_s) do
+          @node.all(selector, options).map do |node|
+            Node.new(node: node)
+          end
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a component that wraps an HTML fragment.
+      def component(name, klass, selector, options = {})
+        unless klass < Node
+          raise ArgumentError, 'Must be given a subclass of Node'
+        end
+
+        define_method(name.to_s) do
+          klass.new(node: @node.find(selector, options))
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a collection of components that wrap HTML fragments.
+      def components(name, klass, selector, options = {})
+        unless klass < Node
+          raise ArgumentError, 'Must be given a subclass of Node'
+        end
+
+        options = { minimum: 1 }.merge(options)
+
+        define_method(name.to_s) do
+          @node.all(selector, options).map do |node|
+            klass.new(node: node)
+          end
+        end
+
+        define_helpers(name, selector)
+      end
+
+      private
+
+      def define_helpers(name, selector)
+        define_existence_predicates(name, selector)
+      end
+
+      def define_existence_predicates(name, selector)
+        define_method("has_#{name}?") do
+          @node.has_selector?(selector)
+        end
+
+        define_method("has_no_#{name}?") do
+          @node.has_no_selector?(selector)
+        end
+      end
+    end
+  end
+end

data/lib/testable/capybara/node.rb

@@ -0,0 +1,30 @@
+require "testable/capybara/dsl"
+
+module Testable
+  class Node
+    # The Node class represents a wrapped HTML page or fragment. It exposes all
+    # methods of the Cogent DSL, making sure that any Capybara API methods
+    # are passed to the node instance.
+    include DSL
+
+    attr_reader :node
+
+    # A Capybara node is being wrapped in a node instance.
+    def initialize(node:)
+      @node = node
+    end
+
+    # Any Capybara API calls will be sent to the node object.
+    def method_missing(name, *args, &block)
+      if @node.respond_to?(name)
+        @node.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @node.respond_to?(name) || super
+    end
+  end
+end