wsl 0.1.4

data/lib/utils/TestSuiteCleanup.rb

@@ -0,0 +1,24 @@
+#-------------------------------------------------------------#
+# Summary:  A simple convenience script to do stuff at the end
+#			of a test run.
+#
+# Purpose:  1) To print a total of passed and failed tests.
+# Pre-con:  None.
+# Post-con: None.
+#-------------------------------------------------------------#
+
+require "wsl"
+
+
+##
+# These are core tasks that have to be performed AFTER any other 
+# startup tasks.
+#
+def cleanup_core
+	# Print total summary at end of run.
+	total_summary
+	
+	rem "Core cleanup activities completed."
+end
+
+cleanup_core

data/lib/utils/TestSuiteStartup.rb

@@ -0,0 +1,29 @@
+#-------------------------------------------------------------#
+# Summary:  A simple convenience script to do stuff before
+#			starting the test suite.
+#
+# Purpose:  To perfom actions before starting the test suite.
+# Pre-con:  None.
+# Post-con: None.
+#-------------------------------------------------------------#
+
+require "wsl"
+require "log4r"
+require "log4r/formatter/patternformatter"
+
+##
+# These are core tasks that have to be performed BEFORE any other 
+# startup tasks.
+#
+def startup_core
+	# Clear the cache of any old data.
+	clear_cache
+
+	# Workout the test suite name and initialise a suite logger.
+	logFile = "logs/" + $0.to_s.split("/")[-1].chomp(".rb") + ".log"
+	Wsl::CustomLogger.initializeSuiteLogger(logFile)
+	
+	rem "Core startup activities completed."
+end
+
+startup_core

data/lib/wsl.rb

@@ -0,0 +1,600 @@
+require "IEContext"
+require "wslPrivate"
+require "watir/contrib/visible"
+
+##
+# Starts the test.
+#
+# testName: the name of the test.
+# logFile: the file to log to.
+#
+def start(testName, logFile=nil)
+	@myBrowser = BrowserContext.new(testName, logFile)
+end
+
+##
+# Opens a new browser with the given url.
+#
+# url: the url to point the browser to.
+#
+def open_url(url)
+	@myBrowser.logger.logStep("Opening browser at url: '" + url + "'")
+		
+	# Point to url and open.
+	@myBrowser.new_browser_at(url)
+	@myBrowser.browser.speed = :zippy
+end
+
+##
+# Returns the current url of the browser.
+#
+def current_url
+	@myBrowser.logger.logStep("Current url: '" + @myBrowser.currentUrl + "'")	
+	return @myBrowser.currentUrl
+end
+
+##
+# Attaches the test to a new browser window 
+# TODO: How to close the old window?
+#
+# windowTitle: the name of the new window to attach to
+#
+def attach(windowTitle)
+	@myBrowser.logger.logStep("Attaching to new window with title: '" + windowTitle + "'")
+	@myBrowser.attach(windowTitle)
+end
+
+##
+# Closes the attached browser window.
+#
+def close(windowTitle=nil)
+
+	# Attach to the browser with the name passed in.
+	attach(windowTitle) if windowTitle != nil
+	
+	@myBrowser.logger.logStep("Closing browser")
+	@myBrowser.close_browser
+end
+
+##
+# Navigates to the given url.
+#
+# url: the url to navigate to.
+#
+def go_to(url)
+	@myBrowser.logger.logStep("Navigating to url: '" + url + "'")
+	@myBrowser.browser.goto(url)
+end
+
+##
+# Browses back a page.
+#
+def back
+	@myBrowser.logger.logStep("Navigating back.")
+	@myBrowser.browser.back()
+end
+
+##
+# Finishes the test.
+#
+def	finish
+	@myBrowser.close_browser		
+	@myBrowser.logger.logEndTest
+	@myBrowser.logger.summary
+	
+	# Reset step counter.
+	@myBrowser.logger.reset
+end
+
+##
+# Prints the total summary of all passed and
+# failed tests in run.
+#
+def total_summary
+	if ! defined? @myBrowser then
+		@myBrowser = BrowserContext.new()
+	end
+	
+	@myBrowser.logger.totalSummary
+	
+	# Clear the test cache so as not to corrupt the test summary.
+	@myBrowser.logger.clearCache
+end
+
+##
+# Clears the cache used by the logger.
+#
+def clear_cache
+	if ! defined? @myBrowser then
+		@myBrowser = BrowserContext.new()
+	end
+	
+	# Clear the test cache so as not to corrupt the test summary.
+	@myBrowser.logger.clearCache
+end
+
+##
+# Enters text in the named field.
+# field: The id of the html field.
+# value: The value you want to set.
+#
+# def enter_text_in(field, value)
+	# @myBrowser.logger.logStep("Entering text into field '" + field + "' with value '" + value + "'")
+	# @myBrowser.enter_text_into_field_with_id(field, value)
+# end
+def enter_text_in(what, how=":id", value=nil)
+	@myBrowser.logger.logStep("Entering text into html element with #{how} '" + what + "'")
+	
+	# parse string to build up correct code with right 'how' attribute.
+	code = <<TEMPLATE 
+	@myBrowser.browser.send(tag, #{how}, what)
+TEMPLATE
+	
+	@myBrowser.tagsInContext.each do |tag|
+		# Evaluate the code to execute it.
+		element = eval(code)  
+			
+		# Determine whether the passed in element has the method we want.
+		if element.exist? && element.respond_to?(:set) then
+			begin
+				return element.set(value)				
+			rescue => ex	
+				# Do nothing, we want to carry on through the list as 
+				# more than one type of element may have the set method.
+			end
+		end
+	end 
+	
+	# Notify the user element was not find.
+	@myBrowser.logger.log(" HTML element with #{how} '" + what + "' not found.")
+end
+
+##
+# Fires an onKeyPress event for the given textbox.
+#
+# field: The textbox to fire the event for (HTML id).
+#
+def key_press_in(field)
+	@myBrowser.logger.logStep("Firing onKeyPress event for: '" + field + "'")
+	@myBrowser.browser.text_field(:id, field).fire_event('onkeypress') 
+end
+
+##
+# Fires an onKeyUp event for the given textbox.
+#
+# field: The textbox to fire the event for (HTML id).
+#
+def key_up_in(field)
+	@myBrowser.logger.logStep("Firing onKeyPress event for: '" + field + "'")
+	@myBrowser.browser.text_field(:id, field).fire_event('onkeyup') 
+end
+
+##
+# Fires a onMouseOver event for the given textbox.
+#
+# field: The textbox to fire the event for (HTML id).
+#
+def mouse_over(field)
+	@myBrowser.logger.logStep("Firing onMouseOver event for: '" + field + "'")
+	@myBrowser.browser.text_field(:id, field).fire_event('onMouseOver') 
+end
+
+##
+# Fires a onMouseDown event for the given textbox.
+#
+# field: The textbox to fire the event for (HTML id).
+#
+def mouse_down(field)
+	@myBrowser.logger.logStep("Firing onMouseDown event for: '" + field + "'")
+	@myBrowser.browser.text_field(:id, field).fire_event('onMouseDown') 
+end
+
+##
+# Selects the named element.
+#
+# what: The element to select.
+# value: if specified true checks it, false unchecks it.
+#
+def select(what, how=":id", value=true)
+	@myBrowser.logger.logStep("Selecting html element with #{how} '" + what + "'")
+	
+	# parse string to build up correct code with right 'how' attribute.
+	code = <<TEMPLATE 
+	@myBrowser.browser.send(tag, #{how}, what)
+TEMPLATE
+	
+	@myBrowser.tagsInContext.each do |tag|
+		# Evaluate the code to execute it.
+		element = eval(code)  
+			
+		# Determine whether the passed in element has the method we want.
+		if element.exist? && element.respond_to?(:set) then
+			begin
+				return element.set(value)				
+			rescue => ex	
+				# Do nothing, we want to carry on through the list as 
+				# more than one type of element may have the set method.
+			end
+		end
+	end 
+	
+	# Notify the user element was not find.
+	@myBrowser.logger.log(" HTML element with #{how} '" + what + "' not found.")
+end
+
+##
+# Clicks the HTML element with the id specified. Note if multiple elements
+# are present it will click the first occurence of it only. The order it 
+# searches in is - button, link, image, div, span, and finally text_field.
+#
+def click(what, how=":id")
+	@myBrowser.logger.logStep("Clicking on html element with #{how} '" + what + "'")
+			
+	# parse string to build up correct code with right 'how' attribute.
+	code = <<TEMPLATE 
+	@myBrowser.browser.send(tag, #{how}, what)
+TEMPLATE
+	
+	@myBrowser.tagsInContext.each do |tag|
+		# Evaluate the code to execute it.
+		element = eval(code)  
+
+		# Determine whether the passed in element id exists, and click it.
+		if element.exist? && element.respond_to?(:click) then
+			return element.click			
+		end
+	end 
+	
+	# Notify the user element was not find.
+	@myBrowser.logger.log(" HTML element with #{how} '" + what + "' not found.")
+end
+
+##
+# Waits for the HTML element with the id specified to exist on screen.
+# Note if multiple elements are present it will look for the first occurence 
+# of it only or until the timeout (in seconds) is exceeded. 
+#
+# The order it searches in is - 
+# button, link, image, div, span, and finally text_field.
+#
+def wait_for(what, how=":id", timeout=60)
+	@myBrowser.logger.logStep("Waiting to load: '" + what + "'")		 		
+	tries = 0
+	
+	# parse string to build up correct code with right 'how' attribute.
+	code = <<TEMPLATE 
+	@myBrowser.browser.send(tag, #{how}, what)
+TEMPLATE
+	
+	# Until timeout is exceeded (or element exists).
+	until tries >= timeout do	
+		@myBrowser.tagsInContext.each do |tag|
+			element = eval(code)
+			# Evaluate the code to execute it and see if it exists.	
+			return if element.exists?	
+		end
+		
+		# Sleep for a bit and then try again.		
+		sleep 0.1
+		tries += 0.1
+	end
+		
+	# if got to here then notify the user element was not find.
+	@myBrowser.logger.log(" HTML element with id '" + what + "' not found.")
+end
+
+##
+# Waits for the browser to catch up. Useful for ajax calls
+# where the browser loads up some javascript.
+#
+def wait(aMoment=0)
+	if aMoment == 0 then
+		@myBrowser.logger.logStep("Waiting  for browser to catch up")
+	else
+		@myBrowser.logger.logStep("Pausing for " + aMoment.to_s + " secs then waiting  for browser to catch up")
+		sleep aMoment
+	end
+	
+	@myBrowser.browser.wait
+end
+
+##
+# Waits for a div tag to become visible or until the timeout
+# period has elapsed.
+# what: The id of the HTML div tag.
+# timout: maximum amount of time to wait for (default is 60 secs).
+#
+# TODO: Merge with wait_for method (add visible? to if condition)
+#
+def wait_until_visible(what, how=":id", timeout=60)
+	@myBrowser.logger.logStep("Waiting for : '" + what + "' to become visible")	
+	
+	tries = 0
+	
+	# parse string to build up correct code with right 'how' attribute.
+	code = <<TEMPLATE 
+	@myBrowser.browser.send(tag, #{how}, what)
+TEMPLATE
+	
+	# Until timeout is exceeded (or element exists).
+	until tries >= timeout do	
+		@myBrowser.tagsInContext.each do |tag|
+			# Evaluate the code to execute it and see if it exists.	
+			element = eval(code)
+			
+			# Element exists and is visible.
+			return element.visible? if element.exist? && element.visible?
+		end
+		
+		# Sleep for a bit and then try again.		
+		sleep 0.1
+		tries += 0.1
+	end
+		
+	# if got to here then notify the user element was not find.
+	@myBrowser.logger.log(" HTML element with id '" + what + "' has not become visible before timeout.")	
+end
+
+##
+# Records expected result, then asserts whether the 
+# text is displayed on screen to verify the expected
+# result.
+#
+# text: The text to look for on screen.
+# expectedResult: The expected result we are trying to verify. - This could potentially be factored out???
+#
+def assert_text(text, expectedResult=nil, timeout=60)		
+	@myBrowser.logger.logExpectedResult("'" + text + "' " + expectedResult) if expectedResult != nil
+	isFound = check_for_text(text)
+	
+	# Until conditions met sleep for 1 sec and then try again.
+	if timeout > 0 then 
+		tries = 0
+		
+		until isFound || tries >= timeout do		# URL match found or timeout exceeded.
+			isFound = check_for_text(text)
+			sleep 1
+			tries += 1
+		end
+	end
+	
+	if isFound then
+		# Text found
+		if expectedResult != nil then
+			@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "'" + text + "' found on screen.")
+		end
+		return true
+	else
+		# Text wasn't found
+		if expectedResult != nil then
+			@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, "'" + text + "' NOT found on screen.")
+		end
+		return false
+	end
+end
+
+##
+# Records expected result, then asserts whether the 
+# text is NOT displayed on screen to verify the expected
+# result.
+#
+# text: The text to look for on screen.
+# expectedResult: The expected result we are trying to verify. - This could potentially be factored out???
+#
+def assert_text!(text, expectedResult=nil)
+	@myBrowser.logger.logExpectedResult("'" + text+ "' " + expectedResult) if expectedResult != nil 
+		
+	begin		
+		if defined? @myBrowser.assert_text_in_body(text) then
+			
+			# If this is nil then we are doing a flow control assert - Do not log a test result
+			if expectedResult != nil then
+				@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, "'" + text + "' found on screen.")
+			end
+			
+			return false
+		else
+			# If this is nil then we are doing a flow control assert - Do not log a test result
+			if expectedResult != nil then
+				@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "'" + text + "' NOT found on screen.")
+			end
+			
+			return true		
+		end
+	rescue => ex
+		# Remember exception thrown when text not found.
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "'" + text + "' NOT found on screen.")
+		return false
+	end
+end
+
+def assert_all_text(args)
+	@myBrowser.logger.logExpectedResult("Asserting all text is shown on screen...")
+		
+	# Iterate and return false if any member of the array doesn't exist.
+	args.each do |at|
+		return false if !assert_text(at, "Expecting " + at + " to exist on screen.") 
+	end
+	
+	# Otherwise assertion is true.
+	return true
+end
+
+##
+# Asserts that the current url matches the pased in url. If orFailValue is
+# specified then a clever assertion is done whereby the method asserts 
+# every second until the url is matched, or the 'orFailValue' is matched to
+# the url OR found in the text body. If neither of these conditions are met 
+# within the timeout period then a fail due to a time out is registered 
+# for this assertion.
+#
+# The clever assertion is a workaround for any ajax submissions we do. 
+# currently there is no way to determine a response for an ajax call using 
+# Watir (There is an outstanding development request regarding this).
+#
+# url: The url to match on.
+# expectedResult: The expected result message to show on screen.
+# timeout: period in seconds before registering a failed assertion.
+# orFailValue: a value if found in the url or body text registers a fail.
+#
+def assert_url(url, expectedResult="is current url.", timeout=60, orFailValue=nil)	
+	# Get rid of the query string portion.
+	splitUrl = @myBrowser.currentUrl.split("?")[0]
+	
+	@myBrowser.logger.logExpectedResult("'" + url.to_s + "' " + expectedResult.to_s)
+	tries = 0
+	
+	begin
+		# Clever assertion.
+		if orFailValue != nil then	
+			# Until conditions met sleep for 1 sec and then try again.
+			until splitUrl.downcase  == url.downcase || 				# URL match found.
+				splitUrl.downcase == orFailValue.downcase || 			# Fail value found in url.
+				@myBrowser.assert_text_in_body(orFailValue) == nil ||	# Fail value found in body.
+				tries >= timout do										# Timeout exceeded.
+				sleep 1
+				tries += 1
+			end
+		# Simple assertion.
+		else
+			# Until conditions met sleep for 1 sec and then try again.
+			until splitUrl.downcase == url.downcase || 					# URL match found.
+				tries >= timeout do										# Timeout exceeded.
+				sleep 1													
+				tries += 1
+			end	
+		end
+				
+		# Assert pass or fail.
+		assert_url_conditions(splitUrl, url, timeout, orFailValue)
+	rescue => ex
+		@myBrowser.logger.logException ex
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, 
+			"'" + url.to_s + "' NOT current url or on screen." +
+			"\n       '" + @myBrowser.currentUrl + "' is current url.")
+		return false
+	end		
+end
+
+##
+# Logs a comment.
+#
+# text: The comment to log.
+#
+def rem(text)
+	@myBrowser.logger.logComment(text)
+end
+
+def manual_test(steps)
+	@myBrowser.logger.log(" Manual steps to perform:")
+	
+	# Log the steps
+	steps.each do |step| 
+		@myBrowser.logger.logStep(step)
+	end
+	
+	# Ask for pass or fail
+	result = ""
+	
+	until result.upcase  == "P" || result.upcase == "F" do
+		puts " Manual test pass or fail (P/F)? " 
+		result = gets.chomp	
+	end
+	
+	# Log result
+	@myBrowser.logger.logExpectedResult("Manual test passes")
+	
+	if result.upcase == "P" then
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "Manual test passed")
+	else
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, "Manual test failed")	
+	end
+end
+
+##
+# Records a PASS if the link exists
+#
+# what: The HTML id of the link
+#
+def assert_link_exists(what, expectedResult)
+	@myBrowser.logger.logExpectedResult(expectedResult)
+
+	if @myBrowser.browser.link(:id, what).exists? then
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "Link does exist")	
+		return true
+	else
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, "Link does not exist")
+		return false
+	end
+end
+
+##
+# Records a PASS if the button exists
+#
+# what: The HTML id of the button
+#
+def assert_button_exists(what, expectedResult)
+	@myBrowser.logger.logExpectedResult(expectedResult)
+
+	if @myBrowser.browser.button(:id, what).exists? then
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::pass, "Button does exist")	
+		return true
+	else
+		@myBrowser.logger.logActualResult(Wsl::CustomLogger::fail, "Button does not exist")
+		return false
+	end
+end
+
+##
+# Allows other steps to be executed and if certain conditions are not met then
+# the steps are repeated. Ideal for performing some manual steps which if not
+# done correctly then need to be repeated. If in the passed in block of steps
+# conditions are not met then call retryable_steps_error with appropriate message
+# to prompt for a repeat.
+#
+# -------------------------------------------------------------------------------
+# Example usage: 
+# retryable_steps{
+# 	Do some steps here
+#	...
+#	if pass condition is fail then
+#		Do any further steps if needed
+#		...	
+#		# Record the error with message
+#		retryable_steps_error "The steps failed you need to retry again"
+#	end
+#}
+# -------------------------------------------------------------------------------
+#
+# &block: The block of code to pass in (must be surrounded by '{' and '}')
+#
+def retryable_steps(&block)
+	begin
+		# Call the block
+		yield
+	rescue => ex 
+		# Output the message for completeness and then retry.
+		rem ex.message
+		retry
+	end
+end
+
+##
+# Used to report a retryable_steps needs to be re-tried.
+# If in the retryable steps the condition(s) to determine
+# pass/fail of the steps fails then call this.
+#
+# message: The message to display before retrying.
+#
+def retryable_steps_error(message)
+	# TODO: Create a custom error/exception?
+	raise ArgumentError, message
+end
+
+##
+# Shows all the elements in context in the order they are searched through.
+#
+def elements_in_context
+	rem "elements in context in order of precedence: \n[" + 
+		@myBrowser.tagsInContext().join(", ") + "]"
+end