Preprocessor standard
- 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
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