Overview

Robot Framework Tutorial 2016 – Keywords

No Comments

Robot Framework Tutorial 2016

Part 1: Installation
Part 2: Keywords
Part 3: Implementing Keywords in Java
Part 4: Selenium2Library as a drop-in replacement for SeleniumLibrary
Part 5: Integration with TeamCity CI-Server
Part 6: Integration with Jenkins
Part 7: File Processing

The “old” Robot Framework Tutorial.


The Robot Framework really comes with a very comprehensive User Guide. Sometimes this makes me think that additional tutorials are almost not needed. But then again I think that a blog post can be more specific in digging into one aspect of a tool than the documentation can. So here we go digging into the central testing concept of the Robot Framework and that is: Keywords.

This blog post will entirely deal with available Keywords and how to write new Keywords out of existing ones directly using Robot Framework features. For a lot of use cases this approach is already sufficient due to the huge amount of existing Test Libraries and thus Keywords. The next blog post in this series will then deal with writing new Keywords in Java (just in case you are waiting for that one). One could also use other programming languages, but for me as a Java developer this is a quite natural choice. Writing new Keywords this way is needed if you have to test specific technologies that are not yet covered by the existing Test Libraries.

A first Example

Let’s jump into the cold water right away with the smallest possible example I can think of for a Test written with the Robot Framework. (Yes, actually it is not even testing anything, but that is nitpicking.)

*** Settings ***

*** Test Cases ***
Test Robot Framework Logging
  Log   "Test Logging"

The Settings section is empty because we are not importing any external Test Libraries. I could have omitted that section of course, but somehow for me it belongs to a Test Case File even if it is empty.

We defined one testcase below the Test Cases section. That one is executing one Keyword “Log” and we are passing one parameter to this Keyword, namely the String “Test Logging”. Easy as that, but still there are a few stumbling blocks. There must be at least two spaces to separate arguments from Keywords and arguments from each other. Furthermore there must be always an indention of two spaces in the beginning of each line below a testcase. Both should be visible from the example, but it is still easy to miss these things.

The test can be executed with pybot or Java – depending on the type of your installation – directly from the directory where the Test Case File is stored.

pybot --outputdir ./report sample-0-trivial.txt
java -jar /usr/local/opt/robotframework/robotframework-2.9.2.jar --outputdir ./report sample-0-trivial.txt

There are lots of command line options possible. Here we are using “–outputdir” to define the place where the resulting Log- and Report-Files are stored. Just take a look at the Report-File by opening it in a Browser. We will still have a closer look on the Report- and Log-File at the end of this blog post.

All examples shown in this blog post can be found from GitHub here. This way they are hopefully easier to access than through this blog post and there are more examples than shown in this blog post. Furthermore I am planning to enhance that site with more examples in the future.

The Robot Framework is supporting different formats for writing Test Case Files. The format used throughout this blog post (and blog series) is the Plain Text Format. I simply like it the most as it is very easy to read and understand once you have been getting used to the thing with the “additional whitespaces” mentioned above. You could also use HTML, which allows you to have a nice kind of “presentation view” on your test cases. But it is simply more code to write and it is more likely to run into merge conflicts when putting the files under version control (which should always be the case). There is also the possibility to use BDD-style test case descriptions. Well, that could probably be a blog post of its own, but for the time being I would like to omit that. It only makes things more complicated while we want to learn the basic concepts here.

Keywords – A Programming Language

Working with Keywords is like learning a new programming language. So you basically need to understand the syntax of it, which is luckily not too complicated. And hopefully this will no longer be a problem after reading through this blog post and the examples. And of course you need to know what a new language offers. For the Robot Framework this means how to implement certain structures like doing loops or conditional execution of keywords. And it means knowing which Test Libraries and Keywords are available.

Thus it is definitely worth taking a look at the list of available Test Libraries on the Robot Framework homepage to get an idea what is already available. Please note that the Standard Libraries are included in each Robot Framework installation right away (compare previous blog post on installation), while the External Libraries require additional installation.

Build-In, Standard and External Test Libraries. Well, one could get confused by this, but no worries. The Build-In Library is part of every Robot Framework installation and Keywords from that Library can be used without even having to import that Library in the Settings section. Standard Libraries are part of every Robot Framework installation, but to use Keywords from them they must be “imported” in the Settings section. External Libraries must be installed separately. They come with own installation instructions and they must be imported the same way as the Standard Libraries.

Ok, the next example:

*** Settings ***
Library     String


*** Test Cases ***
Test Robot Framework Logging
  Log   Test Logging
  Log Many  First Entry   Second Entry
  Log To Console  Display to console while Robot is running

Test For Loop
    : FOR    ${INDEX}    IN RANGE    1    3
    \    Log    ${INDEX}
    \    ${RANDOM_STRING}=    Generate Random String    ${INDEX}
    \    Log    ${RANDOM_STRING}

I like this example as it is still pretty short, but it shows a few of the features that are available when working with Keywords at one glance. First of all we extended the first test case by adding more rows to it calling different Keywords. That is basically how we implement Tests – even though here we are only logging – by executing any amount of Keywords (with corresponding parameters) below one test case definition. The example also shows how to define two different test cases in one Test Case File. The second test case shows how to implement a loop and how to assign results from executing a Keyword to a variable. As the Keyword “Generate Random String” comes from the String Library we need to import that one under the Settings section. As it is a Standard Library it comes with the Robot Framework installation.

Writing own Keywords

So far we have seen how to use existing Keywords. Now it is time to write the first new Keyword.

*** Settings ***

*** Test Cases ***
Test Robot Framework Logging
    Log    Test Logging

Test My Robot Framework Logging
    My Logging    My Message    WARN

*** Keywords ***
My Logging
    [Arguments]    ${msg}    ${level}
    Log    ${msg}    ${level}

Own Keywords in Test Case Files are written below the Keywords section. The syntax is pretty much the same as when writing test cases. Major difference ist that you can pass parameters in to your own Keywords.

A common example for an own Keyword is for example a Login that would get a username and password (maybe also a URL) and then hides all the technical details (technical Keywords) needed to perform the Login.

Organizing Keywords – Resource Files

Of course you do not want to pollute your Test Case Files with your Keyword definitions. Obviously that makes those also less reusable. The solution to this is defining new Keywords in so-called Resource Files. Those can then be included similar to the way Test Libraries are included.

*** Keywords ***
My Logging
    [Arguments]    @{arg}
    Log Many    @{arg}

Example “Resource File”:

*** Settings ***
Resource        resource-2.txt

*** Test Cases ***
Test Robot Framework Logging
    Log    "Test Logging"

Test My Logging
    My Logging   "Test My Logging 1"   "Test My Logging 2"

Example “Test Case File”:

Well, not too much to add here as this is pretty straightforward. Beside using Resource Files the example also shows how to use arguments from type array for own Keywords. In this example the Test Case File and the Resource File must be located in the same directory. Of course it is also possible to store Resource Files to sub-directories and then use relative path-information when including the Resource File.

Note: Never use absolute paths to include Resource Files as this path might differ for different team members and the test environment. Always use only relative path definitions here.

Beyond Keywords

Basically you should have now all the basics to start writing own Keywords, Resource Files and Test Case Files. Still there are a lot more possibilities beyond those basics. Some of them are briefly depicted in the following.

Setup and Teardown

This feature allows to execute certain Keywords to prepare tests or clean up after testing. The following shows how to define setup/teardown for a complete Test Case File.

*** Settings ***
Suite Setup       Setup Actions
Suite Teardown    Teardown Actions

*** Test Cases ***
Test Robot Framework Logging
    Log    Test Logging

*** Keywords ***
Setup Actions
    Log    Setup Actions done here

Teardown Actions
    Log    Teardown Actions done here

There are more possibilities to also have setup/teardown defined to be running for each test case.

Tagging

Tagging is not really related to Keywords, but it is a nice way to get a better grip on what you are testing from looking at the report.

*** Settings ***

*** Test Cases ***
Test Robot Framework Logging
    [Tags]    sample   logging
    Log    "Test Logging"

The tags are summarized in the report and thus you can check how many test cases are related to certain features of the system under test. But please note that his requires some discipline in applying the tags.

This leads to the final part of this blog post that is dealing with the Report- and Log-Files.

Report- and Log-Files

The reporting- and logging of the Robot Framework is definitely very strong.

reporting

As can be seen on the above screenshot there are different statistics on the results. You can see how many test cases have a certain tag. Furthermore you see the statistics by Test Suite, which here means Test Case File. By clicking on “Sample-0-Tagging” you get a detailed list of the results from that Test Case File.

reporting-1

The great thing is that you can now dig deeper into the results by clicking on an individual test case. This opens a new page with the log. Here you see the result of each of the executed Keywords that are forming a test case. This way if a test would fail you can exactly see which Keyword has failed and also additional logging information could be added here (we had a lot of logging examples already :-)).

logging

Conclusion

With the concepts of Keywords the Robot Framework offers a rich ecosystem for writing test functionality using existing Test Libraries. This can and should be used to decouple technical concepts from functional ones. Using the domain vocabulary in the test cases makes them more readable and understandable while hiding the technical details in own Keywords and Resource Files.

This blog post cannot show everything that is possible and available. Best advice is (again) to take a look at the existing Test Libraries. There are also more examples in the already mentioned tutorial on GitHub.

Next week we will take a look at writing new Keywords in Java and there is still a lot more to explore around the Robot Framework :-).

Comment

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