jsdoc-cypress-cucumber-plugin

This plugin for JSDoc provides a method for documenting step definitions created for cypress-cucumber-preprocessor.

Usage

The plugin provides new tags: @step, @stepalias, @When, @Given, @Then

Tag | Description --------------|--------------------------------------------------------------------------------------- @step | Let JSDoc know you're documenting a step definition. The other tags rely on this one. @stepalias | If you provide more than one expression for the same step, document it with this. @When | Documents a When expression @Given | Documents a Given expression @Then | Documents a Then expression @needs | Reference another step definition using @link to describe needed contexts @provides | Describe the context provided by a step. @group | Categorize a step.

The step's name and ID are generated by the plugin based on the value of the expression keywords.

For instance, the expression @Given this page loads's Name, which can be used for @link references among other things, would be: givenThisPageLoads. HTML tags and attributes are stripped from the generated name.

Example

/**
 * @step
 * @description My description
 *
 * @When I scroll to selector
 * @stepalias I scroll to the selector element
 * @stepalias I scroll the selector element into view
 *
 * @summary
 * Scrolls the page until the provided selector is viewable.
 *
 * @needs {@link someOtherStep}
 * @needs {@link youCanAddMultipleRequiredSteps}
 * @group samples
 */
When(/^I scroll(?:\sto)?(?:\sthe)? "([^"].*)"(?:\selement\sinto\sview)?/, (selector) => {
  // do something here
});

Installation

1. Install the plugin via npm.
2. Add the plugin to the plugins array in your .jsdoc.json.
3. Add something to your template to get things to render.
4. Document your cucumber/cypress invocations

Template

At the moment, you'll need to add a way to display the new tags in a template. Something like this would render most of the tags nicely:

<dl class="details">
  <?js if(data.needs && data.needs.length > -1) { ?>
    <dt class="tag-source">Needs step(s):</dt>
    <dd class="tag-source">
      <ul>
        <?js data.needs.forEach((e, i) => { ?>
          <li><?js= e ?></li>
        <?js }) ?>
      </ul>
    </dd>
  <?js } ?>
    <dt class="tag-since">Reference name:</dt>
    <dd class="tag-since"><ul class="dummy"><li><?js= data.name ?></li></ul></dd>
    <dt class="tag-since">Step group:</dt>
    <dd class="tag-since"><ul class="dummy"><li><?js= data.group ?></li></ul></dd>
  </dl>

  <?js if (data.params && params.length && !data.hideconstructor) { ?>
    <h5>Parameters:</h5>
    <?js= this.partial('params.tmpl', params) ?>
  <?js } ?>

</div>

Roadmap

• [ ] Create a JSDoc template specifically for documenting test step definitions. Likely a separate package.
• [ ] Improve the @needs tag to allow direct linking by ID or possibly context, rather than needing the @link tag.
• [ ] Other suggestions.