Configuring the Build Step in YAML

Learn how to configure the build step in a YAML file.

Before you proceed, note that YAML is whitespace sensitive. Please copy and paste the example in a text editor with syntax highlighting (e.g. Notepad++).

For information on the YAML schema, see the Microsoft reference guide for Azure Pipelines YAML schema.

SpecFlow+LivingDoc custom build step YAML snippet

- task: SpecFlowPlus@0
  inputs:
    #generatorSource: 'FeatureFolder' # Required. Options: FeatureFolder, TestAssembly, FeatureData
    #projectFilePath:  # Required when generatorSource == FeatureFolder
    #testAssemblyFilePath:  # Required when generatorSource == TestAssembly
    #featureDataJsonFilePath:  # Required when generatorSource == FeatureData
    #projectName: # Optional
    #testExecutionJson: # Optional
    #projectLanguage: 'en' # Optional
    #workItemPrefix: # Optional
    #workItemUrlTemplate: # Optional
    #bindingAssemblies: # Optional
    #output: # Optional

Arguments

Argument Description
generatorSource FeatureFolder: Generate living documentation from feature files from the file system.
TestAssembly: Generate living documentation from a compiled SpecFlow test assembly.
FeatureData: Generate living documentation from pre-parsed features stored in a Feature Data JSON file.
projectFilePath The folder containing the feature files. Use the test project root folder if you want to include test execution results.
testAssemblyFilePath Relative or absolute path to the test assembly. Glob patterns are supported e.g.: MyProject\\**\\MyProject.dll
featureDataJsonFilePath Relative or absolute path to the feature data JSON. Glob patterns are supported e.g.: MyProject\\**\\FeatureData.json
projectName The name of the project visible in the viewer
testExecutionJson The absolute or relative path to the Test Execution JSON files generated by the SpecFlow.Plus.LivingDocPlugin. Glob patterns are supported
Important: In order to correctly display the execution results, you MUST provide the Test Project Root folder and not a subfolder (e.g. not the Features folder) in the projectFilePath parameter.
projectLanguage The language used by your Gherkin files. This is optional because in many cases the language can be auto-detected. You can read more about language options here.
workItemPrefix The special prefix for tags used to add a link to a work item in Azure DevOps.
For example, setting this to "DEVOPS_WI:" will allow you to tag a feature with @DEVOPS_WI:1234, and this tag will be converted to a link to work item 1234 when viewing the feature in LivingDoc.
workItemUrlTemplate The URL template to use to generate the external links. Example: https://dev.azure.com/fabrikam/FabrikamProj/_workitems/edit/{id}
bindingAssemblies Path to Binding Assemblies (newline delimited). Glob patters are supported e.g.: MyProject/**/MyBindings.dll.
TestAssembly: If your bindings are in the same assembly as your feature files, you don't have to specify this.
FeatureFolder, FeatureData: If your Bindings are in the same Test Assembly as your feature files, enter the path to your Test Assembly.
output Relative (from the working directory) or absolute path to the generated output file.

Non-LivingDoc specific parameters

  • enabled: boolean (not needed when true)
  • continueOnError: boolean (not needed when false)
  • condition:
selection YAML value
Only when all previous tasks have succeeded (nothing)
Even if a previous task has failed, unless the build was canceled succeededOrFailed()
Even if a previous task has failed, even if the build was canceled always()
Only when a previous task has failed failed()
Custom conditions (custom condition)
  • timeoutInMinutes: Specifies the maximum time, in minutes, that a task is allowed to execute before being canceled by server (zero value indicates an infinite timeout)

Examples

FeatureFolder example

- task: SpecFlowPlus@0
  displayName: 'LivingDoc with FeatureFolder generatorSource'
  inputs:
    generatorSource: 'FeatureFolder'
    projectFilePath: 'BookShop.AcceptanceTests'
    projectName: 'testName'
    testExecutionJson: 'BookShop.AcceptanceTests/**/TestExecution.json'
    projectLanguage: 'en'
    workItemPrefix: 'WI'
    workItemUrlTemplate: 'https://dev.azure.com/specflow/BookShop/_workitems/edit/{id}'
    bindingAssemblies: |
        BookShop.AcceptanceTests/**/BookShop.AcceptanceTests.dll
        BookShop.AcceptanceTests/**/MyBindings.dll
  enabled: false
  continueOnError: true
  condition: always()
  timeoutInMinutes: 10

TestAssembly example

- task: SpecFlowPlus@0
  displayName: 'LivingDoc with TestAssembly generatorSource'
  inputs:
    generatorSource: 'TestAssembly'
    testAssemblyFilePath: 'BookShop.AcceptanceTests/bin/**/BookShop.AcceptanceTests.dll'
    projectName: 'testName'
    testExecutionJson: 'BookShop.AcceptanceTests/**/TestExecution.json'
    projectLanguage: 'en'
    workItemPrefix: 'WI'
    workItemUrlTemplate: 'https://dev.azure.com/specflow/BookShop/_workitems/edit/{id}'
    bindingAssemblies: 'BookShop.AcceptanceTests/**/MyBindings.dll'
  enabled: false
  continueOnError: true
  condition: always()
  timeoutInMinutes: 10

FeatureData example

- task: SpecFlowPlus@0
  displayName: 'LivingDoc with FeatureData generatorSource'
  inputs:
    generatorSource: 'FeatureData'
    featureDataJsonFilePath: './**/FeatureData.json'
    testExecutionJson: 'BookShop.AcceptanceTests/**/TestExecution.json'
    workItemPrefix: 'WI'
    workItemUrlTemplate: 'https://dev.azure.com/specflow/BookShop/_workitems/edit/{id}'
    bindingAssemblies: |
        BookShop.AcceptanceTests/**/BookShop.AcceptanceTests.dll
        BookShop.AcceptanceTests/**/MyBindings.dll
  enabled: false
  continueOnError: true
  condition: always()
  timeoutInMinutes: 10

Example of output

Specify output file name as MyFeatureData.json and place it in the LivingDoc directory. If the directory is not exists, the tool will create it.

- task: SpecFlowPlus@0
  displayName: 'LivingDoc with custom output'
  inputs:
    generatorSource: 'FeatureFolder'
    projectFilePath: 'BookShop.AcceptanceTests'
    projectName: 'testName'
    testExecutionJson: 'BookShop.AcceptanceTests/**/TestExecution.json'
    projectLanguage: 'en'
    workItemPrefix: 'WI'
    workItemUrlTemplate: 'https://dev.azure.com/specflow/BookShop/_workitems/edit/{id}'
    bindingAssemblies: |
        BookShop.AcceptanceTests/**/BookShop.AcceptanceTests.dll
        BookShop.AcceptanceTests/**/MyBindings.dll
    output: 'LivingDoc/MyFeatureData.json'
  enabled: false
  continueOnError: true
  condition: always()
  timeoutInMinutes: 10