The Listener Interface of the Robot Framework

19.6.2012 | 7 minutes of reading time

Having an eye on the Robot’s nuts & bolts…

Sooner or later there is always this single question – the question regarding debugging Robot. Whether during an introduction or in a training, suddenly it’s always “How do I debug this?”

Well, you might say that one should not (need to) debug any automated test suite at all as your very detailed tests will always tell you where the problem is. But that is an illusion. We all know the tests that fail just because an unexpected modal pop up prevents any focus switch or because a required UI element appears too late. That’s the point when you just want to peek what’s going on there.

And this is possible with the Robot Framework, too. The magic words are Listener Interface.

The Robot Framework provides an interface to integrate listener implemented as classes or modules. Listeners needs to be registered during the start up of the framework and messages will be sent to all listener covering important events. Listeners are called synchronously and block the execution of the test suite.

Listeners can be implemented in Java or Python. The Robot Userguide includes an overview of all events respectively all valid hooks. Lucky enough you just have to implement the methods / functions you are actually interested in.

Implemented listeners need to be in the Robot Framework’s path during runtime, either by putting them in the module search path or by using paths (relative, absolute) upon registration.

To register a listener you have to use the --listener cómmand line option when starting the Robot Framework. This is also the place to put arguments as we will see later.

A very basic listener

Let’s start with an example: We would like the test run to be interupted right before a new test case is started. The test case execution shall continue after clicking a button in a dialog.

First our very complex and realistic test suite:

File name: SimpleTest.txt

1*** Test Case ***
2Simple Test Case
3  [Documentation]  A simple test case as listener demo
4  ${test_var}=  Set Variable  OK
5  Should Be Equal  ${test_var}  OK

Now we need a listener that opens a dialog and waits for a button click when a new test case is about to be executed. Therefore we create a Python module that implements the start_test function. start_test has two parameters – the name of the test case as a string and the test case’s attributes as a dictionary. What attributes are passed over in the dictionary is documented in the userguide.

File name: PleaseWait.py

1import tkMessageBox
2from Tkinter import Tk
7def start_test(name, attributes):
8    Tk().withdraw() # Remove root window
9    tkMessageBox.showinfo("Please click 'OK'...",
10                          "Test Case Name: " + name)

Now we can start Robot with the listener included and have a look at the result.

1pybot --listener PleaseWait SimpleTest.txt

As the result the following dialog should be shown:

Listener with arguments

This approach falls short when you have more than one test case in your test suite. Nobody wants to click “Ok” 20 times just to get to the desired test case. In this situation listeners configured with arguments come in handy.

When using listeners with arguments it is necessary to switch from module to class when implementing in Python. Arguments will be passed to the class’s constructor. Thus the listener class must implement an __init__ method that accepts all expected parameters in the correct order. In our situation we just need a single parameter, the test case name.

Please note: As arguments are optional the parameters of the __init__ method should always have sensible default values.

File name: PleaseWaitWithArg.py

1import tkMessageBox
2from Tkinter import Tk
5class PleaseWaitWithArg():
8    def __init__(self, test_name = ''):
9        self.test_name = test_name
11    def start_test(self, name, attributes):
12        if (name == self.test_name) or ('' == self.test_name):
13            Tk().withdraw() # Remove root window
14            tkMessageBox.showinfo("Please click 'OK'...",
15                                  "About to start test '%s'" % name)

This listener waits before the given test case is started (respectively any test case if the argument is omitted).

To check the functionality we have to add at least one more test case to our test suite…

File name: TwoTests.txt

1*** Test Cases ***
2Simple Test Case
3  [Documentation]  A simple test case as listener demo
4  ${test_var}=  Set Variable  OK
5  Should Be Equal  ${test_var}  OK
7Additional Test
8  [Documentation]  Don't be evil...
9  Log  Don't panic!

Arguments are passed to the listener upon registration. They are separated from the listener’s name by colons. Each additional argument is appended to the other by an additional colon.

1pybot --listener PleaseWaitWithArg:"Simple Test Case" TwoTests.txt

If everything works as expected the test execution is interupted before the first test case but not before the second test case.

Please note: double quotes are used just to mask the spaces in the test case name. Generally there is no need to enclose arguments in quotes.

You should leave out the argument and see what happens when using the listener without it!

Showing variables via listeners

But listeners can do more. It is possible to use other test libraries within a listener. By using Robot’s “BuiltIn” library you can access a variable’s current value.

File name: ShowVariable.py

1import tkMessageBox
2from Tkinter import Tk
3from robot.libraries.BuiltIn import BuiltIn
8def end_test(name, attributes):
9    Tk().withdraw() # Remove root window
10    tkMessageBox.showinfo("Please click 'OK'...",
11                          "test_var = '%s'" % BuiltIn().get_variables()['${test_var}'])

When executing this…

1pybot --listener ShowVariable SimpleTest.txt

… the following result should be shown:

And how to continue from here?

These examples should show you what the listeners of the Robot Framework can do. For sure someone thought just four paragraphs ago “Hey, it should be pretty easy to build a real debugger with those!” Before everbody starts hacking on the console and creates a new repository on GitHub: Someone already did so – have a look here . I will write a dedicated blog entry about how to use this remote debugger for Robot later.

Remarks on “API version”

May be you already noticed the variable ROBOT_LISTENER_API_VERSION in my examples. This variable and it’s value define what version of the Listener API will actually be used when calling the listener. Release 2.1 of the Robot Framework introduced heavy changes in the API. To ensure compatibility of existing listeners with the new release the variable ROBOT_LISTENER_API_VERSION was created. When it exists and equals 2 the new API version is used. When the variable is missing the old API version will be used as the default behaviour. There is no reason to use the old API version together with new code (you would have to search the repository for an old documentation first…) but the default behaviour might puzzle you – especially if Python is not your native language or when “writing” some code by adopting Copy & Paste…

Forgetting the API version or putting it in the wrong position (outside the class definition) will result in the listener being called with the old API version creating quite surprising error messages. Thus when stumbling over messages like

[ ERROR ] Calling listener method 'start_test' of listener 'PleaseWaitWithArg' failed: TypeError: start_test() takes exactly 3 arguments (4 given)

just check whether ROBOT_LISTENER_API_VERSION exists, has the right value of 2 and is well placed. In this particular case I moved the variable in front of class PleaseWaitWithArg(): and therefore outside the class definition – a typical “Copy & Paste” error.

Remarks on “Java”

Right a the beginning I wrote that listeners can be implemented in Java, too. But how does that look like exactly and what do you have to keep in mind?

First the source code of all three listeners implemented in Java…

File name: PleaseWaitJ.java

1import java.util.Map;
2import javax.swing.JOptionPane;
4public class PleaseWaitJ {
5    public static final int ROBOT_LISTENER_API_VERSION = 2;
7    public void startTest(String name, Map attributes) {
8        JOptionPane.showMessageDialog(null, "Test name: " + name);
9    }

File name: PleaseWaitWithArgJ.java

1import java.util.Map;
2import javax.swing.JOptionPane;
4public class PleaseWaitWithArgJ {
5    public static final int ROBOT_LISTENER_API_VERSION = 2;
7    private String testName;
9    // Empty constructor in case argument is omitted...
10    public PleaseWaitWithArgJ() {
11        this.testName = "";
12    }
14    // Constructor taking the expected argument...
15    public PleaseWaitWithArgJ(String testName) {
16        this.testName = testName;
17    }
19    public void startTest(String name, Map attributes) {
20        if (name.equals(testName) || ("".equals(testName)))
21            JOptionPane.showMessageDialog(null, "Test name: " + name);
22    }

File name: ShowVariableJ.java

1import java.util.Map;
2import javax.swing.JOptionPane;
4import javax.script.ScriptEngine;
5import javax.script.ScriptEngineManager;
6import javax.script.ScriptException;
8public class ShowVariableJ {
9    public static final int ROBOT_LISTENER_API_VERSION = 2;
11    public void endTest(String name, Map attributes) throws ScriptException {
12        ScriptEngine engine = new ScriptEngineManager().getEngineByName("python");
13        engine.eval("from robot.libraries.BuiltIn import BuiltIn");
14        engine.eval("v = BuiltIn().get_variables()['${test_var}']");
15        Object testVar = engine.get("v");
16        JOptionPane.showMessageDialog(null, "test_var = " + testVar);
17    }

First you have to say: It really works! But compared to the functional scope of these examples that handling of Java based listeners is rather tricky.

The following points are worth to be mentioned:

  • For sure Robot must be started with Jython (jybot) in these cases.
  • File extensions are ignored during registration of listeners. Thus when mixing Python and Java listeners you might use module / class names twice without noticing. Robot will load the Python code.
  • In contrast to Python code you must compile the Java code before starting Robot.
  • Arguments are optional! Thus you should implement constructors with “missing” arguments as well (see second example).
  • The access to Python based libraries is rather awkward (see third example).

share post




More articles in this subject area\n

Discover exciting further topics and let the codecentric world inspire you.


Gemeinsam bessere Projekte umsetzen

Wir helfen Deinem Unternehmen

Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.

Hilf uns, noch besser zu werden.

Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.