Automate testing of browser-based applications in Windows, OSX, iOS, or Android
Note: Awetestlib is undergoing significant changes and this document is very much a work in progress.
- Support for cucumber and calabash is removed to keep things focused
- Support for classic Watir is removed. Watir-Webdriver and Selenium IE support are much improved since Awetestlib was first written.
- Native and hybrid mobile applications are not supported. Browser based apps only.
- The legacy awetestlib dsl is being phased out.
- The new dsl is both simplified and expanded. Code readability and consistency is the primary aim.
- The gem will be heavily documented using Yard conventions so look for the current deployed version in rubygems and rubydoc.info
Prerequisites: Ruby 2.0.x and RubyInstaller Devkit (Windows) or Xcode (Mac)
You need to have Ruby 2.0.x installed using the RubyInstaller package.
You can download the RubyInstaller for 2.0.x here. Choose the most recent 2.0.x.
Install in a directory without spaces, like C:\Ruby187. Don't install in Program Files.
Make sure you tell the installer to put Ruby in the PATH environment variable.
You can check your Ruby version using:
RubyInstaller Devkit (Windows only)
Additionally, for Windows, you will need to install the RubyInstaller DevKit to compile a few dependent gems.
Choose the one for Ruby 2.0.x and your Windows word size (32 or 64 bit) and download the package.
Create directory C:\devkit and unzip the devkit package into that directory.
Open a command window and change to C:\devkit.
ruby dk.rb init
ruby dk.rb review
And make sure you see C:\Ruby20x at the end of the output. Now
ruby dk.rb install
If you have difficulties with the above in Windows 7 and/or behind a firewall, you may have to set the http_proxy and/or run the installers as administrator. (see below)
Ruby 1.8.7 is installed by default in OSX. You will have to update to 2.0.x
Follow Mac instructions for installing/upgrading Xcode to latest version.
Start by opening a command window or terminal.
NOTE: If you are behind a firewall:
- You will need to set the http_proxy environment variable
- You may have to change the HOMEDRIVE environment variable to C: in Windows
- You may need to run the Windows 7 command window as administrator.
set http_proxy=http://myproxy.mycompany.com:80 set HOMEDRIVE=C:
Temporary but necessary (13may2013)
In the command window:
gem install nokogiri -v 1.5.9 --no-ri --no-rdoc
gem install mini_magick -v 3.5.0 --no-ri --no-rdoc
Then, in the command window, install the awetestlib gem.
Note: This could take up to 5 minutes for first time installs. You may need to use 'sudo' on OSX
gem install awetestlib --no-ri --no-rdoc
Then run the following command and verify the step
Run the following command to see the different usages
Appium (both Windows and OSX)
Emulator (Windows only)
Simulator (OSX only)
Safari (OSX only)
To setup support for Safari browser, download the Selenium Safari Standalone Server from Selenium downloads.
Select selenium-server-standalone-x.xx.xx.jar. (The version is 2.33.0 as of this writing.) Download it and copy it into /Library/Java/Extensions. You will need to start this process in a terminal session before running Safari scripts, else you will get a 'waiting for connection' error. Start it with this command in a terminal session:
nohup java -jar /Library/Java/Extensions/selenium-server-standalone-2.33.0.jar &
When using raw Watir-webdriver for Safari, open the browser with
browser = Watir::Browser.new(:remote, :desired_capabilities=>:'safari')
A Caveat: The Selenium SafariDriver currently cannot handle modal alerts/windows, except to dismiss them (invisibly) whenever they exist. (Issue 3862)
This means that any modal, expected or not, will not be visible when the selenium-server-standalone is running. Expected alerts ('Are you sure?') also do not appear, even when manually clicking link or button that should produce alert.
Firefox support is built into the selenium-webdriver gem (required by the watir-webdriver gem) for both Windows and OSX.
To setup support for Google Chrome browser, please download the latest Chromedriver version for your platform from here
Then move the executables into your PATH. To find your PATH, type the command below in your terminal/command prompt:
Internet Explorer (Windows only)
To setup support for Internet Explorer, please download the latest IEDriverServer version from here and move the executable into your PATH.
We suggest putting the Chrome and IE drivers in C:\Ruby187\bin (in Windows) as it should already be in your path.
Setup IDEs (Rubymine, Netbeans)
To setup the awetestlib gem with Rubymine use:
awetestlib rubymine_setup <ProjectName>
To setup awetestlib with Netbeans use:
awetestlib netbeans_setup <ProjectName>
You can now start your scripts within the IDE. Follow the instructions in each IDE for creating and executing run/debug configurations.
For additional information on IDE setup, refer to the links below:
Command Line Execution
If you prefer to run your tests from command line, you can use the following command
awetestlib <script_file> [options]
For example: To run a script named demo.rb in Firefox, your command will look like:
awetestlib demo.rb -b FF
Here is the full list of the currently available command line options:
Usage: awetestlib <script_file> [options] -b, --browser BROWSER Specify a browser (IE, FF, S, C) -r, --root_path ROOT_PATH Specify the root path (default is current path) -l, --library LIBRARY Specify a library to be loaded -x, --excel EXCEL_FILE Specify an excel file containing variables to be loaded -v, --version VERSION Specify a browser version -e, --environment_url URL Specify the environment URL -f, --environment_nodename NODE Specify the environment node name -n, --environment_name NAME Specify the environment name -u, --selenium_remote_url URL Specify the device's remote url and port -s, --screencap_path PATH Specify the path where screenshots will be saved -o, --output_to_log Write to log file --log_path_subdir SUBDIR Specify log path relative to root_path. Defaults to (root_path)/log if -o is specified. -p, --pry Require Pry for debugging -c, --classic_watir Use Classic Watir for IE instead of Watir-webdriver --report_all_test_refs Include list of all error/test case reference ids actually validated
To start writing your own script, refer to the Scripting Guide/Wiki wiki.
For the latest documentation of the Awetest DSL go to Rubydoc and look in Awetestlib::Regression.
One of the technologies that the Awetest framework supports is Cucumber. To get setup with cucumber, you can run the following command:
awetestlib cucumber_setup <ProjectName>
That will create the standard cucumber folder structure in the ProjectName directory.
Visit our wiki to see the list of predefined steps provided by awetestlib.