Robot Framework With Docker in less than 10 minutes

It’s been quite some time since I started using robot framework. For all of you developers, engineers and testers, you know how exciting it feels to start something new. To take a pick under the blanket and throw yourself in deep waters. But you also know that sometimes taking that pick it’s costly. Costly in time, frustration, failure to understand the tools, epic configuration journeys leading to nowhere else, than you chasing your own tail. So, I decided to write this small story to help you dive in faster and safer. I hope. Let’s start.

The tools you are going to need is Docker, Git and an editor of your choice. I prefer Visual Studio Code that comes with a nice plugin you can install for Robot syntax support. Have Docker and Git installed and make sure you have an editor of your choice ready to be used.

The first step requires you to get your hands dirty. If you don’t have an IT background, the next step will make you feel like Neo or the Kevin Mitnick. Well enjoy that moment. So, open a terminal (linux or MacOS) or the git shell on windows and execute the following commands

docker pull ypasmk/robot-framework
git clone git@github.com:ypasmk/robot-framework-docker.git

This will take a while, especially the first command. The first one will download the docker image, that contains inside all the tools that you need in order to run your test cases. For a list of all the tools take a look here.

Using the shell go to the newly created directory and run the tests

cd robot-framework-docker && ./run_tests.sh

That’s it! You just executed your robot framework tests inside docker. To see what happened, have a look at the reports folder and try to open the reports.html file in a browser. Magic!!!

Let’s do more

Now that we have the image and the sample project structure, we can start building our test cases. Just to keep your motivation and excitement level high, we will create two test cases. One will be against amazon front-end using the selenium library. The other will be against Github rest api using the HttpLibrary.

Assuming that most of you have an IT background or at least have experience on writing manual test cases and execute them, I’m confident you will find it interesting.

Make sure that my present exists in amazon Test Case

So my birthday is coming up pretty soon and I’m hoping that I’ll manage to get myself a present. The plan is to buy the apple smart keyboard for Ipad pro. Let’s see if I can do it with Robot (hoping that it will pay the bill as well)

Before we go and start writing our test case, I would like to walk you through the Gherkin Style. We are using Gherkin style instead of using a procedural kind of way to execute our tests. Gherkin style provides a natural way of describing a test case. It has three sections. The Pre-condition section that is considered as Given, the execution of the test which is the When and the expectation which is the Then. Imagining that our test case is suppose to test whether or not this apple keyboard is available in Amazon, we could have this described as follows

Given user is in amazon web page
When user searches for "Apple iPad Pro 10.5 Smart Keyboard German"
Then there are results containing the item
And the user can add the item to the basket
And the user can proceed with the Checkout

I hope that you all agree that the above description doesn’t look that is coming from a testing tool, rather from a documentation describing all the test cases that a tester should go through asserting the expectations. Well, in Robot this is what we are going to use as well. The above text.

In Visual Studio Code open the folder containing the content that you downloaded from git. It should look similar to the screenshot below.

Now, this project expects that the tests will be executed in the docker image that we’ve downloaded in the beginning of this story. So a quick tour on the structure and the logic is necessary. The script that you will need to execute to run all your test cases is the

run_tests.sh

What it will do, it will map some local folders to the docker’s container filesystem and start the container. This way you don’t have to interact with the internals of the container at all. The container is configured to run a script located under the /scripts directory. To clear the landscape, all that will happen inside the container is the execution of the following command.

robot --console verbose --outputdir /reports /suites

This will start the robot by defining the /reports folder as the output folder for the reports and any other output that robot will generate. And it will then go iteratively through the /suites folder and execute all the test cases.

Since this project comes with two test cases, please free to execute it just to see what will happen and what files you are going to get afterwards in the /reports folder. Just run

./run_tests.sh

If the command is not executable just run the command below to fix the issue and retry.

chmod +x run_tests.sh && chmod +x ./scripts/run_suite.sh

If everything goes well, you should see something like this in your console.

Lets create our test case now. In the suites folder create a new file and name it amazon.robot

The content of this file should be identical to the content below. Make sure that tab indentations are kept.

*** Settings ***
Library     Selenium2Library
Library     XvfbRobot
Suite Setup     Start Virtual Display    1920    1080
Force Tags      MediumStory
*** Test Cases ***
Check that presents is available in Amazon
    Given user is in amazon web page
    When user searches for "Apple iPad Pro 10.5 Smart Keyboard German"
    Then there are results containing the item
    And the user can add the item to the basket
    And the user can proceed with the Checkout
*** Keywords ***
user is in amazon web page
    Open Chrome Browser
    Go To       https://www.amazon.de
user searches for "${present_name}"
    Input Text      twotabsearchtextbox     ${present_name}
    Press Key       twotabsearchtextbox     \\13
there are results containing the item
    Wait Until Page Contains     3 Ergebnisse für "Apple iPad Pro 10.5 Smart Keyboard German"   timeout=10
the user can add the item to the basket
    Click Link      Apple iPad Pro 10.5 Smart Keyboard German
    Click Link      In den Einkaufswagen
the user can proceed with the Checkout
    Click Element      hlb-ptc-btn-native
    Capture Page Screenshot
Open Chrome Browser
    ${options}  Evaluate sys.modules['selenium.webdriver'].ChromeOptions()  sys,  selenium.webdriver
    Call Method  ${options}  add_argument  --no-sandbox
    ${prefs}    Create Dictionary    download.default_directory=/tmp
    Call Method    ${options}    add_experimental_option    prefs     ${prefs}
    Create Webdriver    Chrome    chrome_options=${options}

Now you can modify the run_suite.sh script to execute only that test case by adding the -i switch like this

CMD="robot --console verbose -i MediumStory --outputdir /reports /suites "

This will make sure that only test cases that are marked with the tag MediumStory will be executed. If everything goes well than you will see that some html files are generated in the /reports folder and also a screenshot.

Congratulations. You just created and run your first UI acceptance test with Robot Framework. Feel free to play with the test case and see what else is possible. Also, if you want to complete the order, I can provide you my address :)

To get more information about the selenium keywords and selectors please visit the documentation.

A brief overview of what we did. We created a test case description using the Gherkin style. This provides a rock solid guideline on how to create your domain dictionary using Robot. Those keywords that we created, can be re-used. The implementation of those keywords are using lower level keywords that are coming from the robot framework libraries.

Fetch my profile from Github

For the second test case we are going to use the HttpLibrary. We are going to have two test cases. One to make sure that unauthorised users cannot access my profile, and the second will be a request with our access token so we can fetch our profile.

Lets start by creating our new suite file and name it github.robot. So in the settings section we need to include the http library. Also let’s give our suite a new tag

*** Settings ***
Library     HttpLibrary.HTTP
ForceTags   MediumStoryREST

Now, we are going to use some variables. Let’s just enter them and see their use later.

*** Variables ***
${token}           ?
${requestUri}      /user
${ACCESS_TOKEN}    %{ACCESS_TOKEN}

Now the last declaration looks fuzzy. First we declare a variable using the $ notation prefix and then we assigned another one with the % notation. Variables starting with % are coming from the environment. This is handy when we need to deal with secrets that we don’t want to expose as plain texts in our codebase.

Next step is to write the two test cases

*** Test Cases ***
Access an api request as unauthorised user
    Given users fullname "Ipatios Asmanidis"
    When is fetching his profile from api
    Then request is forbidden
Access an api request as authorised user
    Given users fullname "Ipatios Asmanidis"
    And user is authorized
    When is fetching his profile from api
    Then users profile is retrieved

Step back for a moment and imagine a world where those test cases as defined as acceptance criteria on a story or specification document. The developer can just copy them. Implement the keywords and then drive his implementation to the directions of those test cases. By the end of the development, the feature will be fully covered by acceptance testing, providing confidence to the development team and management.

Lets see about the keywords.

*** Keywords ***
users fullname "${fullname}"
    Set Suite Variable      ${fullname}     ${fullname} 
is fetching his profile from api
    Create Http Context     api.github.com      scheme=https
    Set Request Header      User-Agent          Robot-Testing
    Next Request May Not Succeed
    GET                     ${requestUri}${token}
request is forbidden
    Response Status Code Should Equal          401
    Response Body Should Contain        Requires authentication
user is authorized
    Set Suite Variable      ${token}      ?access_token=${API_TOKEN}
    
users profile is retrieved
    Response Status Code Should Equal          200
    Response Body Should Contain        ${fullname}

And that is all. In order to run the test successfully you need an access token which you can obtain by your profile settings in github. And in order to pass the token to robot and make it available in your tests you can do it by exposing this environment variable and then make sure it’s being passed in your run_tests.sh scripts. Of course there are plenty of ways how to tackle this, I’m just giving you one which I find easy. The final script file should look like this.

docker run --rm \
  -e USERNAME="Ipatios Asmanidis" \
  -e ACCESS_TOKEN=${ACCESS_TOKEN} \
  --net=host \
  -v "$PWD/output":/output \
  -v "$PWD/suites":/suites \
  -v "$PWD/scripts":/scripts \
  -v "$PWD/reports":/reports \
  --security-opt seccomp:unconfined \
  --shm-size "256M" \
  ypasmk/robot-framework

And to pass the token all you need to do is run it like

ACCESS_TOKEN=myawesometoken && ./run_tests.sh

If you’ve done everything correctly then you should get something like this

And opening the reports in the browser should show you something similar to the screen below

Conclusion

Robot framework is a solid, complete and flexible solution when it comes to user acceptance testing. Having to focus more on writing your test cases and less about preparing and maintaining the infrastructure, help you achieve more in less time.

P.S If you have any issues running the tests, you can checkout the branch that contains the above examples

git checkout medium-branch
./run_tests.sh

This will run all the tests and you will notice two more files in the /suites folder.

Have fun!!!