Mkdocs Gherkin Results Plugin - Integrate Cucumber test results directly into your Mkdocs documentation.

Mkdocs Gherkin Results Plugin

5 views

Integrate Cucumber test results directly into your Mkdocs documentation.

Pitch

The Mkdocs Gherkin Results Plugin enhances your documentation by parsing Cucumber test reports and injecting results into Mkdocs pages. With visual indicators for pass and fail statuses, along with optional screenshot attachments, this tool helps maintain up-to-date documentation that reflects your test scenarios written in Gherkin format.

Description

The Mkdocs Gherkin Results Plugin is an innovative tool designed to enhance your Mkdocs documentation by seamlessly integrating the results of Cucumber test reports. This powerful plugin allows you to maintain dynamic, up-to-date documentation directly reflecting the outcomes of your Cucumber scenarios written in Gherkin format.

Key Features

Test Case Status Indicators: Automatically adds a checkmark next to passed test cases and a cross next to those that have failed, providing instant visual feedback on your documentation.
Screenshot Attachments: Easily display screenshots from test runs, giving context to test results.

Usage Example

To see the plugin in action, refer to the configuration example located in tests/test_docs. This example showcases the integration of both cucumber-js and Mkdocs within the same working directory.

To implement the example, follow these steps:

Run the Cucumber Tests:

cd tests/test-docs
npm install
npm run test

Generate Mkdocs Documentation:
- Create and activate your Python virtual environment using your preferred method.
- Launch the documentation generator:
```
python tests/test-docs/run.py
```

Configuration Options

Integrate the plugin into your Mkdocs setup by adding the following to your mkdocs.yaml:

plugins:
- gherkin-plugin

Configuration Settings

show_attachments: A boolean that determines whether file attachments are visible in the output. The default is True.
messages_path: Specify the location to load the Cucumber messages in NDJSON format, with the default set to gherkin_messages.ndjson.

Example Configuration:

plugins:
  show_attachments: True
  messages_path: "gherkin_messages.ndjson"

Additional Dependencies

If you plan to utilize screenshot attachments, ensure to add the following Markdown extensions:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Future Improvements

Address pending steps that are not displayed.
Create a short instructional video to demonstrate the plugin's functionality.

References

Utilize the Mkdocs Gherkin Results Plugin to elevate your project documentation and create an interactive guide that evolves along with your software testing!