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: [email protected]
  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 only when using relative paths 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: [email protected]
  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: [email protected]
  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: [email protected]
  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: [email protected]
  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