Watir: Difference between revisions

Browse history interactively ← Previous editContent deleted Content addedVisual WikitextInline

Revision as of 20:11, 12 October 2006 editSunSw0rd (talk \| contribs)Extended confirmed users796 editsm →WET ← Previous edit		Latest revision as of 13:51, 8 November 2023 edit undoEmeraude (talk \| contribs)Autopatrolled, Extended confirmed users, Pending changes reviewers82,429 editsNo edit summary
(237 intermediate revisions by more than 100 users not shown)
Line 1:		Line 1:
			{{More citations needed\|date=October 2012}}
	''''WATIR'''', pronounced "Water", is an acronym standing for "Web Application Testing in Ruby". Watir is an automated test tool which uses the Ruby scripting language to drive the Internet Explorer web browser, and is available as a Ruby Gem.
			{{Infobox software
			\| name = Watir
			\| logo = Watir.png
			\| screenshot =
			\| caption =
			\| developer = Bret Pettichord, Charley Baker, Angrez Singh, Jari Bakken, Jarmo Pertman, Hugh McGowan, Andreas Tolf Tolfsen, Paul Rogers, Dave Hoover, Sai Venkatakrishnan, Tom Copeland, Alex Rodionov, Titus Fortner
			\| latest release version = 6.17
			\| latest release date = {{Start date and age\|2020\|08\|28}}
			\| latest preview version =
			\| latest preview date =
			\| programming language = ]
			\| operating system = ]
			\| platform =
			\| genre = ] ] for ]s
			\| license = ]
			\| website = {{URL\|http://watir.com/}}
			}}
			'''Watir''' ('''W'''eb '''A'''pplication '''T'''esting '''i'''n '''R'''uby, pronounced water), is an open-source family of ] libraries for automating web browsers.<ref>{{cite web \|url=http://watir.com/ \|publisher=Watir \|accessdate=11 October 2012 \|title=Watir is...}}<br>- {{cite web\|title=A new member in the Watir-family \|url=http://www.opera.com/developer/tools/operawatir/ \|publisher=Opera Software \|archiveurl=https://web.archive.org/web/20110213011440/http://www.opera.com/developer/tools/operawatir/ \|archivedate=13 February 2011 \|accessdate=8 November 2023}}<br>- {{cite web \|title=Watir to WebDriver: Unit Test Frameworks \|url=https://www.facebook.com/notes/facebook-engineering/watir-to-webdriver-unit-test-frameworks/10150314152278920 \|website=Facebook \|accessdate=11 October 2012 \|url-access=subscription}}</ref><ref name="Agile Testing">{{cite book \|first1=Lisa \|last1=Crispin \|first2=Janet \|last2=Gregory \|title=Agile Testing: A Practical Guide for Testers and Agile Teams\|year=2008 \|publisher=Addison-Wesley \|isbn=9780321534460 \|pages=172\|url=https://books.google.com/books?id=68_lhPvoKS8C}}</ref> It drives ], ], ], ] and ], and is available as a ] gem.<ref name="Agile Testing" /><ref>{{cite book \|last=Marick \|first=Brian \|title=Everyday Scripting with Ruby: For Teams, Testers, and You \|year=2007 \|publisher=Pragmatic Programmer \|isbn=9780977616619 \|page=2 \|url=https://books.google.com/books?id=1vKBQgAACAAJ \|via=Google Books}}</ref> Watir was primarily developed by Bret Pettichord and Paul Rogers.

			== Functionality ==
	Ruby is an object oriented programming language started more than a decade ago in Japan (by Yukihiro Matsumoto). It is a very “pure” OO language. It is also an interpreted language, and has influences from multiple earlier OO languages. Ruby gems are packaged libraries.
			{{Update section\|date=April 2021}}
			Watir project consists of several smaller projects. The most important ones are watir-classic, watir-webdriver and watirspec.

			=== Watir-Classic ===
	WATIR makes use of the fact that Ruby has built in OLE capabilities. As such it is possible to drive the Microsoft Internet Explorer browser programmatically. Watir is a toolkit to automate browser-based tests during ].
			Watir-Classic makes use of the fact that Ruby has built-in ] (OLE) capabilities. As such it is possible to drive ''Internet Explorer'' programmatically.<ref>{{cite web \|title=Creating automated test scripts with Ruby and WATIR \|url=http://www.thoughtworks.com/articles/automated-testing-using-ruby-and-watir \|publisher=ThoughtWorks \|first=Jeremy \|last=Suarez \|date=16 September 2010\|accessdate=11 October 2012}}</ref> Watir-Classic operates differently to HTTP-based test tools, which operate by simulating a browser. Instead, Watir-classic directly drives the browser through the OLE protocol, which is implemented over the ] (COM) architecture.

			The COM permits interprocess communication (such as between Ruby and ''Internet Explorer'') and dynamic object creation and manipulation (which is what the Ruby program does to the ''Internet Explorer''). Microsoft calls this "OLE automation", and calls the manipulating program an "automation controller". Technically, the ''Internet Explorer'' process is the server and serves the automation objects, exposing their methods; while the Ruby program then becomes the client which manipulates the automation objects.
	==Installation==

			=== Watir-Webdriver ===
	WATIR is dependent upon Ruby, therefore both must be accessed. Ruby can be accessed at the page. The current stable version is 1.8.4-20 stable. Using the "1 click installer", the file downloaded will be ruby184-20.exe. Size is 27,940KB.
			Watir-Webdriver is a modern version of the Watir API based on ]. Selenium 2.0 (Selenium-Webdriver) aims to be the reference implementation of the ] specification. In Ruby, Jari Bakken has implemented the Watir API as a wrapper around the Selenium 2.0 API. Not only is Watir-Webdriver derived from Selenium 2.0, it is also built from the ] specification, so Watir-Webdriver should always be compatible with existing ] specifications.

			=== Watirspec ===
	WATIR can also be accessed at . The current standard version is 1.4.1. This version is to be preferred if you do not need to handle security popups or modal dialogs.
			Watirspec is executable specification of the Watir API, like ] is for Ruby.

			== See also ==
	Development work on WATIR moved from the Rubyforge area after the 1.4.1 release in August of 2005. It is now located at OpenQA.org. Once the WATIR 1.5 development branch is completed, it should be released back to Rubyforge here:
			{{Portal\|Free and open-source software}}
			* ]
			* ]
			* ]
			* ]

			== References ==
	To install the current 1.5 Ruby Gem, go to and download the gem.
			{{Reflist}}

			== External links ==
	Ruby should be installed first. Simply execute the ruby184-20.exe self extracting installer and let it run. This file will install ], ], a Ruby IDE called FreeRIDE, the SciTE text editor, and various documentation. It will install in C:\ruby. RubyGems are the Ruby libraries. Type ‘gem list’ to see all installed in a command window.
			*
			*
			* ''''
			* '''', a testers' workshop book by Jeff Morgan

			]
	Playing around with Ruby can be done within a command window by running the ]. Or do ‘Start/All Programs/Ruby-184-20/FreeRide. It takes a few seconds for this to launch. But once it is started you may execute Ruby code. Output goes to the output view pane, or by going to ‘Edit/Preferences’ and checking ‘Run process in terminal’ in ‘Debugger/Run’ it will appear in a command window. (This is preferable; otherwise not all output might be displayed.) So do this.
			]

			]
	WATIR should be installed next. Assuming you are installing the current development gem, do the following.
			]

			]
	#Open a command window
	#Change to directory where the gem was downloaded (assume C:\Watir)
	#Type in: “gem install watir”

	You should see something like this:

	C:\Watir>gem install watir
	Successfully installed watir, version 1.5.1.1100
	Installing ri documentation for watir-1.5.1.1100...
	Installing RDoc documentation for watir-1.5.1.1100...

	To uninstall this in the future, you will have to use the gem unistaller, because this installation does not add anything to your programs menu.

	You can validate that WATIR is installed by executing ‘gem list’ to see your installed gems. In the list you should now see something like this:

	watir (1.5.1.1100)
	Automated testing tool for web applications.

	If you accessed the development version from the link, you might also download the zip file titled "Bonus.zip". I suggest dropping it in the same directory where you placed the gem.

	==Examples==
	===The google example===

	# Here we see a very simple WATIR script to drive to google and validate a page
	require 'watir' # use watir gem
	test_site = <nowiki>'http://www.google.com'</nowiki> # set a variable
	ie = Watir::IE.new # open the IE browser
	ie.goto(test_site) # load url, go to site
	ie.text_field(:name, "q").set("pickaxe") # load text "pickaxe" into search field named "q"
	ie.button(:name, "btnG").click # "btnG" is the name of the Search button, click it
	if ie.text.include?("Programming Ruby")
	puts "Test Passed. Found the test string: 'Programming Ruby'."
	else
	puts "Test Failed! Could not find: 'Programming Ruby'"
	end

	The previous commands can be executed in the ] (irb), or in a Ruby IDE such as FreeRIDE that is installed when Ruby is installed with the once click installer.

	===Handling popups===
	# To handle general popups, use WinClicker.
	ie.button(:name, "btnG").click_no_wait # ensure popup won't block Watir
	hwnd = ie.enabled_popup(5) # get a handle if one exists
	if (hwnd) # yes there is a popup
	w = WinClicker.new
	w.makeWindowActive(hwnd)
	w.clickWindowsButton_hwnd(hwnd, "Yes") # click the "Yes" button
	end

	This example extends upon the google example by ensuring the google search button click will not wait for the popup. This approach will handle most annoying popups, however it may be necessary to download and install the current development Watir gem rather than using the standard Watir release.

	(Note -- this appears to be broken with the most recent development release e.g. 1.5.1.1100. To fix this, do the following:
	# Go to where Ruby was installed (assume C:\ruby) and go to: \lib\ruby\gems\1.8\gems\watir-1.5.1.1100\watir\contrib
	# Open the file enable_popup.rb
	# Insert the text "include Win32" (withOUT the quotes) right above the line "def enabled_popup(timeout=4)"
	# Save the file -- the above popup handling should work with the 1.5.1.1100 release with this fix.)

	===View Browser Objects===
	Suppose you want to be able to see the various objects within the browser? The following are useful:

	# To see objects within the browser
	ie.frame("top_frame").text_fields.each { \|t\| puts t.to_s }
	ie.frame("top_frame").spans.each { \|s\| puts s.to_s }
	ie.frame("top_frame").tables.each { \|t\| puts t.to_s }
	ie.frame("top_frame").links.each { \|l\| puts l.to_s }
	ie.frame("top_frame").select_lists.each { \|s\| puts s.to_s }
	ie.frame("top_frame").labels.each { \|l\| puts l.to_s }

	In the above example, this also shows you how you would access information from within a frame. If there were no frame involved, then drop the "frame("top_frame")." part of the commands.

	===Capture Timings===
	Suppose you want to capture timing information, because you are running a performance test.

	ie.button(:value, 'OK').click
	p ie.down_load_time

	This approach will time a single response. If you want to collect the time for a series of events, use this approach:

	# Performance test timing
	begin_time = Time.now
	=begin
	*****************************
	* Body of script goes here
	*****************************
	=end
	end_time = Time.now
	p (end_time - begin_time).to_s

	Be aware that anything enclosed by an "=begin" and "=end" (on their own lines) is treated as a multi line comment. Typically you might wrap the final button click to submit a page in these commands, and the timing information will then just show you the time from submission to page response.

	===Write Output to Excel (as CSV)===
	It may useful to be able to repeatedly record output to an Excel spreadsheet. Data written to a workbook can be displayed graphically in charts. (How to do this will not be provided here, but see the external link called "Ruby and Excel")

	Suppose you want to record a sequence of 4 screen to screen transition timings. You might then add the following to your script:

	#Read test data input file
	arr = IO.readlines("env.txt")
	executionEnvironment = arr
	acceptableScreen1 = arr.to_f
	acceptableScreen2 = arr.to_f
	acceptableScreen3 = arr.to_f
	acceptableScreen4 = arr.to_f
	#Result OK or not
	resultValue = "OK"
	#Strip line return from tested environment string
	executionEnvironment = executionEnvironment.chomp
	#open spreadsheet - new one each day this script is run
	timeSpreadsheet = File.new( "../PC/" + Time.now.strftime("%d-%b-%y") + ".csv", "a")
	=begin
	**************************
	* Add commands to load data to screen
	* Initialize timing variables as in "Capture Timings" example
	* Submit the "click" to submit from browser to web server
	* Update timing variable as in "Capture Timings" example
	**************************
	=end
	if acceptableScreen1 < actualTime
	resultValue = "NotOK"
	end
	#Log results
	timeSpreadsheet.puts executionEnvironment + ",Expected screen 1 time," + acceptableScreen1.to_s
	+ ",Actual screen 1 time," + (endTime - beginTime).to_s + "," + resultValue
	=begin
	**************************
	* Repeat this 3 times, once for each of the other 3 screens
	* Remember to reinitialize resultValue, endTime, and beginTime each time
	**************************
	=end
	#Close the browser
	ie.close if ie
	#Close the workbook
	timeSpreadsheet.close

	Some points about this example. First, the commented parts depend upon the previous examples above.

	Second, an input file is read to extract test case information. The information should be written on 5 separate lines. The first line contains a reference to the environment in which this test is run, e.g., "dev", "test", "int_test", etc. This first line is loaded into the variable executionEnvironment. The line feed must be chopped off the end of the string, otherwise when written to Excel this will be on its own line, and the other data would go to the next line -- we want everything in the same row in the worksheet.

	Third, the acceptableScreen# variables hold a number -- the expected maximum number of seconds for screen to screen response time. These numbers might all be the same, or different, depending on your test. The values are from lines 2 through 5 in the input file.

	Fourth and finally, the line above where the spreadsheet is written has a line break in it for formatting for this site, so if you copy the above you see that it is on two lines -- you would want to put it all on one line.
	===Write Output to Excel (as XLS)===
	So the above example is very simple, and may be all that is needed, but if you want to format the speadsheet it really needs to be in Excel format. In which case, the opening of the file and the writing to the file needs to be a bit different. Try this modification:

	#open spreadsheet
	excel = WIN32OLE::new('excel.Application')
	workbook = excel.Workbooks.Add
	worksheet = workbook.Worksheets(1)
	worksheet.SaveAs("spreadsheet.xls")
	#Log results
	worksheet.range("a1").value = executionEnvironment
	worksheet.range("b1").value = "Acceptable Screen1 time"
	worksheet.range("c1").value = acceptableScreen1.to_s
	worksheet.range("d1").value = "Actual Screen1 time"
	worksheet.range("e1").value = actualScreen1.to_s
	worksheet.range("f1").value = resultValue
	#
	# Etcetera...assume the above happens 4 times, for 4 screens...
	#
	#Format workbook columns
	worksheet.range("b1:b4").Interior = 36 #pale yellow
	worksheet.columns("b:b").AutoFit
	#close the workbook
	workbook.save
	workbook.close
	excel.Quit

	So this will permit you to not only write to Excel workbooks, but format the data as well. However here the writing is on a cell by cell basis rather than to an entire row as can be done in a CSV file.

	==Recording Scripts==
	There exists a very simple Ruby script called WatirMaker. See the External Link labeled "WatirMaker" to download it. Usage is very simple. Download it, remove the ".txt" suffix, then execute like:

	#Execute WatirMaker
	ruby WatirMaker.rb > c:\temp\rscript.rb

	That's it. Be aware that it will generate plenty of errors on any complex site. But some quick and judicious editing and you may find this little recorder to be very useful for you. Just don't expect it to compare to a commercial tool. It is merely a time saver to help you produce the framework for your script, which you can then polish up programmatically.

	==WET==
	WET is a powertool for Watir. WET stands for Watir Extension Toolkit. Because the WET classes inherit from the Watir classes, WET provides all of the Watir functionality plus additional feature, including powerful popup handling mechanisms. Follow the WET link in "External Links" below for futher details.

	==External Links==
	*
	*
	*
	*
	*
	*
	*
	*
	*

	==See also==
	*]
	*]
	*]
	*]

	]

Latest revision as of 13:51, 8 November 2023

This article needs additional citations for verification. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed.
Find sources: "Watir" – news · newspapers · books · scholar · JSTOR (October 2012) (Learn how and when to remove this message)

Watir

Developer(s)	Bret Pettichord, Charley Baker, Angrez Singh, Jari Bakken, Jarmo Pertman, Hugh McGowan, Andreas Tolf Tolfsen, Paul Rogers, Dave Hoover, Sai Venkatakrishnan, Tom Copeland, Alex Rodionov, Titus Fortner

Stable release	6.17 / August 28, 2020; 4 years ago (2020-08-28)

Written in	Ruby
Operating system	Cross-platform
Type	Software testing framework for web applications
License	MIT license
Website	watir.com

Watir (Web Application Testing in Ruby, pronounced water), is an open-source family of Ruby libraries for automating web browsers. It drives Internet Explorer, Firefox, Chrome, Opera and Safari, and is available as a RubyGems gem. Watir was primarily developed by Bret Pettichord and Paul Rogers.

Functionality

This section needs to be updated. Please help update this article to reflect recent events or newly available information. (April 2021)

Watir project consists of several smaller projects. The most important ones are watir-classic, watir-webdriver and watirspec.

Watir-Classic

Watir-Classic makes use of the fact that Ruby has built-in Object Linking and Embedding (OLE) capabilities. As such it is possible to drive Internet Explorer programmatically. Watir-Classic operates differently to HTTP-based test tools, which operate by simulating a browser. Instead, Watir-classic directly drives the browser through the OLE protocol, which is implemented over the Component Object Model (COM) architecture.

The COM permits interprocess communication (such as between Ruby and Internet Explorer) and dynamic object creation and manipulation (which is what the Ruby program does to the Internet Explorer). Microsoft calls this "OLE automation", and calls the manipulating program an "automation controller". Technically, the Internet Explorer process is the server and serves the automation objects, exposing their methods; while the Ruby program then becomes the client which manipulates the automation objects.

Watir-Webdriver

Watir-Webdriver is a modern version of the Watir API based on Selenium. Selenium 2.0 (Selenium-Webdriver) aims to be the reference implementation of the WebDriver specification. In Ruby, Jari Bakken has implemented the Watir API as a wrapper around the Selenium 2.0 API. Not only is Watir-Webdriver derived from Selenium 2.0, it is also built from the HTML specification, so Watir-Webdriver should always be compatible with existing W3C specifications.

Watirspec

Watirspec is executable specification of the Watir API, like RubySpec is for Ruby.

References

"Watir is..." Watir. Retrieved 11 October 2012.
- "A new member in the Watir-family". Opera Software. Archived from the original on 13 February 2011. Retrieved 8 November 2023.
- "Watir to WebDriver: Unit Test Frameworks". Facebook. Retrieved 11 October 2012.
^ Crispin, Lisa; Gregory, Janet (2008). Agile Testing: A Practical Guide for Testers and Agile Teams. Addison-Wesley. p. 172. ISBN 9780321534460.
Marick, Brian (2007). Everyday Scripting with Ruby: For Teams, Testers, and You. Pragmatic Programmer. p. 2. ISBN 9780977616619 – via Google Books.
Suarez, Jeremy (16 September 2010). "Creating automated test scripts with Ruby and WATIR". ThoughtWorks. Retrieved 11 October 2012.

External links

Watir home page
Watir source code
The Watir Podcast
Cucumber & Cheese, a testers' workshop book by Jeff Morgan

Categories: