Getting started

The Robotframework Workbench is a collection of tools for working with robotframework test case files. It is comprised of the following tools:

• [rwb.editor](rwb.editor User Guide) - a plain text editor designed for editing robotframework test suite files that use the plain text, pipe-separated format
• [rwb.debugger](rwb.debugger User Guide) - a graphical test monitor and minimal debugger
• [rwb.lint](rwb.lint User Guide) - a command line tool for checking the syntax of test suite files and resource files
• [rwb.logviewer](rwb.logviewer User Guide) - a graphical tool for viewing robotframework output xml files
• [rwb.kwbrowser](rwb.kwbrowser User Guide) - a graphical tool for viewing keyword documentation

In addition, the workbench also includes a couple of additional features:

• [rwb.DebugLibrary](rwb.DebugLibrary User Guide) - a keyword library with a keyword that works with rwb.debugger
• [rwb.socket_listener](rwb.socket_listener User Guide) - a listener that sends information about a running test to a remote listener, such as [rwb.debugger](rwb.debugger User Guide)

**Note: these tools are all under active development, and will likely have bugs. **

If you need to install the robotframework workbench, see the page titled Installation Instructions

Creating a test

Open up a terminal window if you don't already have one open. From the command prompt issue the following command:

$ python -m rwb.editor test1.txt

If the workbench is installed correctly you should see an editor window appear. You will be entering a test case in the main portion of the GUI on the right. The portion on the left is a list of open files.

Before typing, you might want to know about a few features unique to this editor:

• Smart headings - typing a * at the start of the line will automatically insert three asterisks, three spaces, then three more asterisks. It will then move the cursor between the two sets of asterisks.
• Smart pipes - This editor is designed to edit test case files that use the plain text, pipe-separated format. This format requires that table cells be separated by one or more spaces, a pipe, and one or more spaces. To make typing easier, pressing the pipe key will automatically enter a space, pipe and space.
• Tab navigation - like a typical spreadsheet, pressing the tab key moves you from cell to cell. If you are at the end of a line and press tab, the editor will automatically add an extra cell for you. If you are already in a trailing blank cell, tab will move you to the next cell (if there is one). This makes it easy to enter multiple cells without ever having to press the pipe key. For example, typing onetwothree will give you a line with three cells in it.
• Smart returns - pressing control-return at the end of the line will create a new line that has the same number of leading blank cells as the current line.
• Smart braces - if you type a dollar sign followed by a curly brace, the editor will automatically add the closing curly brace for you

Ok, now that you know a few of the special features, it's time to create your first test. Type the following into the editor:

*** Test Cases ***
| Test Case #1
| | log | this is test case number 1

| Test Case #2
| | log | this is test case number 2

Run your test from the editor

To run the test from the editor, click on the Run button. This will automatically save the file before running. A window with three notebook tabs will appear in the bottom part of the editor once the test starts to run. This is called the shelf. You can show or hide this window at any time using the View menu.

Note: When you click the Run button it will run the command python -m robot.runner, giving it the filename as an argument. In the prerelease version of the workbench this is not configurable, but it will be soon.

Using the debugger

To use the debugger, run the following from a command prompt:

$ python -m rwb.debugger

You should see a window open up with several blank sections. This is effectively a graphical robotframework listener. Notice in the lower-right corner it displays a number. This is the socket port number on which the listener is listening. By default this number is 8910. You'll need this number to tell robot where to send its data to.

Once that is running, we can run a test from the command line using the following command:

$ python -m robot.runner --listener rwb.socket_listener:8910 test1.txt

The rwb.socket_listener is a listener that forwards everything it gets to a socket. The port that it connects to is appended to the listener. You can actually specify both a hostname and port, so that you can run a test on one machine but monitor it from another.

Setting a breakpoint

If you wish to pause a test in the middle of its execution, you can use the breakpoint keyword in the rwb.DebugLibrary keyword library. Start up the editor, and change the test file to look like the following, then save and exit the editor.

*** Settings ***
| Library | rwb.DebugLibrary

*** Test Cases ***
| Test Case with a breakpoint
| | ${message}= | set variable | hello, world
| | breakpoint 
| | log | ${message}

Using the same command as before, run the test from the command line:

$ python -m robot.runner --listener=rwb.socket_listener:8910 test1.txt

This time you should see that when the breakpoint keyword is run, the test will stop and display the value of all variables that are visible at that point in the test case. You can verify, for example, that ${message} has the expected value.

Run a test using the stand-alone graphical test runner

If you don't want to use the command line and you don't want to run from within the editor, you can use the stand-alone test runner. This is particularly useful if you have multiple monitors, as you can have the editor on one screen and the test runner on another.

To use the test runner, type the following command at a command prompt:

$ python -m rwb.runner test1.txt

Once the window appears, click on the Start button to run the test.

Viewing log files

When a robotframework test suite runs, it creates an xml file that contains all of the test statistics. Depending on command line options, it may or may not also generate some html files (eg: log.html, report.html). The html files are viewable in a browser, but for large log files this can be rather slow.

The robotframework workbench has a graphical tool for viewing log files. Since we just finished running a test there should be an output.xml file in the current directory. To view it, type the following command at a command prompt:

$ python -m rwb.logviewer output.xml

Note: the log viewer is still quite immature. Bear with me a little while longer