chemlab 0.5.0 → 0.6.0

data/lib/chemlab/cli/stubber.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../../chemlab'
+require 'erb'
+
+module Chemlab
+  module CLI
+    # This class is dedicated to stubbing Page Libraries
+    class Stubber
+      class << self
+        def libraries
+          @libraries ||= []
+        end
+
+        # Generate all stubs in a particular path
+        def stub_all(path)
+          Array(path).each do |p|
+            p = File.expand_path(p)
+
+            PageLibrary.new(p).generate_stub if File.file?(p)
+            Dir["#{p}/**/*.rb"].each do |f|
+              next if File.basename(f).include?('.stub.')
+
+              PageLibrary.new(f).generate_stub
+            end
+          end
+        end
+
+        # For each page that extends Chemlab::Page, run the stubber
+        class Chemlab::Page
+          def self.inherited(subclass)
+            print subclass
+
+            Stubber.libraries << subclass
+          end
+        end
+      end
+
+      # A Class representation of a Page Library
+      class PageLibrary
+        attr_accessor :path
+
+        def initialize(path)
+          @path = File.absolute_path(path)
+        end
+
+        # Generate the stub for a given Page Library
+        def generate_stub
+          $stdout.print "- #{@path} :\t"
+
+          begin
+            load @path
+
+            library = Stubber.libraries.last # last appended library is this Page Library
+
+            require 'active_support/core_ext/string/inflections'
+
+            stub_path = @path.gsub(@path[@path.rindex('.')..], '.stub.rb')
+            File.open(stub_path, 'w') do |stub|
+              stub.write(ERB.new(File.read(File.expand_path("#{__dir__}/stub.erb")),
+                                 trim_mode: '%<>').result_with_hash({ library: library }))
+              Stubber.libraries.pop
+            end
+          rescue StandardError => e
+            # $stderr.print(e.message)
+            raise e
+          ensure
+            $stdout.print "\tDone.\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemlab/component.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+
 module Chemlab
   # The base representation of *any* UI component.
   class Component
@@ -8,25 +10,54 @@ module Chemlab
     def_delegator :browser, :browser
     def_delegators :evaluator, :attribute
 
+    # Perform actions against the given page
+    # @example
+    #   Component.perform do |component|
+    #     component.do_something
+    #   end
+    # @example
+    #   Component.perform(&:do_something)
+    # @return The instance of +Component+ used to perform the action
     def self.perform
       yield new if block_given?
     end
 
     class << self
+      # Elements defined on the page
+      # @example
+      #   +text_field :username, id: 'username'+
+      #   Will be in form:
+      #     {
+      #       type: :text_field,
+      #       name: :username,
+      #       args: [ { id: 'username' } ]
+      #     }
+      # @return [Array]
+      def public_elements
+        @public_elements ||= []
+      end
+
+      # rubocop:disable Metrics/BlockLength
       Watir::Container.instance_methods(false).each do |watir_method|
+        # For each Watir element (h1, text_field, button, text_field, etc)
         define_method watir_method do |name, *args, &block|
           next if public_instance_methods.include? name
 
+          public_elements << { type: watir_method, name: name, args: args }
+
+          # @return [Watir::Element] the raw Watir element
           define_method("#{name}_element") do
             find_element(watir_method, name, args.first, &block)
           end
 
+          # @return [Boolean] true if the element is present
           define_method("#{name}?") do
-            send("#{name}_element").present?
+            public_send("#{name}_element").present?
           end
 
+          # === GETTER / CLICKER === #
           define_method(name) do
-            element = send("#{name}_element")
+            element = public_send("#{name}_element")
             if Element::CLICKABLES.include? watir_method
               element.wait_until(&:present?).click
             elsif Element::INPUTS.include? watir_method
@@ -36,22 +67,41 @@ module Chemlab
             end
           end
 
-          define_method("#{name}=") do |val|
-            if Element::SELECTABLES.include? watir_method
-              send("#{name}_element").select val
-            else
-              send("#{name}_element").set val
+          if (Element::SELECTABLES + Element::INPUTS).include?(watir_method)
+            # === SETTER === #
+            define_method("#{name}=") do |val|
+              if Element::SELECTABLES.include? watir_method
+                public_send("#{name}_element").select val
+              else
+                public_send("#{name}_element").set val
+              end
             end
           end
         end
       end
+      # rubocop:enable Metrics/BlockLength
     end
 
+    # If this component is currently visible
+    # @return [Boolean] true if the defined elements in the library are present
+    # @note The page presence is determined by the elements defined on the page and their requirement
+    def visible?
+      missing_elements = [] + self.class.public_elements
+
+      self.class.public_elements.each do |element|
+        missing_elements.shift if has_element?(element[:type], element[:name], element[:args].first)
+      end
+
+      missing_elements.none?
+    end
+
+    # DSL for both components and resources.
     class DSL
       def initialize(base)
         @base = base
       end
 
+      # An attribute to define for a component or resource
       def attribute(name)
         @base.module_eval do
           attr_writer(name)
@@ -76,12 +126,32 @@ module Chemlab
 
     private
 
+    # Find an element on the page
+    # @note this method will wait for the element to appear
+    # @see [has_element]
+    # @api private
+    # @example
+    #   #find_element(:text_field, :username) #=>
     def find_element(watir_method, name, locator = nil, &block)
       locator = { css: %([data-qa-selector="#{name}"]) } if locator.nil?
 
       return instance_exec(&block) if block_given?
 
-      Chemlab.configuration.browser.session.engine.send(watir_method, locator).wait_until(&:exist?)
+      Chemlab.configuration.browser.session.engine.public_send(watir_method, locator).wait_until(&:exist?)
+    end
+
+    protected
+
+    # Check existence of an element on the page
+    # @note this method will _not_ wait for the element
+    # @see [find_element]
+    # @api private
+    # @example
+    #   #has_element?(:text_field, :username) => returns false if the element is is not there
+    def has_element?(watir_method, name, locator = nil)
+      locator = { css: %([data-qa-selector="#{name}"]) } if locator.nil?
+
+      Chemlab.configuration.browser.session.engine.public_send(watir_method, locator).present?
     end
   end
 end

data/lib/chemlab/configuration.rb

@@ -3,20 +3,77 @@
 module Chemlab
   # Chemlab Configuration
   class Configuration
+    include Runtime::Logger
+
+    # Chemlab Terminal Banner
+    BANNER = <<~'BANNER'
+
+                    ##                                                ##
+                   ####                                              ####
+                  ######                                            ######
+                 #######                                           #######
+                 ########                                         #########
+                ##########                                        #########
+                ##########                                       ###########
+               ############                                      ############
+              ##########/------------------------------------------\#########
+             ##########/  / ___| |__   ___ _ __ ___ | | __ _| |__   \#########
+             #########|  | |   | '_ \ / _ \ '_ ` _ \| |/ _` | '_ \   |########
+            ##########|  | |___| | | |  __/ | | | | | | (_| | |_) |  |#########
+            ###########\  \____|_| |_|\___|_| |_| |_|_|\__,_|_.__/  /###########
+           #############\------------------------------------------/#############
+          \*********************############################********************/
+          \\\********************##########################********************///
+         \\\\\\******************#########################*******************//////
+        \\\\\\\\******************########################******************////////
+        \\\\\\\\\\*****************######################*****************//////////
+       \\\\\\\\\\\\****************#####################****************/////////////
+      \\\\\\\\\\\\\\\***************####################***************///////////////
+      \\\\\\\\\\\\\\\\***************##################**************/////////////////
+       \\\\\\\\\\\\\\\\\*************#################**************/////////////////
+          \\\\\\\\\\\\\\\*************################************////////////////
+             \\\\\\\\\\\\\\************##############************//////////////
+               \\\\\\\\\\\\\\**********#############***********/////////////
+                  \\\\\\\\\\\\**********############**********////////////
+                     \\\\\\\\\\\********###########*********///////////
+                        \\\\\\\\\********#########********//////////
+                          \\\\\\\\\*******########*******////////
+                             \\\\\\\*******######******////////
+                                \\\\\\*****######*****//////
+                                   \\\\\****####****/////
+                                     \\\\***###***////
+                                        \\\**##**///
+                                           \****/
+                                             **
+    BANNER
+
+    def initialize
+      yield self if block_given?
+
+      log(BANNER, :begn) unless hide_banner
+      log(<<-CONF, :conf)
+
+      ==> Base URL: #{base_url}
+      ==> Browser: #{browser}
+      ==> Libraries: #{libraries}
+      CONF
+    end
+
     # Add a chemlab configuration
     def self.add_config(name)
       attr_accessor name
     end
 
     add_config :base_url
+    add_config :hide_banner
+
+    attr_reader :browser, :libraries
 
-    attr_reader :browser
     # Set the browser and browser arguments Chemlab should use
     def browser=(browser)
       @browser = Runtime::Browser.new(browser)
     end
 
-    attr_reader :libraries
     # Specify which libraries to load
     def libraries=(libraries = [])
       @libraries = Chemlab.const_set('Vendor', Module.new)
@@ -31,16 +88,7 @@ module Chemlab
       RSpec.configure do |rspec|
         yield rspec if block_given?
 
-        # TODO Change this. /spec/api /spec/ui is hardcoded
-        rspec.define_derived_metadata(file_path: Regexp.new('/spec/api')) do |metadata|
-          metadata[:type] = :api
-        end
-
-        rspec.define_derived_metadata(file_path: Regexp.new('/spec/ui')) do |metadata|
-          metadata[:type] = :ui
-        end
-
-        rspec.after(:each, type: :ui) do
+        rspec.after(:each) do
           Chemlab.configuration.browser&.session&.engine&.quit
         end
       end

data/lib/chemlab/element.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Chemlab
+  # Element types
   module Element
+    # Elements that can be clicked
     CLICKABLES = %i[
       a
       button
@@ -11,10 +13,12 @@ module Chemlab
       radio
     ].freeze
 
+    # Elements that are +<select>+
     SELECTABLES = %i[
       select
     ].freeze
 
+    # Text input elements
     INPUTS = %i[
       text_field
       text_area

data/lib/chemlab/page.rb

@@ -3,11 +3,29 @@
 module Chemlab
   # Representation of a Page on the UI
   class Page < Component
-
     attribute :path
 
+    # Visit the given page, specified by +path '/the_path'+
     def visit
       Runtime::Browser.navigate_to(self.class)
     end
+
+    # Check that the current Path segment of the URL matches the Path of the page
+    # @return [Boolean] true if the path segment matches
+    # @example
+    #   class Page
+    #     path '/test'
+    #   end
+    #
+    #   Page.perform do |page|
+    #     page.visit
+    #     expect(page).to be_on_page #=> passes if the path segment of the browser URL matches /test
+    #   end
+    def on_page?
+      URI(Chemlab.configuration.browser.url).path&.match?(self.class.path)
+    rescue TypeError
+      # it's likely there is no path because of the page using the data protocol e.g.: "data:,"
+      false
+    end
   end
 end

data/lib/chemlab/runtime/browser.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+
 module Chemlab
   module Runtime
     # The browser configurator
     class Browser
-      extend SingleForwardable
+      extend Forwardable
       attr_accessor :session
       attr_reader :browser_options
 
+      def_delegators :session, :url, :refresh, :text, :quit
+
       def initialize(browser_options)
         @browser_options = browser_options
         @session = Session.new(browser_options)
@@ -22,32 +26,24 @@ module Chemlab
         @session.engine.goto(Chemlab.configuration.base_url + path)
       end
 
+      # The options used to create the browser session
+      def to_s
+        @browser_options.to_s
+      end
+
       # An individual session
       class Session
+        extend Forwardable
         attr_reader :engine
 
+        def_delegators :engine, :url, :refresh, :text, :quit
+
         def initialize(browser)
           @engine = Watir::Browser.new(*browser)
 
           # @engine.goto(Chemlab.configuration.base_url)
         end
 
-        def current_url
-          engine.url
-        end
-
-        def refresh
-          engine.refresh
-        end
-
-        def text
-          engine.text
-        end
-
-        def quit
-          engine.close
-        end
-
         def save_screenshot(file_name)
           engine.screenshot.save(file_name)
         end

data/lib/chemlab/runtime/env.rb

@@ -4,18 +4,22 @@ module Chemlab
   module Runtime
     # Environment configuration file
     module Env
-      module_function
+      class << self
+        # @return [Boolean] true if debug mode is enabled
+        # @example
+        #   ENV['CHEMLAB_DEBUG'] = 'true'
+        #   Runtime::Env.debug? #=> true
+        def debug?
+          enabled?(ENV['CHEMLAB_DEBUG'], default: false)
+        end
 
-      def debug?
-        enabled?(ENV['DEBUG'], default: false)
-      end
-
-      private
+        private
 
-      def enabled?(value, default: true)
-        return default if value.nil?
+        def enabled?(value, default: true)
+          return default if value.nil?
 
-        (value =~ /^(false|no|0)$/i) != 0
+          (value =~ /^(false|no|n|0)$/i) != 0
+        end
       end
     end
   end