comments added

Author: nareshnavinash

config/global.yml

@@ -1,3 +1,7 @@
+# This is the global configuration which this test framework uses at all the runs
+# This file is parsed in the libraries/config.rb file and used within the tests
+# A capability is added to specify this prams as an environment variable and use the same within the tests
+# Params declared as environment variables gets higher preference over the prams mentioned in this file
 browser: chrome
 headless: false
 screen_horizontal: 1280

config/production.yml

@@ -1 +1,8 @@
+# This file is where environment specific values are declared
+# Like this file is to hold the production environment details which can hold url, username, password and other details if needed
+# If we need to run the same tests in a different set of environment,
+# One can create a new file with new values and use the same to run the tests
+# For example, for staging environment run, create a file staging.yml and mention the same during the run as environment variable,
+# run as `run_config=staging.yml ruby spec/test_find_professionals.rb` this will pick the values from staging.yml file and run.
+# By default producition.yml file is taken for run, one can change that in libraies/config.rb file.
 url: https://www.upwork.com/

libraries/assert.rb

@@ -1,6 +1,19 @@
+# This library file is to have the common assertion methods that are used across the tests
+# The idea of this is inherited from rpsec-expectations,
+# where we can call the assertions at anypoint in the tests without using any objects
 require_relative 'logger.rb'
 include Libraries
 
+# This method gets two values as a mandatory input and logs appropriately in the stdout
+# If two values are same, then the log will be printed as PASS else FAIL
+# One can send the logger message as well if needed
+# For example: 
+#       1. expect_to_equal(1,1)
+#           -> PASS           > 1 is equal to 1
+#       1. expect_to_equal(1,2)
+#           -> FAIL           > 1 is not equal to 2
+#       1. expect_to_equal(1,1, "custom message")
+#           -> PASS           > custom message
 def expect_to_equal(value1, value2, message = nil)
     case value1.class.to_s
     when "Array"
@@ -24,11 +37,3 @@ def expect_to_equal(value1, value2, message = nil)
         end
     end
 end
-
-def expect_not_to_equal(value1, value2, message = nil)
-    if value1 != value2
-        Log.pass(message || "#{value1} is not equal to #{value2}")
-    else
-        Log.fail(message || "#{value1} is equal to #{value2}")
-    end
-end

libraries/config.rb

@@ -1,50 +1,69 @@
+# This file is where the global configs and run configs are parsed 
+# Here we are giving preference in the following order
+# Environment variable > Vaiable declared in the global.yml file > default value
 require 'yaml'
 
+# All the methods under this config class are class methods
+# This gives us flexibility in fethching the values directly across the framework
 module Libraries
     class Config
 
+        # To parse and read the global config and run config files
+        # Files will be parsed only once irrespective of any number of method calls
+        # One can direcly use the global vaiables $config or $run_config directly within the tests 
+        # Or use the custom methods for specific entities to have default fallback.
         def self.read_config_file
             $config ||= YAML.load_file(File.dirname(__FILE__).split("/libraries")[0] + '/config/global.yml')
             run_config_file = ENV["run_config"] || "production.yml"
             $run_config ||= YAML.load_file(File.dirname(__FILE__).split("/libraries")[0] + '/config/' + run_config_file)
         end
 
+        # To set the logger level that is needed for a run, one can change by running,
+        #`logger_level=test ruby spec/test_find_professionals.rb`
         def self.logger_level
             Config.read_config_file
             return ENV["logger_level"] || $config["logger_level"] || "info"
         end
 
+        # To specify which browser to be used for running the tests, change durning run time by,
+        # `browser=firefox ruby spec/test_find_professionals.rb`
         def self.browser
             Config.read_config_file
             return ENV["browser"] || $config["browser"] || "chrome"
         end
 
+        # To specify weather to run the tess in headless mode, If we are running the tests in linux, headless mode is forced
         def self.headless
             Config.read_config_file
             linux_check = true if Gem::Platform.local.os.include? "linux"
             return linux_check || ENV["headless"] || $config["headless"] || false
         end
 
+        # To mention the implicit wait that is used by selenium during a page load
         def self.implicit_wait
             Config.read_config_file
             return ENV["implicit_wait"] || $config["implicit_wait"] || 10
         end
 
+        # To specify the screenshots that is taken during test run path.
         def self.screenshot_location
             Config.read_config_file
             return ENV["screenshot_location"] || $config["screenshot_location"] || "reports/screenshots"
         end
 
+        # To specify the browser screen horizontal size
         def self.screen_horizontal
             Config.read_config_file
             return $config["screen_horizontal"] || 1200
         end
 
+        # To specify the browser screen vertical size
         def self.screen_vertical
             Config.read_config_file
             return $config["screen_vertical"] || 700
         end
 
+        # To return the url used for the tests
         def self.url
             Config.read_config_file
             return ENV["url"] || $run_config["url"]

libraries/driver.rb

@@ -1,3 +1,6 @@
+# This file holds the driver methods that are going to be used across this framework
+# This is to create a wrapper around the selenium-webdriver in order to combine and use to our convinience
+# This wrapper class helps us to use the browser of our choice and could use with high flexibility
 require_relative "config.rb"
 require_relative "logger.rb"
 require 'selenium-webdriver'
@@ -8,11 +11,12 @@ class Driver
 		attr_accessor :driver
 		$focus_driver = nil
 		@driver = nil
-		@main_window = nil
-		@click_exception_count = nil
 		@@drivers = []
 		@@drivers_with_names = {}
 
+		# While initilizing the driver class a browser driver is initialized of our choice and assigned to the class object
+		# Ex: chrome_driver = Driver.new
+		# Ex: firefox_driver = Driver.new(browser="firefox") # or set the firefox variable as environment variable or in the global.yml file
 		def initialize(driver_name = "Driver", browser = Config.browser)
 			begin
 				start(driver_name,browser)
@@ -27,7 +31,12 @@ def initialize(driver_name = "Driver", browser = Config.browser)
 		##############################
 		# Custom methods of driver #
 		##############################
-
+		
+		# This is the main method to initialize the browser of our choice along with the specified options
+		# Specify the browser name and the current driver name to get the browser initiated
+		# List of browsers supported as of now chrome & firefox
+		# If you need to initialize the browser in headless mode set the headless true either in global.yml or in the environment variable
+		# Browser dimentions are also set from the global.yml file. If the tests are supposed to run in different dimentions change the settings promptly
 		def start(driver_name, browser)
 
 			case browser
@@ -69,13 +78,14 @@ def start(driver_name, browser)
 
 			target_size = Selenium::WebDriver::Dimension.new(Config.screen_horizontal, Config.screen_vertical)
 			@driver.manage.window.size = target_size
-			@click_exception_count=0
 			@@drivers.push(self)
 			@@drivers_with_names[self] = "#{driver_name}"
 			$focus_driver = self
 			return self
 		end
 
+		# This is to generate different user agent for each run
+		# This avoids captcha verification to some extent
 		def get_user_agent
 			list_of_user_agents = ["Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246",
 			"Mozilla/5.0 (X11; CrOS x86_64 8172.45.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.64 Safari/537.36",
@@ -85,36 +95,42 @@ def get_user_agent
 			return list_of_user_agents.sample
 		end
 
+		# TO load the browser with specific URL.
 		def get(url)
 			$focus_driver = self
 			@driver.get(url)
 			Log.info("#{$focus_driver} browser is loaded with - #{url}")
 		end
 
+		# To Clear cookies from the current browser driver
 		def clear_cookies
 			$focus_driver = self
 			@driver.manage.delete_all_cookies
 			Log.info("Cleared cookies from the " + Config.browser + " browser #{$focus_driver}")
 		end
 
+		# To quit the current browser driver
 		def quit
 			Log.info("Quiting the browser - #{$focus_driver}")
 			@driver.quit
 			@@drivers.delete(self)
 		end
 
+		# To refresh the current browser driver
 		def refresh
 			$focus_driver = self
 			navigate.refresh
 			Log.info("#{$focus_driver} is refreshed")
 		end
 
+		# To find element in the current browser driver
 		def find_element(locator)
 			$focus_driver = self
 			Libraries::Wait.wait_for_element(locator)
 			return @driver.find_element(locator.how,locator.what)
 		end
 
+		# To save screenshot of the current browser driver
 		def save_screenshot(file = nil)
 			$focus_driver = self
 			if file.nil?
@@ -126,20 +142,24 @@ def save_screenshot(file = nil)
 			@driver.save_screenshot(file_name)
 		end
 
+		# To return the current browser driver element. This can be used to perform direct selenium actions over the browser driver
 		def self.get_current_driver
 			return $focus_driver
 		end
 
+		# To find multiple elements in the current browser. This returns a list of elements found for a specific locator
 		def find_elements(locator)
 			$focus_driver = self
 			return @driver.find_elements(locator.how,locator.what)
 		end
 
+		# This is to perform action in the browser driver
 		def action
 			$focus_driver = self
 			return @driver.action
 		end
 
+		# This is to scroll the browser window to a specific element
 		def scroll_to_locator(locator)
 			$focus_driver = self
 			element = find_element(locator)