Given/When/Then And Example Tables Using the Robot Framework


When doing ATDD (Acceptance Test Driven Development) or BDD (Behaviour Driven Development), the following grammar is widely spread to formulate pre- and postconditions of a test:

  1. Given: The static preconditions
  2. When: The behaviour under test (or that, which should be specified)
  3. Then: The expected results of the behaviour under the given preconditions

In this context executable specifications are a hot topic, but it is still a long way to go, isn’t it?

The goal is to be able to describe a behaviour in such a way, that it is specification and test at the same time. This removes the ever-existing divergence between specifications and what the system is actually doing.

Next to the nearly natural-language like test description, the exact behaviour is only understandable with additional examples. These often differ only in details, which makes the tabular format the recommended one, because there differences can be easily spotted. The combination of the given/when/then-structure and the examples table looks very promising at the moment, based on discussions in the community. It contains all technical details to automate the acceptance test, is compact enough to stay clear from distracting noise and last but not least is understandable to the business people, so that it is suited perfectly for discussing. Maybe it can be even created by the whole team, together with the business analysts, in a so called “specification workshop” (read: “Bridging the Communication Gap”, by Gojko Adzic).

This structure is currently supported by FITNesse as well as Cucumber, so where does the robot framework stand?

With the most recent version of the Robot Framework (2.1.2), there are two improvements, which are key to executable specifications:

  • “Given”, “When”, “Then” and “And” are ignored at the beginning of user keywords
  • Parameters can be embedded into user keywords

With they you can create executable specifications perfectly. Here’s an example:

*** Settings ***
Resource         ${RESOURCES}/BDD.txt
*** Keyword ***
    [Arguments]  ${periodClosed}  ${periodOpenAndModified}  ${importDay}  ${oldManagerValidUntil}  ${newManagerValidFrom}
    Given initialized criteria for bonus commercial
    And a branch B with branch manager M_OLD and employee E1
    And evaluation for E1 for period ${periodClosed} which is closed
    And evaluation for E1 for period ${periodOpenAndModified} which is open and modified
    When M_NEW becomes new manager of branch B
    And import service is called on ${importDay}
    Then the new branch manager of branch B is M_NEW valid from ${newManagerValidFrom}
    And branch manager M_OLD manages employee E until ${oldManagerValidUntil}
    And branch manager M_NEW manages employee E from ${newManagerValidFrom}
    And Evaluations for E1 still have the same content
| *Test Case* | | *Closed Period*        | *Open Period*          | *Run Import On* | *Old Manager Stops* | *New Manager Starts* |
| 1 | Example   | 1.11.2009 - 30.11.2009 | 1.12.2009 - 31.12.2009 | 11.11.2009      | 30.11.2009          |  1.12.2009
| 2 | Example   | 1.11.2009 - 30.11.2009 | 1.12.2009 - 31.12.2009 |  1.11.2009      | 31.10.2009          |  1.11.2009
| 3 | Example   | 1.11.2009 - 30.11.2009 | 1.12.2009 - 31.12.2009 |  1.12.2009      | 30.11.2009          |  1.12.2009

There you go. A very comapct and clear executable specification. Hard to believe that it is actually executable:

  • This is a Robot Test Suite, containing one user keyword “Example” and three Test Cases “”1”, “2” and “3”
  • While the test cases use the “data-driven-style“, the user keyword is using the new “behaviour-driven-style
  • Because of the plain text mode, the need for an external editor is vanishing. Quite the opposite, RIDE (Robot IDE) has the habit to reformat the Test Suite and puts the user keyword under the test cases, which is desireable normally, but now destroys the reading and flow through the document.
  • Some parameters in the user keywords are variable, like ${importDay}, while others are fix for this test case, like the branch name B. It is essential to keep the examples reduced to the relevant data, to keep it clear and understandable.
  • The user keyword “Example” is defined in every Test Suite. Since robot is giving local keywords precedence over user keywords from other sources, this is no problem. Quite the opposite, the layout of the examples table can be kept consistent over all suites.
  • The examples table uses the pipe symbol “|” for the layout. This makes it possible to give the columns meaningful names; but the column titles have no effect on how the parameters are passed, only their order is important and has to match the parameters in the row “[Arguments]”
  • The concrete test cases are just numbered, improving the compactness of the table
  • Test Setup and Teardown have to be somewhot hidden in the first user keyword (here: “initialized criteria for bonus commercial”). On the other hand, it is none of the business’ business how the system get’s into a defined and clear state.
  • The executable specifications can be grouped in a directory structure to be mapped to user stories.

Now can these natural language sentences be automated? This is highlighted with the first postcondition. The resource file BDD.txt contains all user keywords, which make this executable specification … executable: :

*** Settings ***
Library          de.codecentric.fourtexx.robot.ModelKeyword
*** Keywords ***
the new branch manager of branch ${branch} is ${manager} valid from ${newManagerValidFrom}
	assert branch manager valid from  ${branch}  ${manager}  ${newManagerValidFrom}

Note that not only the date is parametrised, but also the branch name and manager. In this example the values B, M_NEW and (depending on the test case) 1.12.2009 or 1.11.2009 will be passed. The defined user keyword is barely doing more than forewording to a user keyword, implemented in Java. There you can do what a keyword has to do, in order to assert the required business aspects:

public void assertBranchManagerValidFrom(String branch, String manager, String validFrom) throws Exception  {
  // ...

Conclusion: With the new possibilities of Robot Framework 2.1.2, it is at least en par with the other contestants in this race. The discovered way to have executable specifications with an appended table for examples in plain text seems to be ideal to make specification, example and test collapse to a single artefact.


  • lucas

    how to deal with a multi line parameter?

    • Andreas Ebbert-Karroum


      no idea, I never had the need to do so. First idea would be to have a descriptive name for the parameter, and then hide the details in the keywords.


      • Steve

        Andreas, thank you for this BDD example, its been very helpful to our team here.

        I’m not certain what you meant by this reply, could you elaborate? We’d really like to express JSON as multiline, for example:

        Then there should be JSON


  • deeksha

    19. December 2011 von deeksha

    Hello. I am a student and I just started off with robot framework even I dont understand much yet. My guide has asked me complete the following task. Could you please help me with it.

    You should make a python program with the following spec.

    – full python, no use of python library except the one in the official python installation and Robotframework

    – a main program (M1) start a thread T2 and then start a loop where it reads messages from T2

    – the thread T2 start robotframework, to execute a robotframework test.

    The test is a small sequence

    print xx


    print xy


    print xz


    Each pause must generate an exchange between T2 and M1. The exchange is T2 send a message (with Queue python module) to M1. In M1 the reading message loop, prints a text, and send a message back to T2.

    After having send a message to M1, T2 was waiting from the message back (on another Queue). When it gets the message, that is the end of the pause instruction implementation

    The pause instruction is implemented in python

  • Brian Rock

    28. February 2012 von Brian Rock

    Could you provide some sample code on how your connecting RF with the keywords written in Java? We have an entire automation framework (Java + Selenium WebDriver) written using a Page Object Model framework and I would like to drive it with Ride. However, I am not finding any good examples how to do connect the two.

    Any help would be appreciated.


Your email address will not be published. Required fields are marked *