Package com.arc_e_tect.gradle.gherkin

Class GenerateFeatureDocsTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
com.arc_e_tect.gradle.gherkin.GenerateFeatureDocsTask
All Implemented Interfaces:
Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.TaskInternal, org.gradle.api.Named, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.util.Configurable<org.gradle.api.Task>
@DisableCachingByDefault(because="Generated documentation depends on source file content and is cheap to regenerate") public abstract class GenerateFeatureDocsTask extends org.gradle.api.DefaultTask
Gradle task that scans .feature files and writes all scenario titles to a single AsciiDoc file.

Caching is intentionally disabled: the output depends entirely on the contents of the feature files and regeneration is cheap.

Either getSourceDirs() or getSourceFile() must be configured, but not both. When neither is set the task falls back to the default source directory ("src/test/resources/features") relative to the project directory.

When getTrackProgress() is enabled, every scenario is classified as listed, defined, or implemented by cross-referencing its steps against the step definitions found in getGlueCodeDirs().

When getTrackProgressHistory() is also enabled, a per-scenario history of when each scenario first reached each of those three statuses is loaded from getProgressHistoryFile(), advanced with the current run's scenarios, and - only when getUpdateProgressHistory() resolves to true - written back.

generate() runs up to three scan-shaped phases - reindexing (only when indexing is active), parsing (always), and glue code scanning (only when getTrackProgress() is true) - each announced with its own LIFECYCLE banner and reported on periodically via ScanProgressReporter, using that class's own default throttle (every 50 items or every 2 seconds) unmodified, so a consumer watching the build knows the task is still alive on a large feature tree.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields inherited from interface org.gradle.api.Task

    TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    GenerateFeatureDocsTask()
    Creates a new task instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    generate()
    Task action: collects .feature files, parses scenarios, and writes them to the configured AsciiDoc output file.
    abstract org.gradle.api.provider.Property<Boolean>
    getForceRewrite()
    Whether getIndexing() renumbers every Feature/Scenario from scratch, or only the ones not already correctly numbered for the currently configured IndexingMode.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getGlueCodeDirs()
    Directories containing the Cucumber-JVM glue code (step definitions).
    abstract org.gradle.api.provider.Property<Boolean>
    getGroupByFeature()
    Whether to group scenarios by their enclosing Feature instead of a flat list.
    abstract org.gradle.api.provider.Property<Boolean>
    getIncludeSubDirs()
    Whether to recursively scan sub-directories of every 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
    getProjectDirectory()
    Root directory of the project, used to resolve the default source directory when neither getSourceDirs() nor getSourceFile() is set.
    abstract org.gradle.api.file.DirectoryProperty
    getSnippetDir()
    Directory that report snippets (listed.adoc/defined.adoc/implemented.adoc) are written to when getTrackProgress() is true.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getSourceDirs()
    Source directories containing the .feature files to process.
    abstract org.gradle.api.file.RegularFileProperty
    getSourceFile()
    Optional 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 report so that it references the snippets via include:: directives instead of embedding their content verbatim.
    abstract org.gradle.api.provider.Property<Boolean>
    getTrackProgress()
    Whether to classify scenarios 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.
    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 org.gradle.api.DefaultTask

    compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService

    Methods inherited from class org.gradle.api.internal.AbstractTask

    acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.gradle.api.Task

    doNotTrackState, notCompatibleWithConfigurationCache

  • Constructor Details

    • GenerateFeatureDocsTask

      @Inject public GenerateFeatureDocsTask()
      Creates a new task instance. Invoked by Gradle's dependency injection infrastructure.

  • Method Details

    • getSourceDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getSourceDirs()
      Source directories containing the .feature files to process. One or more directories may be configured. Mutually exclusive with getSourceFile().
      Returns:
      mutable file collection of feature file source directories

    • getSourceFile

      @Optional @InputFile @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getSourceFile()
      Optional single .feature file to process. Mutually exclusive with getSourceDirs().
      Returns:
      mutable file property for a single feature file

    • getIncludeSubDirs

      @Input public abstract org.gradle.api.provider.Property<Boolean> getIncludeSubDirs()
      Whether to recursively scan sub-directories of every directory in getSourceDirs().
      Returns:
      mutable boolean property controlling recursive directory scanning

    • getOutputDir

      @OutputDirectory public abstract org.gradle.api.file.DirectoryProperty getOutputDir()
      Directory where the generated AsciiDoc file will be written.
      Returns:
      mutable directory property for the output directory

    • getOutputFileName

      @Input public abstract org.gradle.api.provider.Property<String> getOutputFileName()
      Name of the generated AsciiDoc file (without path).
      Returns:
      mutable string property for the output file name

    • getTrackProgress

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTrackProgress()
      Whether to classify scenarios as listed, defined, or implemented and include a progress summary in the generated AsciiDoc.
      Returns:
      mutable boolean property controlling progress tracking

    • getGlueCodeDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getGlueCodeDirs()
      Directories containing the Cucumber-JVM glue code (step definitions). One or more directories may be configured. Required when getTrackProgress() is true.
      Returns:
      mutable file collection of glue code directories

    • getGroupByFeature

      @Input public abstract org.gradle.api.provider.Property<Boolean> getGroupByFeature()
      Whether to group scenarios by their enclosing Feature instead of a flat list. When getTrackProgress() is true, grouping additionally splits report snippets by feature (see getSnippetDir()).
      Returns:
      mutable boolean property controlling grouping by feature

    • getSnippetDir

      @OutputDirectory public abstract org.gradle.api.file.DirectoryProperty getSnippetDir()
      Directory that report snippets (listed.adoc/defined.adoc/implemented.adoc) are written to when getTrackProgress() is true.
      Returns:
      mutable directory property for the snippet output directory

    • getTemplate

      @Optional @InputFile @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getTemplate()
      Optional Mustache template used to render the report so that it references the snippets via include:: directives instead of embedding their content verbatim. Only consulted when getTrackProgress() is true; ignored otherwise.
      Returns:
      mutable file property for the Mustache template file

    • getSystemUnderTestVersion

      @Input 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.
      Returns:
      mutable string property for the system-under-test version

    • getIndexing

      @Input public abstract org.gradle.api.provider.Property<IndexingMode> getIndexing()
      Whether - and how - to number Feature/Scenario titles directly in the source .feature files. IndexingMode.OFF and IndexingMode.CI are always allowed; IndexingMode.FEATURE, IndexingMode.SCENARIO, and IndexingMode.ALL are only allowed when getIncludeSubDirs() is true, and when getGroupByFeature() is false, only IndexingMode.SCENARIO of those three is allowed.
      Returns:
      mutable property for the indexing mode

    • getForceRewrite

      @Input public abstract org.gradle.api.provider.Property<Boolean> getForceRewrite()
      Whether getIndexing() renumbers every Feature/Scenario from scratch, or only the ones not already correctly numbered for the currently configured IndexingMode. Has no effect when getIndexing() is IndexingMode.OFF or IndexingMode.CI.
      Returns:
      mutable boolean property controlling whether existing numbering is preserved

    • getTrackProgressHistory

      @Input 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. Requires getTrackProgress() to also be true.
      Returns:
      mutable boolean property controlling whether scenario progress history is tracked

    • getProgressHistoryFile

      @Internal 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. Deliberately not declared as an @InputFile/@OutputFile: the file legitimately may not exist yet (treated as an empty history, not an error) and is only conditionally written back, so it's read and written directly in generate() instead of through Gradle's up-to-date checking.
      Returns:
      mutable file property for the progress history file

    • getUpdateProgressHistory

      @Input 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. Only consulted when getTrackProgressHistory() is true; the history file is always read regardless.
      Returns:
      mutable boolean property controlling whether the progress history file is written back

    • getProjectDirectory

      @Internal public abstract org.gradle.api.file.DirectoryProperty getProjectDirectory()
      Root directory of the project, used to resolve the default source directory when neither getSourceDirs() nor getSourceFile() is set.
      Returns:
      mutable directory property for the project root directory

    • generate

      public void generate()
      Task action: collects .feature files, parses scenarios, and writes them to the configured AsciiDoc output file.