Cucumber Living Documentation Plugin for Jenkins

BDD living documentation on your jenkins build via Cukedoctor.

Table of Contents

• 1. Introduction
• 2. Usage
• 3. Configuration
• 4. Accessing documentation
• 5. Documentation history
• 6. Jenkins pipeline step
• 7. Docker

1. Introduction

The Cucumber living documentation plugin basically scans for Cucumber json output files in jenkins workspace in order to generate living documentation from it.

Cucumber json output files are generated after Cucumber test using the json formatter:

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

ℹ️	plugin option replaced format option which was deprecated in newer cucumber versions.

Here is how a Cucumber feature look like in a documentation:

The feature file for sample above can be found here.

💡	For more example documentations see here.

2. Usage

After instalation the post build action Living documentation must be available on your jobs:

3. Configuration

Here are the possible plugin configuration:

4. Accessing documentation

When Cucumber living documentation plugin is enabled in your job it adds a link which will take you to current project documentation:

ℹ️	The plugin only stores the last generated documentation.

If you choice format all in configuration then two links will be rendered in the side panel:

❗	If you face the exception below: java.lang.ClassCircularityError: org/jruby/RubyClass you probably hit issue JENKINS-31019, to solve that you need to upgrade your installation to v1.640 or newer.

5. Documentation history

Since version 1.1.1 the plugin stores living documentation history.

⚠️	It reads the history from your job runs history, if you delete a job execution, the documentation will also be deleted from the history.

6. Jenkins pipeline step

Following is an example of pipeline step using this plugin:

node {
    checkout([$class: 'SubversionSCM', additionalCredentials: [], excludedCommitMessages: '', excludedRegions: '', excludedRevprop: '', excludedUsers: '', filterChangelog: false, ignoreDirPropChanges: false, includedRegions: '', locations: [[credentialsId: '', depthOption: 'infinity', ignoreExternalsOption: true, local: '.', remote: 'https://subversion.assembla.com/svn/cucumber-json-files/trunk']], workspaceUpdater: [$class: 'UpdateUpdater']])
    step([$class: 'CukedoctorPublisher', featuresDir: '', format: 'HTML', hideFeaturesSection: false, hideScenarioKeyword: false, hideStepTime: false, hideSummary: false, hideTags: false, numbered: true, sectAnchors: true, title: 'Living Documentation', toc: 'RIGHT'])
}

Since version 1.0.10 it is possible to use the livingDocs shortcut in pipeline DSL:

node {
    svn 'https://subversion.assembla.com/svn/cucumber-json-files/trunk'
    livingDocs()
}

Parameters should be declared as key: 'value' as example below:

node {
    svn 'https://subversion.assembla.com/svn/cucumber-json-files/trunk'
    livingDocs(featuresDir:'cukedoctor')
}

Or using the declarative pipeline:

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                svn 'https://subversion.assembla.com/svn/cucumber-json-files/trunk'
                livingDocs(featuresDir:'cukedoctor')
            }
        }
    }
}

7. Docker

An easy way to test this plugin is using a docker container, here are the steps (assumming you have docker installed):

1. Run the image:

   docker run -it -p 8080:8080 rmpestano/jenkins-living-documentation

2. Access localhot:8080/ and create a job

3. Configure this svn repository: https://subversion.assembla.com/svn/cucumber-json-files/trunk/

   ℹ️	This repository contains cucumber json sample files for the living documentation plugin

4. Add the Living documentation post build action;

5. Just run the job

💡	use featuresDir to point to specific json output, eg: /cukedoctor.

Job output should look like: