Configuration

SpecFlow's behaviour can be configured extensively. How to configure SpecFlow depends on the version of SpecFlow you are using.

SpecFlow 2.x

SpecFlow 2 is configured in your standard .NET configuration file, app.config, which is automatically added to your project.

SpecFlow 3.x

The configuration has been moved to a JSON file, specflow.json. This file is mandatory for .NET Core projects, and optional for projects using the Full Framework. When using the Full Framework, you can still use the app.config file, as with earlier versions of SpecFlow. If both the specflow.json and app.config files are available in a Full Framework project, specflow.json takes precedence.

Configuration Options

Apart from selecting your unit test provider, both configuration methods use the same options and general structure. The only difference is that SpecFlow 2 only uses the app.config file (XML) and SpecFlow 3 requires the specflow.json file (JSON) for .NET Core projects.

Configuration examples

The following 2 examples show the same option defined in the app.config in specflow.json formats:

app.config example:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="specFlow" type="TechTalk.SpecFlow.Configuration.ConfigurationSectionHandler, TechTalk.SpecFlow" />
  </configSections>
  <specFlow>
    <language feature="de-AT" />
  </specFlow>
</configuration>

specflow.json example:

{
    "language": {
        "feature": "de-AT"
    }
}

You can find more examples in the sample projects for SpecFlow.

Default Configuration

All SpecFlow configuration options have a default setting. When using the app.config method (Full Framework only), configuring your unit test provider (see below) is the most important configuration option required. Simple SpecFlow projects may not require any further configuration.

Configuring Your Unit Test Provider

SpecFlow 3

When working with SpecFlow 3, you can only configure your unit provider by adding the corresponding packages to your project. You will therefore need to add one of the following NuGet packages to your project to configure the unit test provider:

  • SpecRun.SpecFlow-3.0.0
  • SpecFlow.xUnit
  • SpecFlow.MsTest
  • SpecFlow.NUnit

Note: Make sure you do not add more than one of the unit test plugins to your project. If you do, an error message will be displayed.

SpecFlow 2

SpecFlow 2 is configured using the app.config file (Full Framework only). Enter your unit test provider in the unitTestProvider element in the specflow section, e.g.:

  <specFlow>
    <unitTestProvider name="MsTest" />
  </specFlow>

Configuration Elements

The same configuration elements are available in both the XML (app.config) and JSON (specflow.json) formats.

<language>

Use this section to define the default language for feature files and other language-related settings. For more details on language settings, see Feature Language.

Attribute Value Description

feature

culture name (“en-US”)

The default language of feature files added to the project. We recommend using specific culture names (e.g.: “en-US”) rather than generic (neutral) cultures (e.g.: “en”).
Default: en-US

tool

empty or culture name

Specifies the language that SpecFlow uses for messages and tracing. Uses the default feature language if empty and that language is supported; otherwise messages are displayed in English. (Note: Only English is currently supported.)
Default: empty

<bindingCulture>

Use this section to define the culture for executing binding methods and converting step arguments. For more details on language settings, see Feature Language.

Attribute Value Description

name

culture name (“en-US”)

Specifies the culture to be used to execute binding methods and convert step arguments. If not specified, the feature language is used.
Default: not specified

<unitTestProvider> (Full Framework only!)

Note: If you are using specflow.json to configure SpecFlow, this option is unavailable. See SpecFlow and .NET Core for information on adding the NuGet packages required to configure your unit test provider in this case.

Use this section to specify the unit test framework used by SpecFlow to execute acceptance criteria. You can either use one of the built-in unit test providers or you can specify the classes that implement custom unit test providers.

Attribute Value Description

name

Name of the unit test provider. See Unit Test Providers.

The name of the built-in unit test provider. If you specify this attribute, you don’t have to specify the other two.
Default: nunit

The following lists all supported providers with their name and generator provider class name:

Name Runtime Provider

specrun

SpecRunTestGeneratorProvider, see the SpecFlow+ documentation

nunit

NUnit3TestGeneratorProvider

nunit.2

NUnit2TestGeneratorProvider

xunit.1

XUnitGeneratorProvider

xunit

XUnit2GeneratorProvider

mstest.2008

MsTestGeneratorProvider

mstest

MsTest2010GeneratorProvider

mstest.v2

MsTestV2GeneratorProvider

generatorProvider

class name

Legacy option, unsupported from v2.0. Use <plugins> instead.

runtimeProvider

class name

Legacy option, unsupported from v2.0. Use <plugins> instead.

<generator>

Use this section to define unit test generation options.

Attribute Value Description

allowDebugGeneratedFiles

true|false

By default, the debugger is configured to step through the generated code. This helps you debug your feature files and bindings (see Debugging Tests). Disabled this option by setting this attribute to “true”.
Default: false

allowRowTests

true|false

Determines whether "row tests" should be generated for scenario outlines. This setting is ignored if the unit test framework does not support row based testing.
Default: true

generateAsyncTests

true|false

Determines whether the generated tests should support testing asynchronous code. This setting is currently only supported for the Silverlight platform.
Default: false

path

path relative to the project folder

Specifies the custom folder of the SpecFlow generator to be used if it is not in the standard path search list. See Setup SpecFlow Projects for details.
Default: not specified

dependencies

custom dependencies

Specifies the custom dependencies for the SpecFlow generator. See Plugins for details.
Default: not specified

<runtime>

Use this section to specify various test execution options.

Attribute Value Description

dependencies

custom dependencies

Specifies custom dependencies for the SpecFlow runtime. See Plugins for details.
Default: not specified

detectAmbiguousMatches

true|false

Legacy option, unsupported from v2.0.
Default: true

missingOrPendingStepsOutcome

Inconclusive| Ignore| Error

Determines how SpecFlow behaves if a step binding is not implemented or pending. See Missing, Pending or Improperly Configured Bindings.
Default: Inconclusive

obsoleteBehavior

None|Warn| Pending|Error

Determines how SpecFlow behaves if a step binding is marked with [Obsolete] attribute.
Default: Warn

stopAtFirstError

true|false

Determines whether the execution should stop when encountering the first error, or whether it should attempt to try and match subsequent steps (in order to detect missing steps).
Default: false

<trace>

Use this section to determine the SpecFlow trace output.

Attribute Value Description

traceSuccessfulSteps

true|false

Determines whether SpecFlow should trace successful step binding executions.
Default: true

traceTimings

true|false

Determines whether SpecFlow should trace execution time of the binding methods (only if the execution time is longer than the minTracedDuration value).
Default: false

minTracedDuration

TimeSpan (0:0:0.1)

Specifies a threshold for tracing the binding execution times.
Default: 0:0:0.1 (100 ms)

stepDefinitionSkeletonStyle

RegexAttribute| MethodNameUnderscores| MethodNamePascalCase| MethodNameRegex

Specifies the default step definition style.
Default: RegexAttribute

Listener

class name

Legacy option, unsupported from v2.0. Use <plugins> instead.

<stepAssemblies>

This section can be used to configure additional assemblies that contain external binding assemblies. The assembly of the SpecFlow project (the project containing the feature files) is automatically included. The binding assemblies must be placed in the output folder (e.g. bin/Debug) of the SpecFlow project, for example by adding a reference to the assembly from the project.

The following example registers an additional binding assembly (MySharedBindings.dll).

<specFlow>
  <stepAssemblies>
    <stepAssembly assembly="MySharedBindings" />
  </stepAssemblies>
</specFlow>

The <stepAssemblies> can contain multiple <stepAssembly> elements (one for each assembly), with the following attributes.

Attribute Value Description

assembly

assembly name

The name of the assembly containing bindings.

<plugins>

This section can be used to configure plugins that contain customisations. See Plugins for more details.

<specFlow>
  <plugins>
    <add name="MyPlugin" />
  </plugins>
</specFlow>

The <plugins> element can contain multiple <add> elements (one for each plugin), with the following attributes:

Attribute Value Description

name

plugin name

The name of the plugin containing the customisations.

path

path relative to the project folder

Specifies the custom folder of the SpecFlow plugin to be used if it is not in the standard path search list. See Plugins for details.
Default: not specified

type

Generator| Runtime| GeneratorAndRuntime

Specifies whether the plugin customises the generator, the runtime or both.
Default: GeneratorAndRuntime