Brackets as an outlining tool

For years (and years and years) I’ve used emacs as my primary editing tool. I sometimes use its built-in outline mode, but more often then not I just type into a never-ending buffer named “notes.txt”.

Lately I’ve been working on an extension to the brackets text editor for the robot framework. In order to eat my own dog food I’m slowing starting to use brackets instead of emacs for my go-to text editor. Emacs is a hard habit to break!

Today I needed to do a little outlining, so I pulled up brackets and created a new file named “notes.md” (.md is an extension for the markdown format). I was pleasantly surprised to see that this works quite well as an outliner. The markdown mode provides both syntax highlighting and code folding for headers and lists. This makes it easy to collapse and expand the sections of my outline as
I work. I’m not a “power outliner”, so this is really all I need.

Brackets is really starting to grow on me. Maybe one of these days I’ll write a more comprehensive review. If you aren’t married to your text editor — or even if you are — brackets is worth checking out.

Advertisements
Brackets as an outlining tool

Introducing Robot Framework extension for Brackets

Looking for a good text editor for creating robot framework plain text files? I’ve been working on an extension for the fantastic brackets editor. To install, simply install the brackets editor, go to the extension manager, and search for “robot”.

Project page: https://github.com/boakley/brackets-robotframework
Project wiki: https://github.com/boakley/brackets-robotframework/wiki

Features of the extension

The robot extension for brackets provides the following features:

  • syntax highlighting
  • code folding
  • smart handling of the tab key
  • code completion (if you have robotframework-hub installed)
  • in-editor keyword documentation (again, if you have robotframework-hub installed)

What is “smart handling of the tab key”?

I recommend using the pipe-delimited plain text format for test cases. I think this is the best combination of easy-to-read and easy-to-write. Unlike the tab- and space-separated formats, the separation of cells is more evident, which I think is important.

One downside of this format is that it’s tedious typing “| |” on most lines. Even worse is a continuation line which begins with “| | ... |“.

With this extension, pressing tab on a blank line automatically inserts pipes, spaces and continuation characters intelligently, removing some of the tedium with this format.

Want to start a new test case? A single tab on a blank line gives you the opening “|” (pipe-space) sequence.

Want to add a new statement to the current test case? Two tabs will get you the leading “| |” (pipe-space-pipe-space).

Want to add a new cell at the end of the current statement? If the cursor is at the last character and you press tab, it will insert “|” to start a new cell. Pressing tab immediately again will remove the trailing “|“, start a new line, and then insert the same number of pipes and spaces as the line you were just editing.

The general idea is to try and get the tab key to “do the right thing”. I’m still refining exactly what that means, but what it has now seems to work pretty well.

Why another extension for another editor?

There are already extensions for several popular text editors. Why create another one?

If I’m honest, it’s partly due to my own hubris. I have some slightly radical ideas for where I want this extension to go, and these ideas might not mesh with existing projects. So, why not write my own?

Another factor is that brackets is based on the remarkable codemirror widget, and I had recently spent a lot of time working with codemirror at my previous job. I’m wanting to strengthen my own javascript skills (which are extremely weak), so this is a chance for me to grow, professionally.

Considering all that, it was easier for me to create a new extension rather than to fork an existing extension and become a contributor.

Integration with robotframework-hub

Another project I’ve been working on is [robotframework-hub (https://github.com/boakley/robotframework-hub/wiki). The hub is a web app and api for serving up information about keywords.

If you are running the hub on your machine, the brackets extension can use the hub API to provide autocomplete and in-editor keyword documentation. Soon you’ll also be able to search your keywords right within the editor.

Summary

My goal with this extension is to give automation engineers a high quality editing tool, so they can focus more on the test case and less on the mechanics of editing the test.

Acknowledgements

A huge thank-you to my current employer, Echo Global Logistics who generously allows me to work on this project as part of my day job.

Introducing Robot Framework extension for Brackets

I’ve been working on a new project lately, called Robot Framework
Hub. It’s a lame name, I know. Suggest a better name and maybe I’ll
use it!

The project is now to the point where it’s ready to be used by more
people than just me and my team. In invite you to take a look. If
you’re impatient and want to see some screenshots before going to the
trouble of installing it, visit the rfhub wiki here:
https://github.com/boakley/robotframework-hub/wiki

What is robot framework hub?

What is the hub (I’ll use “rfhub” from here on out)? In short, rfhub
is a light weight, zero configuration web application and api for
serving up documentation for all of the robot framework keywords on
your system.

Tired of hitting the internet for library documentation? rfhub solves
that problem. Also, you can get documentation for all of the keywords
in your local resource files and private libraries in addition to
documentation for built-in keywords and installed libraries. Rfhub
also allows you search across all your keywords at once.

Want to try it out? it’s crazy easy to get started. All you need is
python and the robot framework, and a working internet
connection. Open up a terminal or command prompt and issue these two commands:

$ pip install robotframework-hub
$ python -m rfhub

That’s it! Now you can browse to <http://localhost:7070/doc&gt; to see the
documentation for the keywords on your system. Want to use the api?
<http://localhost:7070/api/keywords&gt; will return all of the keywords as
a JSON object. You can also search by name, or get a list of keywords
for a particularly library.

If you want to tell it where to find your own keywords, just add one
or more directories as arguments. For example, if you have keywords in
/src/tests/keywords, you can run the hub like this to see the
documentation for all of the resource files in that directory:

$ python -m rfhub /src/tests/keywords

Although serving documentation is all it does now,
I have pretty big plans for the hub — I want it to have a
dashboard to control your testing activities, a way to view robot
framework documentation, and a UI for running tests and viewing test
results amoung other ideas.

What rfhub is not

There’s another robot framework documentation system out there called
rfdocs (http://www.rfdocs.org). rfhub is not a replacement for
rfdocs. It is, however, an alternative. Whereas rfdocs is an
enterprise-class tool for managing the documentation for multiple
versions of libraries, rfdoc is a tool specifically for viewing the
documentation actually installed on your workstation.

Where can I find it?

rfhub is available on github: https://github.com/boakley/robotframework-hub

There’s a bit of information on that landing page, along with links to
the source. Be sure to check out the wiki which you can get to from
that landing page.

Want to contribute?

Would you like to contribute? I would love to have help growing rfhub
into an indispensable part of your testing toolkit. rfhub is written
in python and uses the flask web application framework. For the front
end I use bootstrap.

Send me an email and we can work out the details.

Acknowledgements

A huge thank-you to my current employer, Echo Global Logistics
(http://www.echo.com) who generously allow me to work on this
project as part of my day job.

What is Robot Framework?

In my current job we’re using robot framework. My team is tasked with teaching others how to use it, and to build additional tools to make the process of test automation easier. I’m going to be writing some on the blog about this framework, so I thought I would give a very brief introduction and explain why robot is so compelling.

Robot framework is a generic keyword-driven testing framework specifically targeted at acceptance test driven development. Tests are plain text files using a simple tabular syntax. Because the test cases are plain text, you are free to use whatever tools you’re most comfortable with (Eclipse, Visual Studio,emacs, vim, Notepad++, etc).

Robot framework is written in python, is robust and mature, and under active development. There are several extensions you can use in your test cases (eg: selenium, database, etc), and there are robot-specific extensions for other popular tools (eg: jenkins, sublime text,
brackets, etc).

What do the tests look like?

There is no canonical example of a robot framework test. It supports multiple formats, including HTML, reStructuredText, plain text, and tab-separated data. Personally I prefer the plain text, pipe-delimited format. It’s very diff-and-merge friendly, easy to write and easy to read. Unlike with tab- and space-separated plain text, the division between cells in a test case are clearly visible.

Here’s an example from the robotframework.org web site, reformatted to the pipe-delimited format:

*** Settings ***
| Documentation
| ... | A test suite with a single test for valid login.
| ... |
| ... | This test has a workflow that is created using keywords in
| ... | the imported resource file.
|
| Resource | resource.txt

*** Test Cases ***
| Valid Login
| | Open Browser To Login Page
| | Input Username | demo
| | Input Password | mode
| | Submit Credentials
| | Welcome Page Should Be Open
| | [Teardown] | Close Browser

Under the *** Test Cases *** heading, each line that begins with a single pipe denotes the name of a test case. Lines that begin with pipe-space-pipe-space are statements. Typically the first word will be a keyword (either a built-in keyword or a custom keyword), and remainging cells are keyword arguments.

That’s about all there is to it — very straight-forward, easy to read and easy to write.

What can the framework be used for?

The robot framework isn’t just for testing python code. It can be used for a variety of testing tasks, including:

  • RESTful API testing
  • SOAP service testing
  • Website testing
  • Database testing
  • Desktop application testing
  • Mobile application testing (with selenium and 3rd party drivers)
  • Unit and integration testing (though, there are often better tools
    for that job)
  • Manual testing – scenarios can be written as if they were automated,
    they can prompt the user rather than perform a task.

As you can see, it can be useful for a wide variety of testing tasks. Now, it might not always be the best solution for any one of those areas but it’s one of the few tools that can be used for just about all testing tasks. This means you have a single test syntax to learn, a single reporting structure, a single way to tag and manage tests, and so on.

Other things I like about the framework:

  • Robot framework is written in python, and libraries can be written
    in python. Anything you can do with python, you can do in a test
    case. This makes it very easy to extend to do a variety of tasks.
  • Robot framework has a remote library interface, which means you can write keywords
    in any language that can open a socket (.NET, java, C, etc).
  • Robot test suites are plain utf-8 text. This means they play nicely
    with source control, making it easy to diff and merge
  • You have the choice of writing tests in a BDD (given/when/then)
    style, a procedural style, or in a data driven style. Work the way
    you want, rather than be forced into a particular style of test.
  • it has a powerful tagging mechanism
  • it has a powerful system for streaming test results to other tools
    and dashboards (called “listeners” if you want to look it up in the
    user guide).

Summary

Robot framework is a really good testing framework, if your goals are
to use a single framework for a variety of testing and if you want to
use a keyword driven approach. The fact that it’s easily extensible
with python and that it plays well with tools you probably already use makes
it a very pragmatic choice for a large variety of testing tasks.

The robot framework project has fairly comprehensive documentation. To
get started, visit http://www.robotframework.org

What is Robot Framework?