Getting Started

md42 edited this page Apr 20, 2013 · 8 revisions

Getting Started

JavaLibCore is a common core for all Robot Framework test libraries written in Java.

The main advantages are
  • easily extensible and dynamic - just add keywords to the class path
  • core takes care of communicating with Robot Framework - just implement keywords
  • common functionality readily available (e.g. argument count checking for keywords)

Note Version 1.0 dropped support for Spring Library and Composite Library.

Motivation

Robot Framework supports two kinds of Java libraries. The simpler way is to have a single library class, which has keywords as methods. This is a very easy way to get started, but as the amount of keywords grows it will soon lead to bad design and hard-to-maintain code, even if you split the keywords in to several classes.

The other, better way of doing this is to have a library that implements methods String[] getKeywordNames() and Object runKeyword(String keywordName, Object[] arguments). This gives us more liberty to decide how we want to run and implement our keywords. Also you should remember to implement method String[] getKeywordDocumentation(String keywordName) in the library and specifically equals __intro__, which will be used to generate API introduction chapter.

JavaLibCore provides an implementation of the latter library model. You can add keywords either by simply implementing a Keyword -interface and having your classes in the classpath when running Robot, or by tagging methods with @RobotKeyword annotations.

Provided "core" libraries

These libraries do not provide any keywords. They are merely common implementations of libraries so you don't need to your own. You only need to write keyword implementations. How the libraries find the keywords is explained below.

There are two different ways of creating keywords with Javalib Core:

  • ClassPathLibrary: Searches for keywords in the classpath. The class name is mapped to a keyword name. To create a keyword with the name Do My Specific Task, you simply implement a keyword class called DoMySpecificTask and add it to the class path.
  • AnnotationLibrary: Keywords can be created using annotations. Annotating methods with @RobotKeyword will make them registered as keywords. The class that contains the keyword-methods has to be tagged with @RobotKeywords annotation.

Keyword and Config File Pattern

JavaLibCore libraries requires you to explicitly set the pattern that specifies under which packages the keywords should be searched for. If javalib-core just scanned through all the classes in the classpath a keyword naming conflict would occur when using two or more javalib-core libraries in the same test suite.

Note When the keywords are contained in jar files the jars need to include the directory entries, otherwise javalib-core is unable to find the classes. When creating keyword jar with Eclipse be certain to check the checkbox "Add directory entries".

Instructions

Keyword pattern must begin with the the first part of a Java package. For example **/**.class is not allowed. It must be something like com/**/**.class. It is a good idea to make the pattern as restrictive as possible in order to prevent keyword name collisions. That is why pattern above is not recommended as it makes javalib-core to scour through all the classes which package starts with com. If your keywords are all in the same package it is preferable to use keyword pattern that doesn't make javalib-core to look elsewhere, e.g. if all your keywords reside under com.acme.myproject.keyword you should use com/acme/myproject/keyword/**.class pattern.

Wrapper Libraries

Keyword pattern makes my tests less readable, what can I do?

It is true that this is easier to understand:

Setting Value
Library MySpecialLibrary

than this:

Setting Value Value
Library org.robotframework.javalib.library.ClassPathLibrary com/acme/**/keyword/**/*.class

To resolve this problem you can create an alias or a wrapper library that hides the ugly keyword pattern. For example you could create the following class in the default package:

import org.robotframework.javalib.library.ClassPathLibrary;

public class MySpecialLibrary extends ClassPathLibrary {
    public MySpecialLibrary () {
        super("com/acme/mycomponent/keyword/**/*.class");
    }
}