Accelerate Substeps development
The goal of this plugin is to make the creation, execution, and refinement of Substeps test suites easier for everyone.
This page describes the plugins features and how they will help you in the day-to-day creation and maintenance of Substeps test suites.
It is not a guide to the Substeps framework itself, it is assumed you already have a working knowledge of Substeps. If you don’t, we recommend you read the Getting started guide.
The main features of the Substeps Eclipse plugin are:
- content assist – helping you use the most appropriate step definition and avoid duplication
- syntax highlighting – a splash of colour always helps to aid comprehension
- error highlighting – discover problems during editing
- execute tests – run Substeps tests directly from within Eclipse
- navigation – quickly navigate between feature files and the corresponding substep files
- code formatting – ensure consistency of formatting across teams
An Eclipse 4.2 (Juno) or greater installation and a Substeps project setup.
Installing the plugin
- Help → Install new software
- Click “Add…” to add Technophobia’s update site:
- Name: Substeps update site (or an alternative of your choice)
- Location: http://code.technophobia.com/substeps/eclipse/stable/
- Once added, select “Substeps update site” in the “work with” options list, expand Substeps in the pane below until you see an entry with a version next to it (see below)
Select the latest version, “Next”, accept the license agreement etc. and “Finish”.
Restarting Eclipse afterwards is not essential, although you may have to re-open any feature or substeps files you have already open.
It is actually possible to work on Substeps test suites without a specific editor. Simply write your features and substeps in a text editor and run them via the command line using one of the supported build tools (Maven, ANT or JUnit).
However, we feel that the plugin offers a number of significant benefits:
Features such as error highlighting mean that problems are discovered immediately as they are entered, instead of during execution.
Also, by using the content assist feature, less time can be spent searching through all of the substeps files looking for a particular definition.
More errors found during creation than execution
Without using the plugin, there is no way of knowing whether a feature set is valid or not without running it. This is quite a significant feedback loop. By highlighting problems in the editor as they’re typed, the feedback loop is reduced and should also reduce the number of times builds fail due to typos.
Less chance of duplication
With multiple people writing BDD tests on the same project, there’s a good chance they’ll have the same need for common substeps definitions and may each write their own versions, not realising others had done the same. This duplication will typically cause problems further down the line when tests need to be refactored or changed.
By using the plugin and content assist, team members are more easily able to spot existing step definitions that meet their needs before writing their own
The plugin provides a standard formatting capability of feature and substeps files, resulting in a consistent look across the various substeps files regardless of which team member wrote them.
All substeps related activity can be performed within the Eclipse IDE, without the need to switch between applications. From within Eclipse it is possible to author features and define Substeps, in addition to being able to run these tests, all without leaving the IDE.
This guide assumes a basic knowledge of Eclipse (nothing too exhaustive, but a knowledge of importing and navigating projects, how to open views etc).
The plugin provides an editor for features:
And Substep definitions:
Both editors offer:
- Substeps syntax colouring
- Content assist, triggered by Ctrl + Space with suggestions filtered by the text already typed on the line
Features and Substeps files can be located in the Project and Package explorers as with other file resources.
The outline view has been extended and populated with the structure of the feature or Substeps file, depending on which editor is currently active.
The outline view allows you to quickly navigate the overall structure of the Feature or Substeps file, and drill down to specific steps without having to scroll down/up.
The outline view can be enabled via the Eclipse menu:
Window → Show view → Outline
Jump to Step definition
When editing a feature file, it is possible to jump to the definition of a particular step using F3.
Place the cursor anywhere on the line within the feature file and press F3.
NB. Currently, this functionality only works for steps defined in Substeps files. If the step is defined in Java, no attempt will be made to open the corresponding Java file.
Substeps Test Execution
An important facet of the plugin is the ability to run and debug Substeps features easily. The current implementation has borrowed heavily from the Eclipse JUnit plugin, so users familiar with this functionality will also be familiar with the features of the Substeps plugin.
With a feature file selected in the Project or Package explorer view, select “Run As” → “Substeps Feature Test” from the context menu (right-click, by default).
Running a feature in this way is also available from the context-menu whilst editing a feature file.
Choosing to run a feature in this way will add an entry to the “Run Configurations”.
By default, no parameters are passed to the test runner. As a result, the execution of the test will use the default values.
To specify an alternate set of properties, open the Run Configurations, select the desired feature under Substeps, Arguments tab and add the appropriate
-D parameters to the “VM Arguments” field (eg.
Substeps Test Execution – Results
A Substeps view provides a hierarchical indicator of test progress and success or otherwise, in addition to any failure messages and stack traces that maybe encountered.
NB. There are a number of features that can be found in the Junit plugin that Substeps currently does not:
- It is not currently possible to jump from the hierarchy of executed steps to the corresponding location in the source file
- Re-running the tests via the hierarchical view
We are aiming to add these features in due course.
The Problems view is designed to highlight syntax issues directly to the author, without having to execute tests first.
Problematic lines are underlined and a marker placed in the overview ruler on the right, further details regarding the problem can be found in the “Problems View”.
By default, the plugin will highlight problems such as missing step definitions, duplications etc. in the editor and list these issues in the “Problems” view.
The detection of problems has a side effect of halting further processing that eclipse might do, such as compiling classes for example, which in turn may lead to further “problems” where step implementations cannot be found.
If you encounter such issues, simply disable the highlighting of problems in the Substeps preferences for the project.
Once the plugin has been installed it can be configured on a per project basis.
From the Package or Project Explorer view
- Select your Substeps project
- context (right, by default) click
By default, the plugin will highlight problems such as missing step definitions, duplications etc in the editor and list these issues in the 'Problems' view.
The detection of problems has a side effect of halting further processing that eclipse might do, such as compiling classes for example, which in turn may lead to further 'problems' where step implementations cannot be found.
If you encounter such issues, simply disable the highlighting of problems
The plugin will attempt to locate feature and substeps directories within the project.
If you are using the Maven pattern of locating these directories under src/test/resources or src/main/resources, you will need to specify the folders where the features and substeps can be found. This is due to the plugin finding the files in both target and source folders.
As the plugin is developed further, more options will be added to this set of preferences.