cucumber / cucumber/common

Preprocessor standard

Open
#773 16 comments 1 reaction 0 assignees View on GitHub
:safety_pin: pinned milestone-proposal platform consolidation
Dominant language
No language data
Stars
3.4k
Forks
679
PR merge metrics
No merged PRs in 30d

Description

While we usually recommend putting all the data for a scenario inside of Gherkin documents, there are valid use cases for pulling data in from an external source, such as an Excel file (or other source).

SpecFlow already has [support for this](https://specflow.org/plus/documentation/prepare-feature-files-for-external-examples/)

I would like to come up with a specification for a preprocessor API that supports Gherkin, but also Markdown, which we might add support for at some time.

What I have in mind is this:

Document -> Preprocessor -> Preprocessed Document -> Parser -> AST -> Compiler -> Pickles -> Cucumber -> Results

The flow is currently:

Document -> Parser -> AST -> Compiler -> Pickles -> Cucumber -> Results

We could agree on a set of preprocessor directives for each supported input format (Gherkin, Markdown). Open questions:

## Syntax

SpecFlow currently uses the format `@source:excel-file-path[:sheet-name]`.

That works, but it wouldn't allow e.g. fetching an Excel document from a URL.

It also overloads the tag syntax, which seems a little confusing to me. I would prefer a dedicated preprocessor syntax (like the C preprocessor). Ideally a syntax that would work for both Gherkin and Markdown

## Format

What if we want to pull data in from a CSV or JSON source? It would be nice if users could easily plug in their own preprocessor plugins for parsing the data at the external source. We'd provide a default one for CSV and/or Excel. I think most languages have decent Excel parsers.

## Semantics

SpecFlow will merge contents from the Gherkin document and the external Excel document. That seems useful, but it would be great to be specific about what happens if the columns differ in various circumstances.

Let's discuss!

Contributor guide

Open the contributing guide

Research direction

The issue names no repository files, tests, or entry points. Start by reviewing the existing Document → Parser flow and the linked SpecFlow external-examples support, then define a preprocessor API covering syntax, source formats, plugins, and merge semantics for Gherkin and possible Markdown input. Done means the open questions are resolved in an agreed specification.

Written by the indexing model from the issue text.

Assessment

Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.