[Feature]: Let bddgen export use JSDoc for improved step catalog

[LarsFischer97]

The Problem

When i run bddgen export i get all steps. But for my LLM Workflows or documentation i would need a bit more context then just the step names. For this we need maintanable comments to my steps.

Proposed Solution

The solution idea is as follows:
bddgen export does also look for JSDoc information above the Decorator.

     /**
     * Assert that the value of the given property on the queried track event is a valid UUID.
     *
     * @param property - The exact property name to check (as it appears in ClickHouse).
     */
    @Then("the value of property {string} is an UUID")
    async assertPropertyValueIsUUID(property: string) {
     ...
     }

Then it creates a markdown table (as an example) and matches the Steps to the JSDoc information.

Step Definition	Description
Then the value of property {string} is an UUID	Assert that the value of the given property on the queried track event is a valid UUID. @param property - The exact property name to check (as it appears in ClickHouse).

Now we can generate a step catalog that is always up to date. 👍

As a solution I prototyped and vibe prompted/coded a proof of concept straight into the node_modules of my installed playwright-bdd🗡️ 😆 - Although not really worth showing it did somewhat work though.

If I have time i will look into creating a propper MR. But wanted to share the idea first.

Additional Context

No response

Priority Level

Medium

[vitalets]

Hey @LarsFischer97 , that looks useful. The challenge here is that jsdoc comments live in AST, and I'd avoid parsing AST inside bddgen. What if we enrich teh output with the actual file locations for every step? Then we can instruct LLM to grab the jsdoc comments and bind them to steps?

Example:

Current output:

$ npx bddgen export

Using config: playwright.config.ts
List of all steps (3):
* Given I am on Playwright home page
* When I click link {string}
* Then I see in title {string}

Proposed output:

$ npx bddgen export

Using config: playwright.config.ts
List of all steps (3):
* Given I am on Playwright home page # path/to/steps.ts:10:2
* When I click link {string} # path/to/steps.ts:13:2
* Then I see in title {string} # path/to/steps.ts:15:2

[LarsFischer97]

For a LLM this would work fine, but for a new dev having some sort of library of steps to choose from and knowing what exactly every step does just from a glance is pretty useful. This is what we struggle with. That we do have a quite flexible steps catalog, but developers do not know the nuances.

Another approach would be to take your suggestion for token efficent LLM support and addionally writing a IDE Plugin to show the jsdoc comments on hovering the steps in the feature file. But that plugin seems a bit over the top.

But i see how we would get a whole bunch of new potential problems when bddgen reads other things then the feature files.