HOWTO: Maven + StoryTestIQ + Selenium RC
StoryTestIQ is an automated acceptance testing tool, which was originally a mashup of 2 existing open source projects, Selenium and FitNesse. StoryTestIQ is many times shortened to STIQ (pronounced “stick”) so it rolls off the tongue more easily. STIQ takes the idea of testing inside the browser a la Selenium and enables editing, tagging, and multi-table execution through a modified FitNesse underneath the covers. The version control from FitNesse was removed so that the generated wiki files are able to be checked in, without any binaries, alongside the code those tests are executing against. The multi-table execution allows for test components, written in “selenese”, to be refactored out of and included in larger test cases. There are many more modifications that the development team, headed by Paul Dupuy, have done to enhance STIQ’s capabilities beyond running Fit and Selenium tests but this is enough background for now.
During STIQ’s development, we created a Maven 2 plugin, imaginatively named maven-stiq-plugin. This plugin did only 1 thing: start up the STIQ server for your project without having to run Java from the command line. In the past couple of days, I have finally had enough time and desire to develop integration of exporting STIQ tests into Selenium RC compliant “selenese” so they can also be executed during your Maven integration-test cycle in the 2.2-SNAPSHOT version. So, lets get down to the “how”.
First, add the STIQ Maven 2 repository to your POM (pom.xml file for your project) as shown below: (NOTE: updated with correction on URL from original posting)
<repositories> ... <repository> <id>STIQ Sourceforge</id> <url>https://storytestiq.svn.sourceforge.net/svnroot/storytestiq/trunk/www/maven2/</url> </repository> </repositories>
We, also, must put the STIQ Maven 2 repository into our plugin repositories within the POM because so that we can find the maven-stiq-plugin to execute during the integration-test cycles: (NOTE: updated with correction on URL from original posting)
<pluginRepositories> ... <pluginRepository> <id>STIQ Plugins Sourceforge</id> <url>https://storytestiq.svn.sourceforge.net/svnroot/storytestiq/trunk/www/maven2/</url> </pluginRepository> </pluginRepositories>
Next, we will put in the maven-stiq-plugin configuration.
<plugin> <groupId>net.sourceforge.storytestiq</groupId> <artifactId>maven-stiq-plugin</artifactId> <version>2.2-SNAPSHOT</version> <executions> <execution> <id>export</id> <phase>pre-integration-test</phase> <goals> <goal>export</goal> </goals> <configuration> <pageRootPath>repository</pageRootPath> <suiteWikiPagePath>ProjectRoot.StoryTests</suiteWikiPagePath> </configuration> </execution> <execution> <id>exec</id> <phase>integration-test</phase> <goals> <goal>exec</goal> </goals> <configuration> <userExtensions>src/main/resources/user-extensions.js</userExtensions> <browserType>*firefox</browserType> <suiteFile>target/stiq/ProjectRoot.StoryTests.html</suiteFile> </configuration> </execution> </executions> </plugin>
Now, to tell you a little bit about what is going on in the above configuration. The <groupId> and <artifactId> elements describe what plugin to grab from the plugin repository and use in the project. In the executions section, we define 2 separate execution elements. The first execution is called “export”. This execution will occur during the “pre-integration-test” cycle within the full Maven 2 build life cycle. The goal, similar to an Ant target, on our maven-stiq-plugin that you will be “export”, which is the goal that exports our StoryTestIQ acceptance tests as “selenese” to run within the Selenium RC server. The configurations shown above are <pageRootPath>, which is the directory located below your top-level project directory where the StoryTestIQ tests are located, and <suiteWikiPagePath>, which is a wiki page location for the top-level suite including all of the tests to export. If you don’t already have STIQ tests, please go to http://storytestiq.sf.net to find out how to get started.
The second execution element is called “exec”. This execution will run during the “integration-test” cycle in the Maven build life cycle and will execute the exported tests using Selenium RC server. The configurations for this goal are <userExtensions>, which is where any new selenese actions are defined specific to your project, <browserType>, which is the web browser to execute the tests within, and <suiteFile>, which is where the exported selenese tests were generated during the “export” goal execution. As a convention, the generated selenese file will be located under the “target/stiq” directory by default with the name of the file as <suiteWikiPagePath>.html.
Now you can run the usual ‘install’ command in your project’s top-level directory:
This should compile and execute all of your unit tests then during the integration-test phase it will run the maven-stiq-plugin goals, “export” and “exec” in that order. During the maven-stiq-plugin “exec” goal execution, the web browser will open up in the background and you will see the STIQ tests run. After the tests have executed, the web browser will close and the Maven build life cycle will complete.
NOTE: If you are having trouble with “*firefox” as <browserType>, then you might be seeing a current bug with Selenium RC server version 1.1.1. An upcoming release version will include a fix and we will update the dependency once we see the update. For now, the fix is to go back to Firefox version 3.5.3 or switch to using a different browser as listed here on the Selenium RC documentation.
There is still much more to do with the plugin before getting to a release version of 2.2. Please comment on this blog post with any suggestions or issues that you have with the plugin and it’s configuration. If you are interested, do a search on StoryTestIQ within this blog to find out more about using StoryTestIQ or visit the main project page http://storytestiq.sf.net. Thank you.