Code Completion

As the number of Gherkin documents (.feature files) grow in a project it often becomes time consuming to edit Gherkin files because the number of Step Definitions also have a tendency to grow.

Editors supporting code completion (see Tool-Support) can help make the editing experience by providing code completion for known Step Definitions. Step Definitions can be written in many different languages, based on several BDD tools such as Cucumber, SpecFlow, Cuke4PHP, Behat etc. Common for them all is that they use Regular Expressions as part of their definitions.

These Regular Expressions, combined with the total set of Gherkin features in a project can be used to build up a database of meta data to power an editor's code completion. SpecFlow already has excellent support for this.

The purpose of this document is to define the format of such a database. Each BDD tool would be responsible for implementing functionality to populate a database in this format. The database can then be shared and made available to many different editors, both desktop based and browser based.

See this thread for a discussion on this topic

See Gherkin Editor for a web-based implementation of this spec.

Design considerations

Incremental updates

It should be possible to rebuild the database incrementally when a Step Definition or Gherkin document changes. This is to ensure that code completion in the editor is always up to date without the user having to wait.

Cross-platform database format

In order for the database to be usable on many different platforms, it should be in a format that is easy to query and update. Candidates are JSON or SQLite.

Desired editor behaviour

When the caret is placed right after a step keyword (Given, When Then etc) and the code completion trigger is invoked (often CTRL-space), a popup should appear that:

• Lists all available Step Definition Regexen
• Filters the Regexen as the user types
• Displays examples from other Gherkin documents

Example:

Given the following steps exist:
  """
  Given I have 4 cukes in my belly
  And I have 3 bananas in my basket
  Given I have 42 cukes in my belly
  """
And the following stepdef regexen exist:
  """
  I have (\d+) cukes in my belly
  I have (\d+) apples in my bowl
  """
When the user asks for code completion for "Given I"
Then the presented options should be:
  """
  * I have (\d+) cukes in my belly
  ** I have 4 cukes in my belly
  ** I have 42 cukes in my belly
  * I have (\d+) apples in my bowl
  """

The ** indented options are taken from the Gherkin files. This could be implemented with a JSON document that looks like the following:

{
  "I have (\\d+) cukes in my belly": [
    "I have 4 cukes in my belly",
    "I have 42 cukes in my belly" ],
  "I have (\\d+) apples in my bowl": []
}

The editor would have an in-memory representation of the JSON document (HashMaps and Arrays). The current step fragment in the editor would then be matched iteratively. When there is a match, add the regexp to the option list, and add elements in the associated array underneath.