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