= Cukedoctor :page-layout: base :toc: preamble :source-language: java :icons: font :linkattrs: :sectanchors: :sectlink: :numbered: :imagesdir: img :doctype: book :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning:

[quote]

---

Enabling Behaviour driven documentation!

---

image:https://github.com/rmpestano/cukedoctor/actions/workflows/ci.yml/badge.svg[Build Status, link=https://github.com/rmpestano/cukedocor/actions/workflows/ci.yml] image:https://coveralls.io/repos/rmpestano/cukedoctor/badge.svg?branch=master&service=github[Coverage, link=https://coveralls.io/r/rmpestano/cukedoctor] image:https://maven-badges.herokuapp.com/maven-central/com.github.cukedoctor/cukedoctor/badge.svg["Maven Central",link="http://search.maven.org/#search|ga|1|cukedoctor"] image:https://sonarcloud.io/api/project_badges/measure?project=com.github.cukedoctor:cukedoctor&metric=alert_status["Sonar", link="https://sonarcloud.io/dashboard?id=com.github.cukedoctor%3Acukedoctor"]

BDD living documentation using http://cukes.info/[Cucumber] and http://asciidoctor.org[Asciidoctor] based on Cucumber http://www.relishapp.com/cucumber/cucumber/docs/formatters/json-output-formatter[JSON execution output].

[.text-right] https://goo.gl/Yp3NiU[Read this page in asciidoc for better reading experience]

== Narrative

[quote]

---

In order to have awesome living documentation + As a bdd developer + I want to convert my test results into http://asciidoctor.org/docs/what-is-asciidoc/[Asciidoc format^].

---

== Story

---

[big]#GIVEN# I execute my cucumber tests using the json formatter

[BIG]#AND# cucumber json output files are generated

[big]#WHEN# I convert the files using Cukedoctor

[big]#THEN# I should have awesome living documentation based on asciidoc.

---

== Sample

image:cukedoctor-sample.png[]

The feature file for the above sample can be https://github.com/database-rider/database-rider/blob/master/rider-core/src/test/resources/features/seeding/seeding-database.feature#L2[found here^].

Failing steps are rendered as follows:

image:cukedoctor-sample-with-error.png[]

== Cukedoctor Living Documentation

As a proof of concept, https://github.com/rmpestano/cukedoctor/tree/master/cukedoctor-converter/src/test/java/com/github/cukedoctor/bdd/cukedoctor[Cukedoctor bdd tests^] output are rendered by itself:

• http://rmpestano.github.io/cukedoctor/cukedoctor-documentation.html?theme=foundation[Cukedoctor documentation html^]
• http://rmpestano.github.io/cukedoctor/cukedoctor-documentation.pdf[Cukedoctor documentation pdf^]
• http://rmpestano.github.io/cukedoctor/cukedoctor/default/cukedoctor.html[Default cucumber formatter html^]

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

== Other Documentation Examples

Here are some bdd documentation examples generated by Cukedoctor:

[cols="1v,1v,lv"] |=== |Project | Living documentation

|https://github.com/database-rider/databae-rider[Database Rider^] |https://database-rider.github.io/database-rider/latest/documentation.html?theme=foundation[html^] / https://database-rider.github.io/database-rider/latest/documentation.pdf[pdf^]

|https://github.com/asciidoctor/asciidoctor[Asciidoctor^] |http://rmpestano.github.io/cukedoctor/asciidoctor/asciidoctor-documentation.html[html^] / http://rmpestano.github.io/cukedoctor/asciidoctor/asciidoctor-documentation.pdf[pdf^]

|https://github.com/cucumber[Cucumber (Ruby)^] |http://rmpestano.github.io/cukedoctor/cucumber/cucumber-documentation.html[html^] / http://rmpestano.github.io/cukedoctor/cucumber/cucumber-documentation.pdf[pdf^]

|https://github.com/cucumber/cucumber-js[Cucumber JS^] |http://rmpestano.github.io/cukedoctor/cucumber-js/cucumber-js-documentation.html[html^] / http://rmpestano.github.io/cukedoctor/cucumber-js/cucumber-js-documentation.pdf[pdf^]

|https://github.com/jekyll/jekyll[Jekyll^] |http://rmpestano.github.io/cukedoctor/jekyll/jekyll-documentation.html[html^] / http://rmpestano.github.io/cukedoctor/jekyll/jekyll-documentation.pdf[pdf^]

|https://github.com/sdkman/sdkman-cli[Sdkman^] |http://rmpestano.github.io/cukedoctor/sdkman/sdkman-documentation.html[html^] / http://rmpestano.github.io/cukedoctor/sdkman/sdkman-documentation.pdf[pdf^]

|===

== Cukedoctor Converter

Cukedoctor converter is the basis for other modules, it generates asciidoc files based on Cucumber json execution files.

=== Usage

Just declare the converter in your pom.xml:

[source, xml]

<dependency> <groupId>com.github.cukedoctor</groupId> <artifactId>cukedoctor-converter</artifactId> <version>3.7.0</version> </dependency> ----

=== Example

[source, java]

@Test public void shouldSaveDocumentationIntoDisk(){ List<String> pathToCucumberJsonFiles = FileUtil.findJsonFiles("target/test-classes/json-output/"); List<Feature> features = FeatureParser.parse(pathToCucumberJsonFiles); DocumentAttributes attrs = GlobalConfig.getInstance().getDocumentAttributes; attrs.toc("left").backend("html5") .docType("book") .icons("font") .sourceHighlighter("coderay") .docTitle("Documentation Title") .sectAnchors(true).sectLink(true);

CukedoctorConverter converter = Cukedoctor.instance(features, attrs);
converter.setFilename("target/living_documentation.adoc");

converter.saveDocumentation();
assertThat(FileUtil.loadFile("target/living_documentation.adoc")).exists();

}

[IMPORTANT]

To generate cucumber .json output files just execute your BDD tests with json formatter, example:

[source,java]

@RunWith(Cucumber.class) @CucumberOptions(plugin = {"json:target/cucumber.json"} )

======

=== Introduction Chapter

You can add a custom introduction chapter to your living documentations by placing a file named cukedoctor-intro.adoc anywhere on your classpath.

The content of the file will be placed between Documentation title and summary section. Here's an example of cukedoctor-intro.adoc:

---

= This is a sample introduction chapter

Introduction chapter is the place where you can insert custom content for your living documentation.

=== Sub section Introduction chapter can have subsections

Here is rendered documentation:

image:cukedoctor-intro.png[]

=== Internationalization

Cukedoctor can use internationalization in two flavours:

==== Reading features

Cucumber feature languages are provided via comments in a feature file, https://github.com/cucumber/cucumber/wiki/Spoken-languages[see here^] for examples.

Another way of setting the language is by using the @language-<language> tag:

.i18n.feature.tag

@language-fr Fonctionnalité: Calculateur

Scénario: Addition de nombres

---

where <language> can be one of the supported locales, en, es, fr, ge and pt.

WARNING: Please notice that the tag @language-<language> is not part of Cucumber. Meaning that you still need to setup Cucumber for i18n. the @language-<language> tag is part of Cukedoctor and serves as a convenient replacement for the # language: <language> comment, which is not supported anymore by Cucumber in JSON files.

If your feature language is not supported by Cukedoctor you can https://github.com/rmpestano/cukedoctor/tree/master/cukedoctor-converter/src/main/resources/i18n[contribute it here^] or use a custom bundle.

==== Custom resource bundle

Another way of internationalization is to provide a custom bundle.

If you do so Cukedoctor will ignore feature language and will use provided resource bundle.

The name of the file must be cukedoctor.properties and can be anywhere in your classpath.

Here are the key values you must provide to customize your documentation:

---

#sections title.features = Features title.summary = Summary title.scenario = Scenario

#summary summary.steps = Steps summary.total = Totals summary.duration = Duration

#result result.passed = Passed result.failed = Failed result.skipped = Skipped result.pending = Pending result.undefined= Undefined result.missing = Missing

---

==== Supported locales

Cukedoctor currently supports the following locales en, es, fr, ge and pt.

Here are the https://github.com/rmpestano/cukedoctor/tree/master/cukedoctor-converter/src/main/resources[supported locales^]

=== Skip features

In order to ignore features and not process them in generated documentation you can use @skipDocs tag:

.ignored.feature

@skipDocs Feature: Calculator

Scenario: Adding numbers

=== Feature ordering

To change the order features will be rendered in living documentation you can add an order comment in cucumber-jvm 1.x only:

.ordered.feature.comment

order: 1

Feature: Calculator

Scenario: Adding numbers

---

Or in cucumber-jvm 2.x and later, with an order tag:

.ordered.feature.tag

@order-1 Feature: Calculator

Scenario: Adding numbers

---

=== Enriching documentation

==== Asciidoc markup in comments

To enrich the documentation one can use asciidoc markup inside Cucumber feature files, consider the following feature:

.feature without enrichment

Feature: Calculator

Scenario: Adding numbers You can asciidoc markup in feature description.

Given I have numbers 1 and 2
When I sum the numbers
Then I should have 3 as result

---

It will be rendered by Cukedoctor as follows:

image::no-enrich.png[]

Now if you want to enrich your living documentation you can use asciidoc syntax in your feature:

.enriched 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: Steps comments are placed *before* each steps so this comment is for the *WHEN* step.}

When I sum the numbers

# {* this is a li