Add suggestions/snippets to the model

[davidjgoss]

🤔 What's the problem you're trying to solve?

Snippets are not currently part of the messages schema. As we move to messages-based formatters, they won't be able to include snippets unless we add them to the schema. This is already the case with the xml, pretty and html formatters.

✨ What's your proposed solution?

Add snippets to the messages schema.

There's more than one good way we could do this, but my first draft would be:

• New Snippet message emitted once for each unique snippet containing
  • id
  • text the unmatched step text
  • code the suggested code
  • language the language of the suggested code (useful for e.g. syntax highlighting in formatters)
• New optional field snippetId on the existing TestStepResult message, to be included for undefined steps where there is a snippet

[davidjgoss]

Implementation:

• messages Add Suggestion message messages#329 29.0.0
• compatibility-kit Add Suggestions to undefined samples compatibility-kit#167
• query Find Suggestions query#102
• formatters
  • junit-xml
  • testng-xml
  • pretty
  • html
  • cucumber-json
  • teamcity
• implementations
  • cucumber-node
  • cucumber-js
  • cucumber-jvm Emit Suggestion message cucumber-jvm#3073
  • cucumber-ruby
  • reqnroll

[mpkorstanje]

I have three use-cases to cover.

1. Reporting snippets per test step for plugins that can report test steps.
2. Reporting all unique snippets in a test case for test runners that work at test/scenario level
3. Reporting all unique snippets in a test run for easy copy pasting.

So my idea for Snippet would be:

{
 id,
 pickleId, // to find this snippet given a testcase -> pickle, or to look up the unmatched text
 pickleStepId,  // to find this snippet given a test step -> pickle step, or to look up the unmatched text
 code, // the suggested code
 language // the language of the suggested code (useful for e.g. syntax highlighting in formatters)
}

Additionally, snippets can be generated even if a step is not is not executed. So I don't think any changes to TestStepResult would be needed.

[davidjgoss]

@mpkorstanje makes sense, happy to implement on that basis.