irfanahmadin / cukedoctor

BDD living documentation using Cucumber and Asciidoctor

Cukedoctor

Enabling Behaviour driven documentation!

BDD living documentation using Cucumber and Asciidoctor based on Cucumber JSON execution output.

Table of Contents

• 1. Narrative
• 2. Story
• 3. Sample
• 4. Cukedoctor Living Documentation
• 5. Other Documentation Examples
• 6. Modules
  • 6.1. Maven plugin
  • 6.2. Standalone jar
  • 6.3. Converter
  • 6.4. Extension
  • 6.5. SPI example
• 7. Jenkins plugin
• 8. Distribution
• 9. Contributing

1. Narrative

In order to have awesome living documentation
As a bdd developer
I want to convert my test results into Asciidoc format.

2. Story

GIVEN I execute my cucumber tests using the json formatter

AND cucumber json output files are generated

WHEN I convert the files using Cukedoctor

THEN I should have awesome living documentation based on asciidoc.

3. Sample

The following cucumber feature:

Feature: Calculator

  Scenario: Adding numbers
   You can use *asciidoc markup* in _feature_ #description#.

   NOTE: This is a very important feature!

    #{IMPORTANT: Asciidoc markup inside *steps* must be surrounded by *curly brackets*.}
    Given I have numbers 1 and 2

   #{NOTE: You can use asciidoc in doc strings as well}
   #{TIP: Steps comments are placed *before* each steps}
   #cukedoctor-discrete
    When I sum the numbers using the following java code:
"""
[source,java]
----
    public class Calc {

      public long sum(int x, int y){
          return  x + y; //(1)
      }
  }
----
<1> This is an asciidoc callout inside a feature.
"""

    # {* this is a list of itens inside a feature step}
    # {* there is no multiline comment in gherkin}
    # {** second level list item}
    Then I should have 3 as result

Will be converted by Cukedoctor (after tests execution) into the following document:

Failing steps are rendered as follows:

4. Cukedoctor Living Documentation

As a proof of concept, Cukedoctor bdd tests output are rendered by itself:

• Cukedoctor documentation html

• Cukedoctor documentation pdf

• Default cucumber formatter html

Note	This documentation is published to gh-pages by travisci on each successful build.

5. Other Documentation Examples

Here are some bdd documentation examples generated by Cukedoctor:

Project	Living documentation
Asciidoctor	html / pdf
Cucumber (Ruby)	html / pdf
Cucumber JS	html / pdf
Jekyll	html / pdf
Sdkman	html / pdf

6. Modules

6.1. Maven plugin

If you use maven and execute your cucumber tests through maven you can use cukedoctor-maven plugin. For more details see cukedoctor-maven-plugin.

6.2. Standalone jar

To use Cukedoctor as a standalone jar you can download it here. For more details, see cukedoctor-main.

6.3. Converter

Cukedoctor converter is the basis for the above projects, it generates asciidoc files based on Cucumber json execution files. For more details see cukedoctor-converter.

6.4. Extension

Cukedoctor extension adds new features to generated documentation in order to let original document cleaner and make it easier to enable/disable those features. For more details see cukedoctor-extension.

6.5. SPI example

This module provides an example project to show how cukedoctor documentation can be extended and customized. For more details see cukedoctor-spi-example.

7. Jenkins plugin

Cukedoctor brings Living documentation to Jenkins via Cucumber living documentation plugin.

8. Distribution

Cukedoctor is available at Bintray and at Maven central.

Snapshots are available at maven central and published on each successful commit&build on travis.

You can use snapshots by adding the following snippets in pom.xml:

<repositories>
    <repository>
        <snapshots/>
        <id>snapshots</id>
        <name>libs-snapshot</name>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>

Tip	You can download snapshots directly from Sonatype here.

9. Contributing

• Found a bug? open an issue and attach your feature json output to it;

  • If you’re are Jedi then provide a test that reproduces the issue;

    • If you are Chuck Norris then send a pull request with the fix 👊

• Have an idea? open an issue and lets discuss it;

• Any form of feedback is more than welcome!