Archive for August, 2012

Selenium Best Practices

It’s a summary (and few extras) of test_design_considerations

Use PageObjects pattern
Be fluent with 
  - return this, varargs, generics, 
  - reuse your model and jodatime
Be robust and portable 
  - Prefered selector order : id > name > css > xpath 
  - Avoid Thread.sleep prefer Wait or FluentWait
  - Use relative URLs
  - Don’t rely on specific Driver implementation
  - Create your dataset
Know your new tool
  - Keep up to date (versions and usage pattern)
  - Troubleshooting 
      - jre 1.6
      - IE (zoom, Protected mode setting )
      - Firefox/firebug startpage
  - How to deal with UI components like... fileupload, datepicker, ajaxtables,...
  - Detect when selenium isn't the good tool for the job
  - Don't be afraid to hack around selenium

Use PageObjects pattern

Page Object is a Design Pattern which has become popular in test automation for enhancing test maintenance and reducing code duplication. A page object is an object-oriented class that serves as an interface to a page of your Application Under Test. The tests then use the methods of this page object class whenever they need to interact with that page of the UI. The benefit is that if the UI changes for the page, the tests themselves don’t need to change, only the code within the page object needs to change. Subsequently all changes to support that new UI are located in one place.

The Page Object Design Pattern provides the following advantages :

  • There is a clean separation between test code and page specific code such as locators (or their use if you’re using a UI map) and layout.
  • There is  a single repository for the services or operations offered by the page rather than having these services scattered through out the tests.

For example you have a LoginPage that you can reuse in all your integration test.
if the logon has now a new option or the layout changed a bit… adapt the LoginPage… that’s it !

More on page object : page-objects-in-selenium-2-, PageObjectFactory, simple example based on google search page

Be fluent !

With return this

It makes often your tests more readable if your “void” methods return “this”.


   public class CampaignCreatePage extends AbstractPage {
       ...
    public CampaignCreatePage withCampaignName(String campaignName) {
        name.sendKeys(campaignName);
        return this;
    }

So you can chain the calls like :

    @Test
    public void shouldntSaveWithoutAnyErrors() throws Exception {
        CampaignCreatePage createPage = openCampaignCreatePage();
        createPage.hasNumberOfErrors(4);
        createPage.withCampaignName("SELENIUM").save();
        createPage.hasNumberOfErrors(3);
        createPage.withAgent("firefox").save();
        createPage.hasNumberOfErrors(2);
        createPage.withAssignee("tom").save();
        createPage.hasNumberOfErrors(1);
    }

With varargs

You can also use varargs to make the api cleaner

    public CampaignCreatePage withCampaignTargetsIds(long... targets) {
        targetsIds.sendKeys(StringUtils.join(target,","));
        return this;
        }

In the test this give us something like

    @Test
    public void shouldntSaveTargetUnknownIds() throws Exception {
        CampaignCreatePage createPage = openCampaignCreatePage();
        createPage.withCampaignName("SELENIUM").withAgent("firefox").withAssignee("tom").withProduct(0).withCampaignTargetsIds(1, 2, 3, 4);
        createPage.save().hasNumberOfErrors(1);
    }

With generics

If you have a component that don’t have access to your pageObject. For example, a generic menu where plugins can contribute links to their own pages.
you can use this trick :

    public  T clickOnMenu(String path, Class pageClassToProxy) {
        clickOnMenu(path);
        return PageFactory.initElements(getDriver(), pageClassToProxy);
    }

 

    @Test
    public void testBrodocWithoutMemberOrProspectIdentified() {
        processLogon();
        MemberIdentificationPage page = openMemberIdentificationPage();
        page = page.getMenuElement().clickOnMenu(LuceneSearchPage.URL, LuceneSearchPage.class);
        page.hasInfoMessage();
        page.withNameFilter("mestachs").search().getResults().hasResults()
 }

By reusing your model and joda

For example the CampaignSearchPage can reuse the SearchCampaignParameter

...
     public CampaignSearchPage searchFor(SearchCampaignParameter parameter) {
        clearForm();
        selectRadio("campaignTargetType", parameter.getPersonType());
        sendString(campaignName, parameter.getCampaignName());
        sendDate(creationDateFrom, parameter.getCreationDateFrom());
        sendDate(creationDateTo, parameter.getCreationDateTo());
        sendDate(campaignDateFrom, parameter.getCampaignDateFrom());
        sendDate(campaignDateTo, parameter.getCampaignDateTo());
        findCampaigns.click();
    }
...

Be robust and portable

Preferred selector order : id > name > css > xpath

To locate an element we can use

  • the element’s ID
  • the element’s name attribute
  • an XPath statement
  • by a links text
  • document object model (DOM)

In practice, you will discover

  • id and name are often the easiest and sure way.
  • xpath are often brittle. for example you have 3 tables displayed but sometimes there are no data and the table isn’t rendered, your xpath locating the second table will not always return the intented one.
  • css are the way to go in conjunction of id and name !
  • locating links in an internationalized application is sometimes hard… try to use partial href.

various selectors articles : why-jquery-in-selenium-css-locators-is-the-way-to-go, css selector demystified, jquery selectors

Avoid Thread.sleep prefer Wait or FluentWait

Instead of sleep

    public void clickOnContactType() {
        getDriver().findElement(By.id("contacttypelink")).click();
        sleep(500);
    }

Prefer this fluentWait

    public void clickOnContactType() {
        getDriver().findElement(By.id("contacttypelink")).click();
        SeleniumUtil.fluentWait(By.name("handle"), getDriver());
    }

It’s more robust, deterministic, in case of element not found… the exception will be clearer.

Another alternative is

(new WebDriverWait(driver, 30)).until(new ExpectedCondition() {
                public Boolean apply(WebDriver d) {
                    return d.getTitle().toLowerCase().startsWith("java developer");
                }

More on this http://www.thoughtworks-studios.com/twist-agile-test-automation/2.3/help/how_do_i_handle_ajax_in_selenium2.html

Use relative URLs

Avoid hardcoding hosts

getDriver().get("http://nl.wikipedia.org/wiki/Wiki");
WikiMainPage page = PageFactory.initElements(getDriver(), WikiMainPage.class);
page.search("sdfsdf");

Prefer configuration and pass relative urls like

openPartialUrl("/");

That use an abstract method


    protected void openPartialUrl(String partialurl) {
        getDriver().get(getUrlPrefix() + partialurl + "?siteLanguage=" + this.settings.getLanguage());
    }
    private static String getPrefix() {
        return StringUtils.replace(System.getProperty("selenium.website.url", HTTP_PREFIX), "@localhost@", getCanonicalHostName());
    }
    private static String getCanonicalHostName() {
        try {
            return java.net.InetAddress.getLocalHost().getCanonicalHostName();
        } catch (Exception e) {
            return "127.0.0.1";
        }
    }

It is easy then to launch these tests against another server (integration,acceptance,… or jetty in integration tests)

Don’t rely on specific Driver implementation

Don’t assume that driver will be an instance of FireFoxDriver or InternetExplorerDriver. For example when running the integration tests on your continuous build (linux) you will receive a RemoteDriver.

It’s quite easy to create a small framework around selenium using :

  • LabelledParameterized : to be able to run with different browsers IE,FF,… or with different user language fr/nl/en
  • ScreenShotWatchMan : that takes screenshot on exception and logs the html sources. (see ./target/screenshot/*.png)

Create your dataset

Avoid something like assuming that the data is always there.

CampaignConsultPage consult = openCampaignConsultPage(2132103215L);
CampaignEditPage edit = consult.goToEditPage();
consult = edit.save();
consult.hasInfoMessage();

Create a new campaign and check consult

CampaignCreatePage createPage = openCampaignCreatePage();
createPage.withCampaignName("SELENIUM" + new DateTime()).withAgent("tom").withAssignee("tom").withProduct(0);
createPage.save().hasNumberOfErrors(0);
createPage.hasInfoMessage();
Long campaignId = createPage.getCampaignId();
CampaignConsultPage consult = openCampaignConsultPage(campaignId);
CampaignEditPage edit = consult.goToEditPage();
consult = edit.save();
consult.hasInfoMessage();

Know your new tool

Keep up to date

Keep your binaries and knowledge up to date !
This official blog contains announcements and also some a lot of links to possible application of selenium
StackOverflow forums are really good to learn from other mistakes. The official Sauce Labs Blog is also really interesting for their real life experiences.

Use jre 1.6

If while starting your integration tests you encounter :

java.lang.NoSuchFieldError: HOURS
at org.openqa.selenium.remote.internal.HttpClientFactory.(HttpClientFactory.java:44)

or

java.lang.NoSuchFieldError: java/util/concurrent/TimeUnit.HOURS

Run your test with a jre 1.6

How to close Firebug startpage

FirefoxProfile profile = new FirefoxProfile();
profile.setPreference("extensions.firebug.currentVersion", "1.8.2");
driver = new FirefoxDriver(profile);

note that you may need to adapt the version.

IE not working

check

  • The browser zoom level must be set to 100% so that the native mouse events can be set to the correct coordinates.
  • On IE 7 or higher on Windows Vista or Windows 7, you must set the Protected Mode settings for each zone to be the same value. The value can be on or off, as long as it is the same for every zone. To set the Protected Mode settings, choose “Internet Options…” from the Tools menu, and click on the Security tab. For each zone, there will be a check box at the bottom of the tab labeled “Enable Protected Mode”.

Possible workaround for Protected Mode

DesiredCapabilities ieCapabilities = DesiredCapabilities.internetExplorer();
ieCapabilities.setCapability(InternetExplorerDriver.INTRODUCE_FLAKINESS_BY_IGNORING_SECURITY_DOMAINS, true);
ieCapabilities.setCapability("ensureCleanSession", true);
driver = new InternetExplorerDriver(ieCapabilities);</pre>

How to deal with ui elements like

File upload

Selenium Tips: Uploading Files in Remote WebDriver

Single and multi select

One option

public class AbstractPage {
...
   protected void selectRadio(String name, String code) {
    WebElement select = this.webDriver.findElement(By.xpath("//input[@value='" + code+ "'and @name='" + name + "' ]"));
    select.click();
   }
...

Maybe a better option is using org.openqa.selenium.support.ui.Select

    Select singleSelection = new Select(getDriver().findElement(By.id("single-selection")));
    singleSelection.selectByVisibleText("July");
    Select mulitpleSelection = new Select(getDriver().findElement(By.xpath("//select[@multiple='multiple' and @size=12]")));
    mulitpleSelection.deselectAll();
    // Select February, August and November using different functions.
    mulitpleSelection.selectByIndex(1); // February
    mulitpleSelection.selectByValue("Aug"); // Select ...
    mulitpleSelection.selectByVisibleText("November"); // Select November

DatePicker

public class CampaignSearchPage extends AbstractPage {
  ...
    sendDate(creationDateFrom, parameter.getCreationDateFrom());
  ...</pre>

sendDate is defined in AbstractPage

   protected void sendDate(WebElement e, DateMidnight dm) {
    if (dm != null) {
        sendString(e, dm.toString("dd/MM/YYYY"));
    }
   }

AjaxTableElement

If you use table elemenst with paging, sorting,… you can perhaps create a component AjaxTableElement
add in pageObject :

public class CampaignSearchPage extends AbstractPage {
          ....
         public AjaxTableElement getTableResult() {
        return new AjaxTableElement(getDriver(),"results");
    }
}

Then you can use the AjaxTableElement

page.searchFor(param);
page.getTableResult().hasResult();
page.getTableResult().clickOnResult(1);

Detect when selenium isn’t the good tool for the job

Selenium can’t deal with OS level dialogs so first avoid them as much as possible…
For eg don’t try to download a pdf through selenium and open acrobat reader.
You may be tempted to use tool like : autoit or sikuli (his java api) but you will loose portability and may be they will only offer you a false sense of quality.

Don’t be afraid to hack around selenium

A lot of people are using it but also trying new stuff like :
– collecting performance statistics.
– creating a full acceptance framework
– implementing a new webdriver

, ,

34 Comments

Rest Api Documentation

The holy grail for rest api is an auto-generated, always up-to-date, stylish documentation that promotes your site/product api. What are the tools available now ?

Inspiring documentation

Well documented

less documented… but strangely easy to use.

For Spring based application

Working in a Java shop, I’m looking for a solution at least working for spring-mvc rest services.

SpringDoclet

SpringDoclet is a Javadoc doclet that generates documentation on Spring Framwork artifacts in a project. The detection of Spring artifacts is based on the presence of Spring annotations on Java classes and methods.

SpringDoclet currently detects and documents the following types of Spring artifacts:
– Components – classes annotated with @Component, @Controller, @Repository, and @Service
– RequestMappings – classes and methods annotated with @RequestMapping

SpringDoclet writes its output in HTML format into a file named spring-summary.html. The location of the file is determined by the Javadoc “-d” option, with the same defaulting rules as the standard doclet.
sample

RESTdoclet

RESTdoclet

Benefits
Enables the creation of an enterprise REST service documentation web portal, providing a central port of call for service consumers
Enables automatic generation of documentation from underlying service source code, thus ensuring the documentation is always up to date
Features
Displays Spring-annotated service operations, types and associated Javadoc
Out of the box supports for Spring 3 RESTful services using Javadoc
Java 5/6 support. Java 7 coming soon
Customisable interactive web documentation application
Simple integration with Maven build processes
No custom annotations required – supports Spring 3 REST annotations out of the box
Further details on the RESTdoclet wiki.

wsdoc

WsDoc is a documentation generator for Spring MVC REST services. Multi modules/war and unified report.

sample

Wadl

Wadl is the wsdl of rest api… but don’t appear to gain in adoption. It’s may dedicated to wsdl nostalgic 😉
Here are some home made solution for self documenting spring based applications.
Sample1 | Sample2

More generics and polished

Swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. The overarching goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync. With Swagger, deploying managing, and using powerful APIs has never been easier.

As a specification, Swagger is language-agnostic. But since a spec without a usable implementation has limited immediate value, Wordnik has released Swagger implementations in Scala, Java, and HTML5. Client generators are currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript 3. More client support is underway.
sample | sample 2 | springmvc

I/O Docs

I/O Docs is a tool created by Mashery that is very similar to Swagger. Written in JavaScript, the source is available on github (same for swagger), which means that you can taylor it to your own needs, as well as look-and-feel.

sample

Customizing it, is also possible.

apiary

Apiary : REST API documentation. Reimagined.
It takes more than a simple HTML page to thrill your API users. The right tools take weeks of development. Weeks that apiary.io saves.

enunciate

Enunciate is an engine for dramatically enhancing your Java Web service API. (@javax.ws.rs.Path)

It’s simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features:
– Full HTML documentation of your services, scraped from your JavaDocs.
– Client-side libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API.
– Interface Definition Documents (e.g. WSDL, XML-Schema, etc.)
– …

sample

Conclusion

Solutions exists… picking the right one will be harder.
For internal use the doclet approach is perhaps enough. From my point of view swagger looks more promising (specification, multi platform implementation, easy “try it” for end-users,…). I think IODocs will bring too much ‘new’ dependencies for “the Enterprise” (node.js,redis,…).

To go further on this topic, take a look at this presentation maintainable-api-docs-and-other-rainbow-colored-unicorns or this talk

Other remarkable tools ? Don’t be afraid to submit them in the comment !

, ,

26 Comments