haiyun-document / webdrivertestingtemplate

A Gradle template for JUnit Selenium WebDriver tests

Info

This is a Java project that can be used as a template (or archetype) to start a WebDriver web browser testing
project. I chose to simplify and not to implement most Selenium "remote" features, therefore implementing a
project using simply WebDriver and Gradle.

I am very much interested in others forking my code and/or letting me know how it can be improved.

The idea here is to replace your existing automation framework, such as "HP Quality Center", "XStudio", or "Rational
Functional Tester", with a pure Java solution managed by the Gradle build system.

Project Layout

Eclipse Root
+--- Project ':root'
+--- Project ':bing'
+--- Project ':commonlib'
+--- Project ':google'
+--- ...

Birdseye view

1. Project "bing" is a basic standalone browser test.
   
2. Project "google" is a RemoteWebDriver JUnit test-suite using a local Grid server that is capable of running
   multiple threads of web browser tests.
3. Project "multiwindowtest" is a test of multi window handling using a static local website.
   
4. Project "commonlib" is a sub-project containing methods shared between projects.
   
5. Project "root" is an 'includeFlat' Gradle-layout-alias to Eclipse project-root-dir 'WebDriverTestingTemplate'.

Quick Start

Normally, this project would be ran through the Gradle plugin for Eclipse IDE, but I have tried to make it easier by
including a method to run dynamically and directly from the .zip distribution on the command line.

To try this project without requiring a Java IDE, just make sure you download Gradle 1.3, configure your GRADLE_HOME
environment variable, add %GRADLE_HOME%\bin to your PATH, and then download the .zip distribution of this
project, unzip it, and run the included gradle_run.bat script.

Implemented Features

Feature	Description
JUnit based	For use ONLY with JUnit 4.11 or higher because of the usage of the parameterized capability of JUnit. This dependency is configured by the Gradle build script.
Parallel runner using JUnit	A parallel runner using the Gradle maxParallelForks method.
Native automation support	For use with Sikuli 1.0.1 or higher to test native elements that WebDriver "Action" is unable to control. This dependency is configured in the Gradle build script. If you implement this however, you may not be able to use the remote webdriver option in your project.
Uses RemoteWebDriver JSON Hub Server	I have included an implementation of a WebDriverServer class that starts a RemoteWebDriver JSON Hub server instance in the BeforeClass method of tests. This server is a static member of the utility class that the tests extend.
Parameterized data driven capability	Unit tests are parameterized from a csv file. Can also load tests from XML, XLS, a database, etc.
Logging and Reporting	Logs test output to console and to a file using SLF4j/LogBack API, and configured by a logback.xml file. Will generate reports of JUnit test results at build/reports/test/index.html . Will place a junit.log file at build/logs/junit.log .
Page Object design pattern	Uses the WebDriver "page object" design pattern, enhanced by the Selenium "LoadableComponent" extendable class.
Fluent API design pattern	Implemented examples of the Fluent API design pattern while retaining capability of the traditional page object pattern.
Multi-project build configuration	Implemented multiple project build. The root project has a subproject called "core" and all subprojects of "core" inherit classes from it.
Run Options	You have three different options for running the tests: via the Gradle GUI, via your IDE Gradle plugin, or via Gradle command line. To run with the JUnit runner in your IDE, you would need to manually export your project as a normal Java project, because this template does not support that.
Core utility package	All projects inherit from a "core" project that contains classes where you can store methods that all of your projects can share between them.

Un-implemented Features

Feature	Description
Gradle Wrapper	Did not choose to implement the Gradle wrapper because I believe that downloading Gradle and configuring GRADLE_HOME and PATH are easy enough. Also, a manual setup of Gradle gives us more control using a batch script.
Jar executable option	Creates an uberJar of all projects and subprojects that can be ran by double clicking the .jar file. If you don't have the file association supporting it, we include a jarAssociation.bat file to setup the file association on your Windows system. I was planning to implement this but currently having trouble getting it to work.

Configuration And Setup

Eclipse

To get it working on a regular Eclipse Juno (rather than Spring Source Suite) then perform the following
steps. If you deviate from these steps you risk importing the project incorrectly. You know you did it
correctly if your imported project resembles the screenshot I provided called "layout.png".

1. Add the following software repositories to your Eclipse software update panel:
   a. "SpringSource Update Site for Eclipse Juno 4.2" - http://dist.springsource.com/release/TOOLS/update/e4.2
   If you have Eclipse 3.x, then the Sprint 3.7 update site may work for you.
   (http://www.springsource.org/STS-installation-instructions )
2. Install the new software components called "Gradle Tooling API" and "Gradle IDE". Restart Eclipse.
   
3. Download the .zip archive of this GitHub project distribution and unzip it to your workspace. An example
   might be: "C:\Eclipse32\workspace\WebDriverTestingTemplate" .
   
4. Use the Eclipse "Import" function from the Eclipse "File menu" to import a "Project" of type "Gradle".
5. Browse using the import wizard to your projects "root" sub-directory described in Step #3 (above). Then click
   the "Build model" button. We do this because of the "includeFlat" Gradle layout.
6. Check all checkboxes . You could also choose to add all to your "working set" if you like but it isn't required.
   
7. Rebuild the dependencies by right clicking on the project and then choose Gradle-->Refresh All Dependencies
   
8. Right click on your project and choose "Run As-->External Tools Configuration". Configure a new "clean" and "build"
   configuration for running a sub-project (or whatever tasks you want to execute).
   
9. Optionally, you can run this project on the command line with "gradle identify google:show google:clean
   google:build --info" and it will execute the project unit tests. Also, this project provides a .bat batch
   script that does this and provides a menu of other actions you can execute.

IntelliJ-IDEA

Intellij-IDEA has a nice Gradle plugin that is included. The steps are otherwise similar to the Eclipse steps #3-#7
above.

Notes

I use "GitHub GUI" to sync my local project repo to GitHub. If you fork my project, I would recommend doing
it this way unless you are a Git expert and prefer another way.

Some related projects:
https://github.com/sebarmeli/Selenium2-Java-QuickStart-Archetype
https://github.com/sebarmeli/Selenium2-Java-Demo
http://code.google.com/p/selenium-ext/source/browse/

Website of this project:
http://djangofan.github.com/WebDriverTestingTemplate/

Markdown cheatsheet:
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

FAQ

1. If the intellisense in Eclipse doesn't work, make sure you have added all the .class directories to
   your Eclipse project classpath. (See the included .classpath file.)