Child pages
  • Cucumber Living Documentation Plugin
Skip to end of metadata
Go to start of metadata

Plugin Information

View Cucumber Living Documentation on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Brings Cucumber living documentation to your continuous integration environment via Cukedoctor.



exclamation
This plugin only works if content security policy is relaxed as described in this section. For example start Jenkins with following argument:
-Dhudson.model.DirectoryBrowserSupport.CSP="sandbox allow-scripts; style-src 'unsafe-inline' *;script-src 'unsafe-inline' *;"

Since v2.2.1 the plugin doesn't need relaxed content security policy.

exclamation


Versions 2.x of the plugin uses Jenkins 2.73.1 as baseline (see issue #17), for older Jenkins installations use version 1.1.1 of this plugin, otherwise the exception java.lang.NoSuchMethodError: jnr.constants.platform.OpenFlags.defined()Z  will be raised when generating living documentation.


bulb
The PDF documentation generation is way faster on version 2.x.


How it works?

The plugin first looks for Cucumber json files, generated by your BDD tests, on your build workspace. After it parses the files and transforms them into html and pdf documentation making them available into your Jenkins build.

To generate Cucumber json output files use the json formatter:

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


Usage

After installing the plugin, you'll get a new Post build action entry named Living documentation:

Configuration

Here are the possible plugin configuration:

Accessing documentation

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


Documentation history


The plugin stores living documentation history:


docs history


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


Documentation examples

Here is a documentation example generated by the plugin based on a cucumber json output file:

The feature file for the above sample can be found here.

For more examples access here.


Jenkins pipeline step

Following is an example of pipeline step using this plugin:


node {
    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')
            }
        }
    }
}

 Docker

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

  1. Run the image: 

    docker run -it -p 8080:8080 rmpestano/jenkins-living-documentation
  2. Access http://localhost: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. Now you can run the job

use featuresDir to point to specific json output, a sub folder relative to workspace root dir, eg: cukedoctor.


Job output should look like:

Change Log

Version 2.2.1 (set 21, 2018)
  • #24 Can't change theme in html documentation
  • #25 Make the plugin work without content security policy
  • #26 Documentation not found via Living documentation link
  • #27 Update to Cukedoctor 1.2.1
Version 2.2.0 (set 20, 2018)
  • #22 Documentation history is lost on Jenkins restart
  • #23 Update to Cukedoctor 1.2.0
Version 2.1.2 (mar 24, 2018)
  • Failed to serialize hudson.model.Project#publishers for class hudson.model.FreeStyleProject (JENKINS-50271)
  • Fixes nested project references in Build actions (JENKINS-50273)
Version 2.1.1 (mar 11, 2018)
  • #20 Do not fail build when content security policy is not relaxed
Version 1.1.3 (mar 11, 2018)
  • #20 Do not fail build when content security policy is not relaxed
Version 2.1 (mar 09, 2018)
  • Merge with v1.1.2
Version 2.0 (mar 09, 2018)
  • #17 Use Jenkins 2.73 as baseline
Version 1.1.2 (mar 09, 2018)
  • #19  Fix link to documentation
  • #20 Downgrade Asciidoctor toolchain
Version 1.1.1 (mar 08, 2018)
  • #16 Allow usage with 'sandbox' content security policy
Version 1.1.0 (mar 08, 2018)


exclamation

Since this version the plugin will only work if content security policy is relaxed as described in this section.


  • #12 SECURITY-XXX
  • #13 Store documentation history
  • #14 Update to latest Asciidoctor
  • #15 Don't rely on System properties for CukedoctorConfig
Version 1.0.12 (oct 19, 2017)
  • #9 Pipeline dsl not found
Version 1.0.11 (sep 15, 2017)
  • #8 Updates to latest Asciidoctor.
Version 1.0.10 (aug 13, 2017)
  • #7 Simplifies pipeline script execution.
Version 1.0.9 (aug 7, 2017)
  • Fixes documentation link in job console.
Version 1.0.8 (aug 6, 2017)
Version 1.0.7 (fev 7, 2017)
  • Support for Jenkins 2 pipelines
Version 1.0.6 (out 24, 2016)
  • Updates to Cukedoctor 1.0.6;
  • Documentation layout configuration:
    1. Hide 'Features' section;
    2. Hide summary;
    3. Hide 'scenario' and 'scenario outline' keyword on generated documentation;
    4. Hide step execution time;
    5. Hide tags.
  • #17 Use Jenkins 2.73 as baseline

 nests project references in Build actions 

2 Comments

  1. For some reason it's not finding the cucumber.json that's in my workspace/target folder even though it's there. Do you have any ideas?Generating living documentation for GetAccess-CogDev-CucumberTests with the following arguments:
    Features dir: /var/lib/jenkins/workspace/CognitoIQ-Projects/CognitoIQ-Services/Tests/AcceptanceTests/InventoryServices-CucumberTests/CognitoDev/GetAccess-CogDev-CucumberTests/target/
    Format: all
    Toc: right
    Title: Living Documentation
    Numbered: true
    Section anchors: true

    No features Found in /var/lib/jenkins/workspace/CognitoIQ-Projects/CognitoIQ-Services/Tests/AcceptanceTests/InventoryServices-CucumberTests/CognitoDev/GetAccess-CogDev-CucumberTests/target/.
    Living documentation will not be generated.

    1. Hi Ebrahim Moshaya,

      what version are you using? version 1.0.3 has a fix for slave nodes.