Support Gherkin `.feature` files as OpenFastTrace specification documents

[kaklakariada]

Motivation

Behavior-Driven Development (BDD) frameworks such as Cucumber, Behave and SpecFlow use Gherkin .feature files to describe executable requirements.

These scenarios are often the most up-to-date requirements of a system, but they cannot currently participate in OpenFastTrace's traceability analysis as specification items.

OpenFastTrace already supports importing coverage tags from .feature files. This functionality is widely used and must remain fully backward compatible. The proposed feature extends the existing importer to additionally recognize specification items without changing the existing coverage tag support.

Proposed solution

Extend the existing Gherkin importer (see #425) to support OpenFastTrace specification items.

Each Gherkin Scenario (or Scenario Outline) represents one OpenFastTrace specification item.

The specification item ID is provided as a dedicated Gherkin tag.

Example:

Feature: User login

  @smoke @authentication @id:scn~login-success~1
  # Covers: dsn~login~2, dsn~logout~3
  # Covers: dsn~remember-me~1
  # Needs: impl, utest, itest

  Scenario: Successful login
    Given the user "alice" exists
    When she logs in with the correct password
    Then the dashboard is shown

This creates the specification item

• ID: scn~login-success~1
• Title: Successful login
• Description: the scenario body
• Covers: dsn~login~2, dsn~logout~3, dsn~remember-me~1
• Needs: impl, utest, itest

The file remains valid standard Gherkin and can still be executed by existing BDD frameworks.

Requirements

Backward compatibility

The existing .feature importer already recognizes OpenFastTrace coverage tags. This behavior must not change.

Specifically:

• Existing .feature files must continue to import exactly as before.
• Existing coverage tags must continue to work unchanged.
• The new syntax is purely additive.
• Users who do not use specification item tags must observe no behavioral changes.

Syntax

Specification item ID

Each Scenario or Scenario Outline must contain exactly one OpenFastTrace ID tag.

@id:scn~login-success~1

The tag follows the existing OpenFastTrace specification item ID syntax while remaining valid Gherkin syntax.

Additional Gherkin tags are allowed and ignored by OpenFastTrace.

Example:

@smoke
@regression
@id:scn~login-success~1
Scenario: Successful login

Metadata

OpenFastTrace metadata is stored as comments.

Supported metadata:

# Covers: ...
# Needs: ...

The metadata may appear anywhere after the OFT ID tag and before the next specification item.

For example, all of the following are valid.

Before the scenario:

@id:scn~login-success~1
# Covers: dsn~login~2

Scenario: Successful login

After the scenario:

@id:scn~login-success~1
Scenario: Successful login
  ...

# Covers: dsn~login~2

Mixed:

@id:scn~login-success~1
# Needs: impl

Scenario: Successful login
  ...

# Covers: dsn~login~2

Import rules

Specification items

Imported as OpenFastTrace specification items:

• Scenario
• Scenario Outline

Not imported:

• Feature
• Rule
• Background
• Examples

Description

The description consists of the complete Gherkin scenario (steps only).

Tags

• Ignore all non-OFT tags.
• Require exactly one valid OpenFastTrace ID tag.
• Report an error if no OpenFastTrace ID tag exists.
• Report an error if multiple OpenFastTrace ID tags are present.

Metadata scope

The metadata region begins with the OpenFastTrace ID tag and ends immediately before the next:

• OpenFastTrace ID tag
• Scenario
• Scenario Outline
• Feature
• end of file

Within this region, the importer recognizes:

# Covers: ...
# Needs: ...

All other comments are ignored.

Validation

The importer should report errors for:

• missing OpenFastTrace ID
• invalid specification item ID
• duplicate specification item IDs
• multiple OpenFastTrace ID tags on one scenario
• malformed # Covers: entries
• malformed # Needs: entries

TODO

Implementation

• Extend the existing Gherkin importer to recognize specification items.
• Preserve all existing coverage tag functionality.
• Register the new parser logic without changing existing importer behavior.

Testing

• Add unit tests for valid .feature files.
• Add unit tests for invalid .feature files.
• Add regression tests proving that existing coverage tag imports continue to work unchanged.
• Add integration tests covering mixed legacy and new syntax.
• Add a Gherkin / Cucumber linter to verify that OFT-enhanced files are still valid Gherkin syntax.

Documentation

• Extend the user documentation with the new .feature syntax.
• Document the mapping between Gherkin elements and OpenFastTrace specification items.
• Add examples demonstrating traceability between Gherkin scenarios, design documents, implementation, and tests.

ChatGPT Skill

• Extend the OpenFastTrace ChatGPT Skill to recognize and generate traceable .feature files using the new syntax.
• Update prompts and examples to prefer the new syntax when generating Gherkin specifications.

Benefits

• Enables executable BDD specifications to participate in OpenFastTrace traceability.
• Preserves complete backward compatibility with existing .feature support.
• Keeps .feature files fully compatible with existing Gherkin tooling.
• Reuses the existing OpenFastTrace concepts (Covers, Needs, specification IDs) with minimal new syntax.
• Allows requirements, design, implementation, and executable acceptance scenarios to be linked within a single traceability graph.

[skyglass]

I just found out that we can use any tags with name, which is allowed gherkin syntax.

So we can also add "Covers" and "Requires" as gherkin named tags:

@exasol-query-execute-write-query-against-backend
@covers:dsn~password_complexity_check~1
@requires:itest,impl,utest
Scenario: Execute a read-only query against the backend
  Given an Exasol database is reachable at localhost
  When the query runtime executes a read-only SELECT statement
  Then changed is false
  And executed_queries equals the executed SELECT statement
  And query_result contains the selected value

I think we don't need to provide the name for the first scenario_id tag, but if this would improve readability, we could also use names for all tags:

@scenario_id:exasol-query-execute-write-query-against-backend
@covers:dsn~password_complexity_check~1
@requires:itest,impl,utest