Extending RobotFramework to check emails

  • Sharebar

RobotFramework logo

In the two first tutorials (How to use RobotFramework With SeleniumLibrary and How to use RobotFramework Part 2), Mathieu Bultel showed us how to use Robot Framework to test your web applications. Unfortunately, Robot Framework doesn’t always give you means to test want you’d want to. To compensate for, Robot Framework lets us create our own test libraries.

Our goal in this tutorial will be to learn how to create those test libraries and how to use them in your test suites. This tutorial will only give the Python way of creating your libraries however they can be implemented using Java if you run Jython. I’ll assume you know at least a bit of Python during this tutorial. If you don’t, Robot Frameworks gives a great tutorial on how to begin with Python. I advise you to keep it somewhere near so you can understand what is going on throughout this guide.

Finally, if you want some more tips about this subject please go read Robot Framework user guide.

Getting started

First of all, you need to create a python class or module. When creating your file be aware that its name will be the name of your library. If you want to make a class I recommend you to give your class the same name as your file so you can drop the module name when importing your library. Yet if you want to give different names, you’ll have to import moduleName.MyLibName.

Now you have your file you have to set two variables to give informations to Robot Framework. The first one is called ROBOT_LIBRARY_SCOPE. It is used to tell Robot Framework whether it should create new instances of your library once every test case, once every test suite or once for the whole test execution. The values of this variable are TEST CASE (default), TEST SUITE and GLOBAL.

The second is ROBOT_LIBRARY_VERSION (or __version__) which determines the version of you library. (for example : 0.1, 1.1.3, 1 … This is up to you how you want to count)

your file should look like :

import someusefullib
import anotherusefullib
class mylib:
    __version__ = '0.1'

You’ve created your first Lib (Yay !) now let’s make it do something.

For our check_mail.py library, we’ll have:

import imaplib
class check_mail:
    __version__ = '0.1'

Robot Framework Keywords

To create a keyword usable in your test suites, simply create a new method in your class (or module). This function’s name will be the keyword with little adjustments. First the matching between methods’ names and keywords is case insensitive meaning that “Pwet” and “pwet” will refer to the same method (pwet for example) in your library. Then the matching ignores underscores and spaces meaning that the keyword “Try This” matches “TryThis” and “Try_this”.


If your library needs arguments (for its constructor) you just have to add an __init__ method with all the arguments you need. In this case you’ll have to give those arguments to your library when you import it.

In the case your keywords need arguments, methods implementing those keywords take those arguments. The simplest is to have an exact number of arguments. Yet you can put a variable number of arguments using python syntax :

def many_args(*args):
    print args

You can also give default values to you arguments. (not necessarily to all of them)

def default_arg (arg1, arg2='default'):
    print arg1, arg2


The error handling is pretty simple . Keyword status is reported thanks to exceptions which means that if a keyword raises an exception, its return value will FAIL whereas if it returns normally, it will PASS.

Moreover, error types and messages will appear in logs, reports and the console. So when you create your library you should give error messages as precise as you can. This way, it will be easier for you to find what part of your test failed and for what reason.

def check_mail(self, *args):
    r, self.item = self.mailbox.search(None, *args)
    self.item = self.item[0].split()
    if self.item == []:
        raise AssertionError("No mail found")

This example will call the imaplib method search. In the case it can’t find any mail from your mailbox (that you’ve opened before) with the arguments you specified, you see “No mail found with your arguments” in your robot frameworks log and the test return value will be set to Fail.

Use your new library in robot framework

Now you’ve done your library, all you have to do to use it in robot framework is to import it in the Settings part of your file using :

Library	   path/to/your/lib.py

You can then call your keywords as it they were robot framework keywords.

Putting all together

Here is the complete source of check_mail.py:

import imaplib
class check_mail:
    __version__ = '0.1'
    def open_mail_box(self, server, user, pwd):
            self.mailbox = imaplib.IMAP4(server)
            self.mailbox.login(user, pwd)
        except imaplib.IMAP4.error:
            raise AssertionError('Could not connect to the mailbox')
    def check_mail(self, *args):
        r, self.item = self.mailbox.search(None, *args)
        self.item = self.item[0].split()
        if self.item == []:
            raise AssertionError("No mail found")       
    def close_mailbox(self):

And a test case using the library that check if a new mail is present from remote@domain.com will look like this:

Library		Lib/check_mail.py

*** Test Cases ***

TC test mail [Documentation]
   Open Mail Box  server user password
   Check Mail  UNSEEN  FROM  "remote@domain.com"

Article contributed by Juliet Godon, intern in Wallix AdminBastion team.

Incoming search terms:

  • robot framework keywords
  • robot framework java example
  • robot framework libraries
  • robot framework email
  • robot framework suite setup example
  • robot framework python
  • python robot framework
  • check emails
  • how to get mails opened in robot framework
  • robot framework python library
This entry was posted in development, test and tagged , , . Bookmark the permalink.