AnnotationLibrary

AnnotationLibrary

Introduction

Annotating methods with @RobotKeyword will make them registered as keywords. The class that contains the keyword-methods has to be tagged with @RobotKeywords annotation. This is perhaps the simplest and the most flexible way of creating keywords, the downside is that you need java 1.5 or higher to use it. For the moment this is also only java library type that supports adding documentation to keywords that robot tools can read.

A keyword implementation has to fill the following requirements:

• it's a method that is annotated with @RobotKeyword annotation.
• the method is contained in java class that has been annotated with @RobotKeywords annotation.
• the method is contained in java class which name matches the given ant style pattern, e.g.: com/acme/**/keyword/**/*.class
• the class has a default constructor
• the class is public and non-abstract

If you want to use keyword overloading, mark the overloaded version with @RobotKeywordOverload annotation. One version must have the main keyword annotation @RobotKeyword and not @RobotKeywordOverload. Overloaded keywords must be located at the same class.

Usage

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

Or you can create a wrapper library:

public class MyLibrary extends AnnotationLibrary {
  public MyLibrary() {
    super("com/acme/**/keyword/**/*.class");
  }
}

And take it into use like this:

Setting	Value
Library	MyLibrary

With wrapper libraries you can also add multiple keyword patterns, eg:

public class MyLibrary extends AnnotationLibrary {
    List<String> keywordPatterns = new ArrayList<String>() {{
      add("com/acme/**/keyword/**/*.class");
      add("org/some/other/place/**.class");
        }};
    public MyLibrary() {
        super(keywordPatterns); // keywords are looked in all the places speficied by the different patterns
    }
}

You can also provide documentation for the library:

public class MyLibrary extends AnnotationLibrary {
    @Override
    public String getKeywordDocumentation(String keywordName) {
        if (keywordName.equals("__intro__"))
            return "This is the general library documentation.";
        return super.getKeywordDocumentation(keywordName);
    }
}

Autowired Annotation

JavalibCore 1.2 provides a new way for the Annotation class instance and the Keywords class instances to find each other. The annotation @Autowired in the fields of keywords classes or fields of annotation library class is automatically populated by the library by instance of matching class when the library instance is created.

Example of @Autowired annotation:

/**
 * If the library includes keywords in a class of type MyKeywordClass, the created instance is
 * injected automatically to this field.
 **/
@Autowired
public MyKeywordsClass keywords;

/**
 * Several keywords classes can be autowired, just as well as the annotation library instance itself.
 **/
@Autowired
public MyOtherKeywordsClass otherKeywords;

Documenting keywords

Keyword documentation

AnnotationLibrary lets the keyword implementer to include keyword documentation into the code. This information is used by tools such as Robot IDE and it is also visible in the log files Robot generates. It can also be used to generate library reference documentation. The first line of the documentation is used as a short description of what the keyword does.

Argument names

Keyword argument names used in documentation generation can be added by using a special annotation @ArgumentNames. Robot framework also uses keyword names are to check if the keyword is invoked with a correct number of arguments and makes the test fail if incorrect number of arguments is provided. If the argument of the keyword is of type String[] the keyword accepts from zero to infinity arguments. This should be indicated to Robot framework by inserting '*' in front of the argument name. In overloaded cases optional argument must be marked by inserting '=' at the end of the argument name.

Keyword examples

@RobotKeyword("Launches application with the given arguments.\n\n"
    + "Example:\n"
    + "| Launch Application | _com.acme.myapplication.MyApp_ | _--data-file_ | _C:\\data.txt_ |\n")
@ArgumentNames({"className", "*args"})
public void launchApplication(String className, String[] args) throws Exception {
    Class<?> clss = Class.forName(className);
    Method mainMethod = clss.getMethod("main", String[].class);
    mainMethod.invoke(null, new Object[] { args });
}

@RobotKeyword("Overloaded")
@ArgumentNames({"argument1", "argument2="})
public void overloadedKeyword(String argument1, String argument2) {
    System.out.println("Arg1 :"+argument1+" arg2:"+argument2);
}

@RobotKeywordOverload
public void overloadedKeyword(String argument1) {
    overloadedKeyword(argument1, "hello");
}