Robot Framework Assistant

Robot Framework Assistant provides IDE features to edit Robot Framework test data in the Sublime Text 3.

From release 3.0.0 onwards plugin is not anymore compatible with Sublime Text 2. The releases made before the 3.0.0 will serve the Sublime Text 2 users. The documentation for Sublime Text 2 user can be found from st2-maintenance branch README

Installation

The easiest way to install is to use Package Control and search for: Robot Framework Assistant.

Alternative installation methods

Download the plugin as a zip. Open Sublime Text and click *** | Preferences | Browse Packages | *** to open the packages directory. Then create a directory named Robot Framework Assistant and unzip the plugin to the directory.

Configuration

Before yo can start using the Robot Framework Assistant, you must at least configure the settings in the User package Robot.sublime-settings file. To Open the file navigate to: Preferences | Package settings | Robot Framework Assistant | Settings - User | The default settings can be found from the Preferences | Package settings | Robot Framework Assistant | Settings - Default |

robot_framework_workspace

Before the Robot Framework Assistant can provide the keyword and variable completion features, it needs to create a database from the test suite and resource files. The argument defines the root folder where scanning of robot data is performed.

Must point to a folder and pointing to a file is not allowed. When the command Robot Framework: Create database is executed, the scanning of Robot Framework test data is performed based on this setting.

In windows ow write double backslash to write literal backslash.

robot_framework_keyword_argument_format

Defines how keyword argument are formatted when keyword completion is used. When set to false, each argument is formatted to individual lines. If set to true keyword and arguments are returned in single line.

robot_framework_extension

File extension defines which types of files the Robot Framework Assistant plugin will search from the folder defined in the robot_framework_workspace option.

This setting affects the plugin commands and features but the theme definition in this plugin is not affected by this option.

If there library or variable file imports in the Robot Framework data, those imports are automatically parser and included in the scanning.

path_to_python

In order the creating the database of keywords and variables to work, path to Python binary must be defined. It must be the same Python binary where the Robot Framework is installed.

In Linux like environments this could be like: /usr/bin/python and in Windows this could be like: C:\Python27\python.exe

robot_framework_module_search_path

Module search path defines a list of paths where the Robot Framework libraries are searched. Example if you have imported a library with the library name, then module search path must contain the folder where the library can be located.

The Robot Framework Assistant uses the Robot Framework API to parse the test data and libraries. All changes, which are not system wide, to locate the libraries, must also be added in the module search path in the Robot Framework Assistant

More details how libraries is searched in Robot Framework can be found from be the Robot Framework User guide

robot_framework_library_in_xml

When a library is not available during parsing time, example if library is imported with Remote library interface or it is not written in Python like the SwingLibrary Then this setting can be used to import libraries in libdoc XML format.

Libraries found from the this path are globally available, like the BuiltIn library. Example the keyword completion will work although the library may not imported for that particular resource or test suite.

robot_framework_builtin_variables

Robot Framework comes by default some predefined and builtin variables. These variables names may change between different Robot Framework versions. Use this setting to define a list of the Robot Framework BuiltIn variables. The easiest way to see the list of the variables is to run Robot Framework with following test case:

*** Test Cases ***
Log All BuiltIn Vars
	Log Variables

Note: At least on Robot Framework 2.9.2 version, the following command did not list the empty variables, like ${EMPTY}.

Syntax definitions

By default this plugin will be used with files which extension is .robot and plugin will use four spaces as cell separator. The settings can be changed by user, but consult the Sublime unofficial documentation where the user settings should be saved.

Change the file extension

The file extension is defined in the Robot.tmLanguage file. To change file extension, navigate to the User package folder and open the Robot.tmLanguage file.

Look for the lines containing:

<key>fileTypes</key>
    <array>
        <string>robot</string>
    </array>

The <string> element contains the file type definition.

Change the cell separator

The cell separator is defined in the Robot.tmPreferences file. To change the cell separator, navigate to the User package folder and open the Robot.tmPreferences file.

Look for the line containing <string><![CDATA[ ]]></string> XML tag. There are four spaces inside of the [ ] characters and those four spaces defines the cell separator which is user by the plugin. The cell separator is example used by the for loop snippets to align and display snipped correctly.

Hotkeys

• Pressing Alt + Enter or Alt + Click with mouse, on top of the keyword will go to the keyword source. Source of the keyword can locate in Robot Framework test data or in a Python library. Go to does not work on libraries written in other programming languages.
• Pressing Ctrl + Alt + Enteror Ctrl + Alt + Clicl with mouse will display the keyword documentation.
• Pressing Ctrl + Alt + a will run the Robot Framework: Create Database command
• Pressing Ctrl + Alt + s will run the Robot Framework: Create Database Tables command
• Pressing Ctrl + Alt + t will run the Robot Framework: Create Database Table From Active Tab command
• Pressing Ctrl + Alt + i will run the Robot Framework: Create Database Index From Active Tab command
• Pressing Ctrl + Alt + r will show available library, resource or variables imports in a popup menu. The popup menu is only displayed if cursor is in settings table and line contains Libraries, Resource or Variables setting.

The usage of the Ctrl + Alt + a/s/t/i commands is explained in the Internal database for keywords and variables wiki page

Snippets

Snippets are a Sublime Text feature to provide commonly used text templates and in this plugin, snippets offers quick access to the commonly used settings in the Robot Framework data. To gain access to the snippets write the required character combination. If the snippet is not displayed press the Tab key to see the snippets completion list. The snippets can be accessed with following key combinations:

• Write :f to access Robot Framework for loops. There currently are available the following snippets: normal, enumerate, range and zip loops types.
• Write *k to access *** Keywords *** table snippet.
• Write *s to acess *** Settings *** table and it settings. There currently are available the following snippets: Default Tags, Documentation, Library, Resource, *** Settings ***, Test Setup, Test Teardown, Test Template and Test Timeout.
• Write *t to access *** Test Cases *** table snippet.
• Write :to access Keyword and Test Case settings. There currently are available the following snippets:: [Arguments], [Documentation], [Return] [Tags], [Teardown] and [Timeout].
• Write *v to access *** Variables *** snippet.

The different for loop snippets uses the fields feature from the snippets. After completing the for loop snippry, the different for loops fields can be accessed by pressing the tab key.

Please note that plugin does not prevent the user to place snippets in invalid places in the test data. Please refer to the Robot Framework User Guide to locate the correct usage of the different available snippets.

Go To Keyword

Alternatively, use Sublime Text's Go To Symbol to go to the source of a Keyword.

Please note that Go To Symbol only works for keywords within the same file. It is not possible to use Go To Symbol to jump keyword in other resource files or in libraries.

Creating a database

Once the plugin configuration is done, the plugin needs to scan the test data to create a internal database to the package directory. The database will contain table for each test case, resource and library. Once the tables has been created, plugin will create a index for each test case, resource and library. Index will contain all keywords and variables, what the test case or resource has imported in the test data. Indexing allows plugin to provide completion to only those keyword or variables which has been imported for the currently opened test or resource file.

The plugin will automatically update the pointer to the index in the database, when user will change between different tabs in the Sublime.

Error investigation for database creation

When creating the database, plugin will write a log file to the package installation directory: database/scan_index.log file. If there are errors when the database is created, please check the log and correct possible errors.