com.arc_e_tect.gradle.gherkin.GherkinToAsciidocExtension

public abstract class GherkinToAsciidocExtension extends Object

DSL extension for the Gherkin-to-AsciiDoc Gradle plugin.

 gherkinToAsciidoc {
     sourceDirs.from('src/test/resources/features')                                // default
     includeSubDirs = true                                                         // default
     outputDir      = layout.buildDirectory.dir('generated-docs')                 // default
     outputFileName = 'features.adoc'                                             // default
     trackProgress  = false                                                        // default
     // glueCodeDirs.from('src/test/java/.../steps')                              // required when trackProgress = true
     groupByFeature = true                                                         // default; forced to true whenever trackProgress = true
     // snippetDir  = layout.buildDirectory.dir('generated-docs/features/snippets') // default
     // template    = file('templates/report.mustache')                            // optional
     // systemUnderTestVersion = 'v1.0.0'          // optional; default: project.version
     indexing       = IndexingMode.OFF                                             // default; requires includeSubDirs = true
     forceRewrite   = false                                                        // default; see getForceRewrite()
     consolidatedIndex = false                                                     // default; see getConsolidatedIndex()
     trackProgressHistory  = false                                                 // default; requires trackProgress = true
     // progressHistoryFile = layout.projectDirectory.file('gherkin-progress-history.ndjson') // default
     updateProgressHistory = trackProgressHistory                                  // default; see getUpdateProgressHistory()
     failOnDuplicateScenarios = true                                               // default; see getFailOnDuplicateScenarios()
 }

indexing, forceRewrite, and updateProgressHistory can each be overridden for the whole build from the command line, e.g. -PgherkinToAsciidoc.indexing=ci - see getIndexing(), getForceRewrite(), and getUpdateProgressHistory().

Field Summary

Fields

Modifier and Type

Field

Description

static final String

DEFAULT_OUTPUT_FILE_NAME

Default name of the generated AsciiDoc output file.

static final String

DEFAULT_PROGRESS_HISTORY_FILE_NAME

Default name of the persisted scenario progress history file.

static final String

DEFAULT_SNIPPET_DIR

Default relative path of the directory report snippets are written to.

static final String

DEFAULT_SOURCE_DIR

Default relative path of the source directory containing .feature files.

static final String

FORCE_REWRITE_OVERRIDE_PROPERTY

Name of the Gradle project property that overrides getForceRewrite() from the command line for every project in the build, e.g.

static final String

INDEXING_OVERRIDE_PROPERTY

Name of the Gradle project property that overrides getIndexing() from the command line for every project in the build, e.g.

static final String

NAME

Extension DSL block name, i.e.

static final String

UPDATE_PROGRESS_HISTORY_OVERRIDE_PROPERTY

Name of the Gradle project property that overrides getUpdateProgressHistory() from the command line for every project in the build, e.g.
Constructor Summary

Constructors

Constructor

Description

GherkinToAsciidocExtension()

For use by the Gradle-generated concrete subclass.
Method Summary

Modifier and Type

Method

Description

abstract org.gradle.api.provider.Property<Boolean>

getConsolidatedIndex()

In a multi-project Gradle build, whether getIndexing()'s Feature numbering (and, for IndexingMode.SCENARIO, its cross-file Scenario numbering too) is one continuous sequence spanning every project in the build, or an independent sequence - starting at 1 again - for each project.

abstract org.gradle.api.provider.Property<Boolean>

getFailOnDuplicateScenarios()

Whether generateFeatureDocs fails the build when two or more scenarios within the same project share a title.

abstract org.gradle.api.provider.Property<Boolean>

getForceRewrite()

Whether getIndexing() renumbers every Feature/Scenario from scratch (ignoring any existing numbers), or only numbers the ones that aren't already correctly numbered for the currently configured IndexingMode.

abstract org.gradle.api.file.ConfigurableFileCollection

getGlueCodeDirs()

Directories containing the Cucumber-JVM glue code (step definitions) used to determine whether a scenario's steps are implemented.

abstract org.gradle.api.provider.Property<Boolean>

getGroupByFeature()

Whether to group scenarios by their enclosing Feature in the generated AsciiDoc, instead of a flat list.

abstract org.gradle.api.provider.Property<Boolean>

getIncludeSubDirs()

Whether to recursively scan sub-directories of every configured directory in getSourceDirs().

abstract org.gradle.api.provider.Property<IndexingMode>

getIndexing()

Whether - and how - to number Feature/Scenario titles directly in the source .feature files.

abstract org.gradle.api.file.DirectoryProperty

getOutputDir()

Directory where the generated AsciiDoc file will be written.

abstract org.gradle.api.provider.Property<String>

getOutputFileName()

Name of the generated AsciiDoc file (without path).

abstract org.gradle.api.file.RegularFileProperty

getProgressHistoryFile()

File that the persisted scenario progress history is read from and, when getUpdateProgressHistory() is true, written back to.

abstract org.gradle.api.file.DirectoryProperty

getSnippetDir()

Directory that the listed.adoc/defined.adoc/implemented.adoc report snippets are written to when getTrackProgress() is true.

abstract org.gradle.api.file.ConfigurableFileCollection

getSourceDirs()

Source directories that contain the .feature files to process.

abstract org.gradle.api.file.RegularFileProperty

getSourceFile()

A single .feature file to process.

abstract org.gradle.api.provider.Property<String>

getSystemUnderTestVersion()

Version of the system under test that the reported Gherkin scenarios exercise, printed in the generated document as e.g.

abstract org.gradle.api.file.RegularFileProperty

getTemplate()

Optional Mustache template used to render the generated AsciiDoc file so that it references the report snippets via include:: directives, instead of embedding their content verbatim.

abstract org.gradle.api.provider.Property<Boolean>

getTrackProgress()

Whether to classify every scenario as listed, defined, or implemented and include a progress summary in the generated AsciiDoc.

abstract org.gradle.api.provider.Property<Boolean>

getTrackProgressHistory()

Whether to persist, across builds, a per-scenario history of when each scenario first reached listed, defined, and implemented status - surviving scenarios being moved between feature files, since the history is keyed by a fingerprint of the scenario's name rather than by feature file location.

abstract org.gradle.api.provider.Property<Boolean>

getUpdateProgressHistory()

Whether getProgressHistoryFile() is written back to disk after being updated with the current run's scenarios.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- NAME
  
  public static final String NAME
  
  Extension DSL block name, i.e. the name used to register the extension with the project.
  See Also:
  
  Constant Field Values
- DEFAULT_SOURCE_DIR
  
  public static final String DEFAULT_SOURCE_DIR
  
  Default relative path of the source directory containing .feature files.
  See Also:
  
  Constant Field Values
- DEFAULT_OUTPUT_FILE_NAME
  
  public static final String DEFAULT_OUTPUT_FILE_NAME
  
  Default name of the generated AsciiDoc output file.
  See Also:
  
  Constant Field Values
- DEFAULT_SNIPPET_DIR
  
  public static final String DEFAULT_SNIPPET_DIR
  
  Default relative path of the directory report snippets are written to.
  See Also:
  
  Constant Field Values
- DEFAULT_PROGRESS_HISTORY_FILE_NAME
  
  public static final String DEFAULT_PROGRESS_HISTORY_FILE_NAME
  
  Default name of the persisted scenario progress history file.
  See Also:
  
  Constant Field Values
- INDEXING_OVERRIDE_PROPERTY
  
  public static final String INDEXING_OVERRIDE_PROPERTY
  
  Name of the Gradle project property that overrides getIndexing() from the command line for every project in the build, e.g. -PgherkinToAsciidoc.indexing=ci. Takes precedence over any project's own configured indexing value. The value is matched against IndexingMode enum constant names case-insensitively.
  See Also:
  
  Constant Field Values
- FORCE_REWRITE_OVERRIDE_PROPERTY
  
  public static final String FORCE_REWRITE_OVERRIDE_PROPERTY
  
  Name of the Gradle project property that overrides getForceRewrite() from the command line for every project in the build, e.g. -PgherkinToAsciidoc.forceRewrite=true. Takes precedence over any project's own configured forceRewrite value. The value is parsed as a boolean.
  See Also:
  
  Constant Field Values
- UPDATE_PROGRESS_HISTORY_OVERRIDE_PROPERTY
  
  public static final String UPDATE_PROGRESS_HISTORY_OVERRIDE_PROPERTY
  
  Name of the Gradle project property that overrides getUpdateProgressHistory() from the command line for every project in the build, e.g. -PgherkinToAsciidoc.updateProgressHistory=true. Takes precedence over any project's own configured updateProgressHistory value. The value is parsed as a boolean.
  See Also:
  
  Constant Field Values
Constructor Details
- GherkinToAsciidocExtension
  
  public GherkinToAsciidocExtension()
  
  For use by the Gradle-generated concrete subclass.
Method Details
- getSourceDirs
  
  public abstract org.gradle.api.file.ConfigurableFileCollection getSourceDirs()
  
  Source directories that contain the .feature files to process. One or more directories may be configured, e.g. via sourceDirs.from(file('a'), file('b')). Mutually exclusive with getSourceFile().
  
  Returns:
  
  mutable file collection of feature file source directories
- getSourceFile
  
  public abstract org.gradle.api.file.RegularFileProperty getSourceFile()
  
  A single .feature file to process. Mutually exclusive with getSourceDirs().
  
  Returns:
  
  mutable file property for a single feature file
- getIncludeSubDirs
  
  public abstract org.gradle.api.provider.Property<Boolean> getIncludeSubDirs()
  
  Whether to recursively scan sub-directories of every configured directory in getSourceDirs(). Defaults to true. Forced to true whenever getTrackProgress() is true.
  
  Returns:
  
  mutable boolean property controlling recursive directory scanning
- getOutputDir
  
  public abstract org.gradle.api.file.DirectoryProperty getOutputDir()
  
  Directory where the generated AsciiDoc file will be written. Defaults to build/generated-docs.
  
  Returns:
  
  mutable directory property for the output directory
- getOutputFileName
  
  public abstract org.gradle.api.provider.Property<String> getOutputFileName()
  
  Name of the generated AsciiDoc file (without path). Defaults to "features.adoc".
  
  Returns:
  
  mutable string property for the output file name
- getTrackProgress
  
  public abstract org.gradle.api.provider.Property<Boolean> getTrackProgress()
  
  Whether to classify every scenario as listed, defined, or implemented and include a progress summary in the generated AsciiDoc. Defaults to false.
  Can only be enabled when getSourceDirs() and getGlueCodeDirs() are both configured; enabling it also implies getIncludeSubDirs().
  
  Returns:
  
  mutable boolean property controlling progress tracking
- getGlueCodeDirs
  
  public abstract org.gradle.api.file.ConfigurableFileCollection getGlueCodeDirs()
  
  Directories containing the Cucumber-JVM glue code (step definitions) used to determine whether a scenario's steps are implemented. One or more directories may be configured, e.g. via glueCodeDirs.from(file('a'), file('b')). Required when getTrackProgress() is true; ignored otherwise.
  
  Returns:
  
  mutable file collection of glue code directories
- getGroupByFeature
  
  public abstract org.gradle.api.provider.Property<Boolean> getGroupByFeature()
  
  Whether to group scenarios by their enclosing Feature in the generated AsciiDoc, instead of a flat list. Defaults to true. Forced to true whenever getTrackProgress() is true, in which case scenarios are grouped by feature within each of the listed/defined/implemented sections.
  
  Returns:
  
  mutable boolean property controlling grouping by feature
- getSnippetDir
  
  public abstract org.gradle.api.file.DirectoryProperty getSnippetDir()
  
  Directory that the listed.adoc/defined.adoc/implemented.adoc report snippets are written to when getTrackProgress() is true. Defaults to build/generated-docs/features/snippets.
  When getGroupByFeature() is true, snippets for a status with at least one scenario are written per feature, under <snippetDir>/<camelCaseFeatureTitle>/<status>.adoc.
  
  Returns:
  
  mutable directory property for the snippet output directory
- getTemplate
  
  public abstract org.gradle.api.file.RegularFileProperty getTemplate()
  
  Optional Mustache template used to render the generated AsciiDoc file so that it references the report snippets via include:: directives, instead of embedding their content verbatim. Only consulted when getTrackProgress() is true; ignored otherwise.
  When not set, the generated report looks exactly as it does without this property: scenario titles are embedded directly, with no include:: directives. The snippet files are still written either way.
  
  Returns:
  
  mutable file property for the Mustache template file
- getSystemUnderTestVersion
  
  public abstract org.gradle.api.provider.Property<String> getSystemUnderTestVersion()
  
  Version of the system under test that the reported Gherkin scenarios exercise, printed in the generated document as e.g. System Under Test version: v1.0.0. Defaults to the project's own version (as set in the build file or a properties file); set this property to override that default, e.g. when the scenarios target a different artifact than the one being built.
  
  Returns:
  
  mutable string property for the system-under-test version
- getIndexing
  
  public abstract org.gradle.api.provider.Property<IndexingMode> getIndexing()
  Whether - and how - to number Feature/Scenario titles directly in the source .feature files. Defaults to IndexingMode.OFF.
  
  IndexingMode.OFF - nothing is numbered (default).
  
  IndexingMode.FEATURE - every feature is numbered, e.g. Feature: 1 - User authentication.
  
  IndexingMode.SCENARIO - every scenario is numbered continuously across all feature files, e.g. Scenario: 1 - User logs in.
  
  IndexingMode.ALL - both are numbered, scenarios as <featureNumber>.<scenarioNumber>, e.g. Scenario: 1.1 - User logs in.
  
  IndexingMode.CI - indexing is skipped entirely; unlike IndexingMode.OFF, the source files aren't even stripped of prior numbering. See "gherkinToAsciidoc.indexing" below.
  
  Feature files are processed in the same order the generated report lists them in: for each source directory (directories themselves ordered alphabetically by path when more than one is configured), that directory's own feature files first - alphabetically by file name - and only then, when getIncludeSubDirs() is true, its sub-directories' files, each sub-directory visited the same way, alphabetically by name. Scenario numbers additionally follow document order within each file. A line whose existing number already reflects the currently configured mode is left untouched, rather than being renumbered to fit that processing order - see getForceRewrite() for exactly what "reflects the currently configured mode" means and how to opt out of it.
  
  IndexingMode.OFF and IndexingMode.CI are always allowed. IndexingMode.FEATURE, IndexingMode.SCENARIO, and IndexingMode.ALL are only allowed when getIncludeSubDirs() is true; when getGroupByFeature() is false, only IndexingMode.SCENARIO of those three is allowed.
  
  The "gherkinToAsciidoc.indexing" project property, when set (e.g. -PgherkinToAsciidoc.indexing=ci), overrides this property for every project in the build regardless of what any project configures here - typically used to force IndexingMode.CI in a CI pipeline so generateFeatureDocs never mutates source files there, without having to change the build script itself.
  Returns:
  
  mutable property for the indexing mode
- getForceRewrite
  
  public abstract org.gradle.api.provider.Property<Boolean> getForceRewrite()
  Whether getIndexing() renumbers every Feature/Scenario from scratch (ignoring any existing numbers), or only numbers the ones that aren't already correctly numbered for the currently configured IndexingMode. Defaults to false. Has no effect when getIndexing() is IndexingMode.OFF (which always strips every number, regardless) or IndexingMode.CI (which never touches anything, regardless).
  
  true - every Feature/Scenario number is recomputed from scratch, exactly as if none of them had ever been numbered before - the same behaviour as before this property existed.
  
  false (default) - a line whose existing number already matches the format getIndexing()'s mode would itself produce is left completely untouched: for a Feature, a single integer; for a Scenario/Scenario Outline, either a single integer (IndexingMode.SCENARIO) or <featureNumber>.<n> matching that scenario's own feature's number (IndexingMode.ALL). Every other numbered line - the wrong format, or a leftover from a previously configured, different indexing value - is stripped and renumbered, same as true. A newly added feature file that happens to sort alphabetically before already-numbered files is given the next number not already in use, rather than bumping every already-numbered file after it.
  
  For example, with indexing = IndexingMode.SCENARIO and forceRewrite = false, a Scenario already reading Scenario: 3 - ... keeps that number. Changing indexing to IndexingMode.ALL affords that same scenario a fresh number - its old 3 doesn't match ALL's <featureNumber>.<n> format, so it no longer "reflects" the currently configured mode.
  
  The "gherkinToAsciidoc.forceRewrite" project property, when set (e.g. -PgherkinToAsciidoc.forceRewrite=true), overrides this property for every project in the build regardless of what any project configures here.
  Returns:
  
  mutable boolean property controlling whether existing numbering is preserved
- getConsolidatedIndex
  
  public abstract org.gradle.api.provider.Property<Boolean> getConsolidatedIndex()
  In a multi-project Gradle build, whether getIndexing()'s Feature numbering (and, for IndexingMode.SCENARIO, its cross-file Scenario numbering too) is one continuous sequence spanning every project in the build, or an independent sequence - starting at 1 again - for each project. Defaults to false. Has no effect when getIndexing() is IndexingMode.OFF or IndexingMode.CI (neither numbers anything), and no effect on IndexingMode.ALL's Scenario numbering, which is already scoped per Feature - strictly finer-grained than per-project - regardless.
  
  false (default) - every project numbers its own features (and, in IndexingMode.SCENARIO mode, scenarios) from 1, independently of every other project in the build - so two projects maintained concurrently never fight over the same numbers, and a project's own numbers don't shift just because another project gained or lost a feature file.
  
  true - every project's features (and IndexingMode.SCENARIO scenarios) instead share one number space across the whole build, exactly as if every project's feature files had been passed to a single project's own generateFeatureDocs - the behaviour every version of this plugin had before this property existed. Set this when existing numbers already reference this shared, build-wide sequence and renumbering every project's features to start at 1 would be disruptive.
  
  Only affects a task that actually scans more than one project's feature files. The scoping happens within a single generateFeatureDocs invocation, over exactly the files that invocation collected - so it matters only in an "aggregator" layout, where one project's sourceDirs reach into several projects. In the more common "fan-out" layout, where the plugin is applied to every project and each task's sourceDirs resolve against its own project directory, no task ever sees another project's files: numbering already restarts at 1 in every project, and setting this to true is silently ignored rather than producing the build-wide sequence described above. See the README's "Multi-Project Builds" section for both layouts.
  
  Like getIndexing() and getForceRewrite(), this property is inherited from the root project's own gherkinToAsciidoc extension by default; a sub-project that configures it itself overrides that inherited default for itself only.
  Returns:
  
  mutable boolean property controlling whether indexing is consolidated build-wide or scoped per project
- getTrackProgressHistory
  
  public abstract org.gradle.api.provider.Property<Boolean> getTrackProgressHistory()
  
  Whether to persist, across builds, a per-scenario history of when each scenario first reached listed, defined, and implemented status - surviving scenarios being moved between feature files, since the history is keyed by a fingerprint of the scenario's name rather than by feature file location. Defaults to false.
  Requires getTrackProgress() to also be true; enabling this property while trackProgress is false fails generateFeatureDocs with a descriptive error. The history file configured via getProgressHistoryFile() is always read when this property is true, regardless of getUpdateProgressHistory().
  
  The plugin itself has no dependency on git or any other version control system; branch-based control over when to advance the history (e.g. "only on main") is a CI concern, expressed purely through getUpdateProgressHistory() - typically driven from a Gradle property set differently per branch in the CI pipeline itself.
  
  Returns:
  
  mutable boolean property controlling whether scenario progress history is tracked
- getProgressHistoryFile
  
  public abstract org.gradle.api.file.RegularFileProperty getProgressHistoryFile()
  
  File that the persisted scenario progress history is read from and, when getUpdateProgressHistory() is true, written back to. Defaults to gherkin-progress-history.ndjson directly in the project directory - deliberately not under build/, since this file is meant to be committed to version control so the history survives across checkouts. Only consulted when getTrackProgressHistory() is true.
  
  Returns:
  
  mutable file property for the progress history file
- getUpdateProgressHistory
  
  public abstract org.gradle.api.provider.Property<Boolean> getUpdateProgressHistory()
  
  Whether getProgressHistoryFile() is written back to disk after being updated with the current run's scenarios. Defaults to the same value as getTrackProgressHistory(). Only consulted when getTrackProgressHistory() is true; the history file is always read regardless of this property's value, so a build with this set to false still reports against the up-to-date-in-memory history, it simply doesn't persist it.
  Set this to false for branches/builds that shouldn't advance the committed history (e.g. feature branches or pull request builds), and leave it true (the default, once trackProgressHistory is enabled) for the branch(es) that should - typically expressed via the "gherkinToAsciidoc.updateProgressHistory" project property from the CI pipeline rather than hardcoded in the build script, since the plugin itself has no notion of which branch is currently checked out.
  
  The "gherkinToAsciidoc.updateProgressHistory" project property, when set (e.g. -PgherkinToAsciidoc.updateProgressHistory=true), overrides this property for every project in the build regardless of what any project configures here.
  
  Returns:
  
  mutable boolean property controlling whether the progress history file is written back
- getFailOnDuplicateScenarios
  
  public abstract org.gradle.api.provider.Property<Boolean> getFailOnDuplicateScenarios()
  
  Whether generateFeatureDocs fails the build when two or more scenarios within the same project share a title. Defaults to true.
  Titles are compared within each project, never across them: two microservices implementing the same cross-cutting concern legitimately carry the same scenario titles, and each keeps its own progress history for its own copy. Only a collision inside one project is a defect.
  
  A shared title is unsafe because ScenarioFingerprint identifies a scenario by its title alone; two scenarios that merely happen to share a title are indistinguishable to it, so persisting progress history for them would silently corrupt it - see DuplicateScenarioTitles for the full explanation. With the default true, generateFeatureDocs rejects the build outright the moment such a collision is found, before either the report or the history file is written.
  
  Set to false to let the build continue despite duplicate titles instead - every duplicate is still reported, as a warning, unconditionally (not only under --info, unlike the default's own pre-failure logging). Doing so also unconditionally disables progress history tracking for generateFeatureDocs, regardless of getTrackProgressHistory()'s own value: once duplicate titles are no longer guaranteed to fail the build, the fingerprint-keyed history can no longer be trusted, so it is never read, advanced, or written while this property is false. The generated report prominently warns about this whenever getTrackProgressHistory() is true.
  
  Returns:
  
  mutable boolean property controlling whether duplicate scenario titles fail the build

Class GherkinToAsciidocExtension

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

NAME

DEFAULT_SOURCE_DIR

DEFAULT_OUTPUT_FILE_NAME

DEFAULT_SNIPPET_DIR

DEFAULT_PROGRESS_HISTORY_FILE_NAME

INDEXING_OVERRIDE_PROPERTY

FORCE_REWRITE_OVERRIDE_PROPERTY

UPDATE_PROGRESS_HISTORY_OVERRIDE_PROPERTY

Constructor Details

GherkinToAsciidocExtension

Method Details

getSourceDirs

getSourceFile

getIncludeSubDirs

getOutputDir

getOutputFileName

getTrackProgress

getGlueCodeDirs

getGroupByFeature

getSnippetDir

getTemplate

getSystemUnderTestVersion

getIndexing

getForceRewrite

getConsolidatedIndex

getTrackProgressHistory

getProgressHistoryFile

getUpdateProgressHistory

getFailOnDuplicateScenarios