java.lang.Object

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()
 }

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

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_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.
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>

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.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.

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
- 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
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

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

INDEXING_OVERRIDE_PROPERTY

FORCE_REWRITE_OVERRIDE_PROPERTY

Constructor Details

GherkinToAsciidocExtension

Method Details

getSourceDirs

getSourceFile

getIncludeSubDirs

getOutputDir

getOutputFileName

getTrackProgress

getGlueCodeDirs

getGroupByFeature

getSnippetDir

getTemplate

getSystemUnderTestVersion

getIndexing

getForceRewrite