Selenium4j is a tool translating Selenium IDE HTML scripts to Java JUnit tests.
Selenium4j is a tool translating HTML Selenium scripts to Java JUnit tests allowing easy integration to an automated testing environment.
Problems with Selenium IDE HTML tests
While Selenium IDE is great tool for creating HTML tests, the HTML scripts are not Java tests and as such are not usable outside of the Selenium IDE environment
Using the IDE to create the Java JUnit test works one way only - from HTML to Java. Re-using the java test within Selenium IDE proved to be unreliable and buggy
Using Selenium RC to invoke the HTML files is not practical solution as it allows only a limited configuration such as browser, server and a single suite. E.g.
java -jar selenium-server.jar -multiwindow -htmlSuite "*iexplore" "https://www.website.com" "C:\suite.html" "C:\results.html"
Motivation for Selenium4j
In reality we would like to:
- Reuse the Selenium HTML suites for regression testing
- To be able to integrate them within an automated environment (think CruiseControl f.i.)
- Make the test configurable
WebDriver (Selenium2) solution?
Looking into WebDriver there is no analog of the Selenium IDE. The IDE is an amazing tool for recording the user clicks and it should be great if WebDriver solve the HTML automation integration. It seems that the later version of the IDE (1.0.5 as of writing) provides better support for the new Selenium2 API. Yet, the problem with HTML test integration is still on the table. As long as you record your script and export it to HTML, you are on your own. You need to manually use the IDE to translate the HTML scripts to the desired language (Java in my case), then you need to copy the source, paste it to you Eclipse/Netbeans, make sure compiles, configure it properly. In other words, it's not fun. WebDriver should provide a solution that simplifies that process and at the end the recorded Selenium IDE script should be seamlessly integrated within an automated environment. In that context, Selenium4j is an example how HTML could be easily translated to a Java JUnit sources.
How does Selenium4j work?
In short Selenium4j translates the HTML tests to Java JUnti tests. It iterates through the HTML suite and tests, digest them and discovers their Selenium commands. Each command is being subsequently transformed to a Java JUnit method. At the end of the transformation the HTML scripts are being translated to Java JUnit sources following same directory(package) structure as the suite and tests. In addition, Selenium4j have suite setup/teardown utilities as well as external configuration.
Open Firefox and [http://seleniumhq.org/download/ Install Selenium IDE]
Open [http://seleniumhq.org/projects/ide/ Selenium IDE]
Record your test and save it as suite and note the directory. The ant build file assumes /selenium4j/test-html. It should contain the following structure:
/selenium4j /test-html /MyTests suite.html test1.html test2.html
MyTestsdirectory as well as
test2names are being transformed to Java package and classes respectively, thus you should follow Java naming conventions when naming them.
Create selenium4j.properties file under your test suite as bellow.
selenium4j.propertiesis a configuration file containing the web site being tested, the used driver and the number of times the test to be invoked.
/selenium4j /test-html # MyTests is the directory where you can store your Selenium IDE HTML suite and test files /MyTests suite.html test1.html ... selenium4j.properties
selenium4j.properties should contain:
# the web site being tested webSite=http://www.website.com # A comma separated values of the WebDrivers being used. Accepted drivers: # HtmlUnitDriver, FirefoxDriver, ChromeDriver, InternetExplorerDriver driver=FirefoxDriver,ChromeDriver # How many times we want to iterate and test loopCount=1
Invoke ANT and execute build.xml. This will iterate through MyTests HTML files and will magically transform them to JUnit source files under
/selenium4j /test-java /MyTests # this folder will be populated with the HTML tests being converted to Java JUnit sources .. Test1.java Test2.java Suite.java
test-javafolder to your Eclipse/Netbeans source path and execute the generated JUnit tests. The latter will open the given driver(browser) and follow the same steps as in the HTML test.
Using the distibutable jar file
As above with an alternate step 7.
Build the jar:
ant dist The
selenium4j-transform.jar will be located in the
/selenium4j/dist directory. Feel free to move to a more convenient directory, the dependencies are all included in the jar file.
java -jar dist/selenium4j-transform.jar -htmlDir test-html -junitDir test-java. The selenium4j-transform.jar takes the parameters
htmlDir: Defaults to ./test-html. The selenese html source. junitDir: Defaults to ./test-java. The directory the JUnit tests will be created in. dieOnUnimplemented: Defaults to true. If your html tests contain a method that has yet to be implemented in java, a string will be written into the test source that will cause a compile error. If set to false, this string will be commented out, allowing the tests to continue. (Though if you're dependent on the missing test method, results may be, interesting.) createFrom: Defaults to 'suite'. The name of the file (without extension) to look for to create the JUnit Suite.
Selenium4j test suite derives from
org.kohsuke.junit.ParallelTestSuite [https://parallel-junit.dev.java.net/ Parallel JUnit] allowing parallel suite testing. Bear in mind that while multiple suites are running concurrently, the tests within a single suite are still being executed sequentially.
Setting up and Tearing down the tests
Selenium4j supports setup and teardown. Preview the example suite at
/selenium4j/test-html/google for setup and teardown samples.
/selenium4j /test-html /MyTests suite.html test1.html ... selenium4j.properties # setup directory follows the same structure as MyTests, # except it will be executed before MyTests, thus it can be used to init suite preconditions /setup suite.html setup.html ... selenium4j.properties # teardown directory follows the same structure as MyTests, # except it will be executed after MyTests, thus it can be used to cleanup suite resources /teardown suite.html setup.html ... selenium4j.properties
Open firefox and install Selenium IDE
Open Selenium IDE
Record your test and save it as suite under /selenium4j/test-html directory.
It should follow the following structure (Assuming you are testing google "GoogleTests" ):
/selenium4j /test-html /GoogleTests suite.html test1.html test2.html
Create and store a selenium4j.properties file under your test suite as below
/selenium4j /test-html /GoogleTests suite.html test1.html ... selenium4j.properties
If the file selenium4j.properties is not found, selenium4j will hunt up the tree up to the test-html directory looking for a file of that name. It will use the first one it finds.
selenium4j.properties should contain:
# the web site being tested webSite=http://www.nextinterfaces.com # The WebDriver being used. Accepted drivers: HtmlUnitDriver, FirefoxDriver, ChromeDriver, InternetExplorerDriver driver=FirefoxDriver # How many times we want to iterate and test loopCount=1
Edit build.properties to your satisfaction. Values will determine how and where tests are built. The following properties are expected:
src.test: Location off the project root where html format tests are to be found. If not specified, defaults to "test-html".
src.test.dir: Location off the project root where java tests will be written. Defaults to "test-java".
dieOnUnimplemented: Defaults to true. If your html tests contain a method that has yet to be implemented in java, a string will be written into the test source that will cause a compile error. If set to false, this string will be commented out, allowing the tests to continue. (Though if you're dependent on the missing test method, results may be, interesting.)
Invoke ANT and execute build.xml. This will iterate through GoogleTests HTML files and will tranform them to Java Junit source files under "/selenium4j/test-java" directory:
/selenium4j /test-java /GoogleTests .. Java JUnit source
Add test-java folder to your source path and execute the JUnit tests. The same test will get started opening the selected driver (browser)