Getting started with Thucydides – using the Thucydides Maven Archetypes

thucydides is an open source library that lets you use webdriver/selenium 2 to write better acceptance tests. . the easiest way to start a new thucydides project is to use the maven archetype. two archetypes are currently available: one for using thucydides with junit, and another if you also want to write your acceptance tests (or a part of them) using easyb .

from the command line, you can run mvn archetype:generate and then select the net.thucydides.thucydides-easyb-archetype archetype from the proposed list of archetypes. or you can use your favorite ide to generate a new maven project using an archetype.

$ mvn archetype:generate
...
define value for property 'groupid': : com.mycompany
define value for property 'artifactid': : webtests
define value for property 'version':  1.0-snapshot: :
define value for property 'package':  com.mycompany: :
confirm properties configuration:
groupid: com.mycompany
artifactid: webtests
version: 1.0-snapshot
package: com.mycompany
 y: :
[info] ------------------------------------------------------------------------
[info] build success
[info] ------------------------------------------------------------------------
[info] total time: 2:33.290s
[info] finished at: fri oct 28 07:20:41 nzdt 2011
[info] final memory: 7m/81m
[info] ------------------------------------------------------------------------

this will create a simple thucydides project, complete with a page object, a step library and two test cases, one using junit, and one using easyb. before going any further, take the project for a spin: go into the generated project directory, run the tests and generate the reports:

$ mvn test thucydides:aggregate

this should run some web tests and generate a report in target/site/thucydides directory (open the index.html file). you should see a report like this one:

if you drill down into the individual test reports, you will see an illustrated narrative for each test:

now for the details. the project directory structure is shown here:

+ src
   + main
      + java
         + com.mycompany.pages
            - homepage.java   

   + test
      + java
         + com.mycompany.pages
            + requirements
               - application.java
            + steps
               - endusersteps.java
            - searchbykeywordstorytest.java 

      + stories
         + com.wakaleo.webtests.wikipedia
            - searchingforcats.story

this project is designed to provide a starting point for your thucydides acceptance tests, and to illustrate some of the basic features. the tests come in two flavors: easyb and junit . easyb is a groovy-based bdd (behaviour driven development) library which works well for this kind of test. the sample easyb story can be found in the searchingforcats.story file, and looks something like this:

	using "thucydides"

	thucydides.uses_default_base_url "http://www.wikipedia.com"
	thucydides.uses_steps_from endusersteps
	thucydides.tests_story searchbysinglekeyword

	scenario "searching for cats", {
	    given "the user is on the home page", {
	        end_user.is_on_the_wikipedia_home_page()
	    }
	    when "the end user searches for 'cats'", {
	        end_user.searches_by_keyword('cats')
	    }
	    then "they should see the corresponding article", {
	       end_user.should_see_article_with_title("cat - wikipedia, the free encyclopedia")
	    }
	}

a cursory glance at this story will show that it relates a user searching for entries on cats on wikipedia. however only the “what” is expressed at this level – the details are hidden inside the test steps and, further down, inside page objects.

if you prefer pure java tests, the junit equivalent can be found in the searchbykeywordtest.java file:

@story(searchbysinglekeyword.class)
@runwith(thucydidesrunner.class)
public class searchbykeywordstorytest {

    @managed(uniquesession = true)
    public webdriver webdriver;

    @managedpages(defaulturl = "http://www.wikipedia.com")
    public pages pages;

    @steps
    public endusersteps enduser;

    @test
    public void searching_by_keyword_cat_should_display_article_about_cats() {
        enduser.is_on_the_wikipedia_home_page();
        enduser.searches_by_keyword("cats");
        enduser.should_see_article_with_title("cat - wikipedia, the free encyclopedia");

    }

}

as you can see, this is a little more technical but still very high level.

the step libraries contain the implementation of each of the steps used in the high-level tests. for complex tests, these steps can in turn call other steps. the step library used in this example can be found in endusersteps.java:

public class endusersteps extends scenariosteps {

	public endusersteps(pages pages) {
		super(pages);
	}

    @step
    public void searches_by_keyword(string keyword) {
        enters(keyword);
        performs_search();
    }

	@step
	public void enters(string keyword) {
        onhomepage().enter_keywords(keyword);
	}

    @step
    public void performs_search() {
        onhomepage().starts_search();
    }

    private homepage onhomepage() {
        return getpages().currentpageat(homepage.class);
    }

    @step
	public void should_see_article_with_title(string title) {
        assertthat(onhomepage().gettitle(), is(title));
	}

    @step
    public void is_on_the_wikipedia_home_page() {
        onhomepage().open();
    }
}

page objects are a way of encapsulating the implementation details about a particular page. selenium 2 has particularly good support for page objects, and thucydides leverages this. the sample page object can be found in the homepage.java class:

	@defaulturl("http://www.wikipedia.org")
	public class homepage extends pageobject {

		private webelement searchinput;

		@findby(name="go")
		private webelement searchbutton;

		public homepage(webdriver driver) {
			super(driver);
		}

		public void enter_keywords(string keyword) {
			searchinput.sendkeys(keyword);
		}

	    public void starts_search() {
	        searchbutton.click();
	    }
	}

the final piece in the puzzle is the application.java class, which is a way of representing the structure of your requirements in java form, so that your easyb and junit tests can be mapped back to the requirements they are testing:

	public class application {
	    @feature
	    public class search {
	        public class searchbykeyword {}
	        public class searchbyanimalrelatedkeyword {}
	        public class searchbyfoodrelatedkeyword {}
	        public class searchbymultiplekeywords {}
	        public class searchforquote{}
	    }

	    @feature
	    public class backend {
	        public class processsales {}
	        public class processsubscriptions {}
	    }

	    @feature
	    public class contribute {
	        public class addnewarticle {}
	        public class editexistingarticle {}
	    }
	}

this is what enables thucydides to generate the aggregate reports about features and stories.

from http://weblogs.java.net/blog/johnsmart/archive/2011/10/31/getting-started-thucydides-%e2%80%93-using-thucydides-maven-archetypes