README.adoc

asciidoctor-gherkin-extension

You can use this extension to include your gherkin feature files in asciidoc in the form of sections, paragraphs, lists and tables.

The conversion is based on a simple, customizable erb template.

Usage

The following feature

simple.feature

Feature: A simple feature
  This is the feature description.

  Background: Background
    Given a simple background step.

  Scenario: Scenario title
    Given a simple scenario step
    When I render the asciidoctor content to html
    Then my feature gets nicely formatted in html.

can be included via the gherkin block macro :

gherkin::./simple.feature[]

and gets rendered into a 3rd level section with subsections :

Corresponding intermediate asciidoc source

=== A simple feature

This is the feature description.

==== Background

[.step-list]
* *Given* a simple background step.

==== Scenario title

[.step-list]
* *Given* a simple scenario step
* *When* I render the asciidoctor content to html
* *Then* my feature gets nicely formatted in html.

If the 3rd level section doesn’t match the section level at the point where you want to include your feature file, you can adjust the section level via the :leveloffset: attribute.

:leveloffset: -1
gherkin::./simple.feature[]
:leveloffset: +1

Or just create your own template.

See the integration tests for a complete maven example.

Formatting tables

You can add some asciidoctor formatting to tables, e.g. column widths, header style, etc.

For example, the following gherkin table

  Given a complex background step with table with header
    #cols=".<2,.^5,^.>3",options="header"
    #cells=h,h,h
    | Header Cell 1            | Header Cell 2          | Header Cell 3 |
    #cells=,m,
    | Cell 1 Row 1             | Cell 2 Row 1 monospace | Cell 3 Row 1  |
    | Cell 1 Row 2 with *bold* | Cell 2 Row 2           | Cell 3 Row 2  |

renders as asciidoctor equivalent :

[.step-list]
* *Given* a complex background step with table with header
+
[cols=".<2,.^5,^.>3",options="header"]
|====
h| Header Cell 1 h| Header Cell 2 h| Header Cell 3
| Cell 1 Row 1 m| Cell 2 Row 1 monospace | Cell 3 Row 1
| Cell 1 Row 2 with *bold* | Cell 2 Row 2 | Cell 3 Row 2
|====

If the first comment of the first row starts with "cols=", then the content of the comment gets placed between brackets right before the table.

Row comments starting with "cells=" get split on "," and become cell formatters.

Custom templates

You can use the template attribute to specify a custom erb template. The attribute value is used as a relative file path, resolved using the docdir attribute as base directory. The template receives a hash called feature containing the feature elements (scenarios, steps, examples, docstrings etc.).

Here is an example of a custom template rendering a table with one row per scenario :

mytemplate.erb

.<%= feature['name'] %>
|====
<%if feature.key?('scenarios') %><% feature['scenarios'].each do |scenario| %>| <%= scenario['name'] %>
<% end %>
<% else %>
| Nothing to show.
<% end %>
|====

assuming you place this template in the same directory as your asciidoc file, the following asciidoc content

gherkin::./simple.feature[template=mytemplate.erb]

//or this : (template is the first positional attribute)

gherkin::./simple.feature[mytemplate.erb]

would render like

Table 1. My feature title

Scenario title1

Scenario title2

Character Encoding

You can use attributes to define the encoding for reading the template file and the feature file.

You can define these attributes either in the block macro or at the document level.

template-encoding

Used to read the custom template file if specified.

encoding

Used to read the feature file.

Defining feature encoding

gherkin::./simple.feature[encoding=UTF-8]