Awesome
CoreBDD
BDD framework for xUnit.net
Getting started with CoreBDD
There are several ways to get started with CoreBDD. You can install the dotnet project template via
dotnet new -i corebdd.projecttemplate
Then create a new folder for your test project and run
dotnet new corebdd
Alternatively you can add CoreBDD to an existing xUnit test project via the nuget package
dotnet add package CoreBDD
There is also an optional Command Line tool for running tests with custom output, scaffolding test classes (features/scenarios/steps) and two-way code generation (Gherkin to CoreBDD tests and vice-versa). More documentation on the CLI is available at the bottom of this page.
dotnet tool install -g corebdd.commandline
Finally if you are using VSCode I have made some code-snippets available available here
Writing CoreBDD Tests
Following the usual calculator example, we can start with the following model to test
public class Calculator
{
public int Add(int x, int y) => x + y;
public int Subtract(int x, int y) => x - y;
}
We can define a Feature to collate a suite of scenarios by deriving from the Specification base class and decorating with the Feature attribute. Note both constructors are required to support the different test syntax styles.
[Feature("Calculator",
@"In order to avoid silly mistakes
As a math idiot
I want to be told the sum of two numbers")]
public class CalculatorFeature : Specification
{
public CalculatorFeature(SpecFixture context):base(context)
{
}
public CalculatorFeature()
{
}
}
Once we have created our base Feature, we have several different flavours for writing tests, first we can generate a scenario-per-class (similar to Cucumber style tests) with a method for each Given/When/Then step. To do this simply inherit from the new Feature class, decorate with an Example attribute and provide Given, When, Then methods that will execute in order
[Example("Add two numbers")]
public class AddTwoNumbers : CalculatorFeature
{
readonly Calculator calc;
public AddTwoNumbers(GivenWhenThenFixture state)
: base(state) => calc = new Calculator();
[Given("I have entered {0} into the calculator", 1)]
public void Given(int first) => Context.Given.First = first;
[And("I have also entered {0} into the calculator", 2)]
public void And(int second) => Context.Given.Second = second;
[When("I press add")]
public void When() => Context.When = calc.Add(Context.Given.First, Context.Given.Second);
[Then("the result should be {0}", 3)]
public void Then(int result) => Context.Result.ShouldBe(result);
}
You can also define scenarios in a single method using delgates for each of the steps and allowing for multiple scenarios to be defined within the same class
public class AdvancedCalculator : CalculatorFeature
{
Calculator calculator;
[Scenario("Multiply two numbers")]
public void MultiplyTwoNumbers()
{
Given("I have a calculator", () => calculator = new Calculator());
When("I key in 10", () => calculator.Key(10));
And("I key in 5 and press multiply", () => calculator.Multiply(5));
Then("It sets the Total to 50", () => calculator.Total.ShouldBe(50));
}
[Scenario("Divide two numbers")]
public void DivideTwoNumbers()
{
Given("I have a calculator", () => calculator = new Calculator());
When("I key in 42", () => calculator.Key(42));
And("I key in 5 and press divide", () => calculator.Deivide(5));
Then("It sets the Total to 42", () => calculator.Total.ShouldBe(42));
}
}
The method based syntax also supports data driven tests, using xUnit InlineData (class based scenarios don't support data driven tests just yet).
[ScenarioOutline("Divide two numbers")]
[Examples(10, 2, 5)]
[Examples(20, 4, 5)]
public void DivideTwoNumbers(int number, int divideby, int result)
{
Given($"I have a calculator", () => calculator = new Calculator());
When($"I key in {number}", () => calculator.Key(number));
And($"I key in {divideby} and press divide", () => calculator.Divide(divideby));
Then($"It sets the Total to {result}", () => calculator.Total.ShouldBe(result));
}
You can generate Gherkin specs from your tests using the CoreBDD.SpecGeneration extension library, either by calling from an application or command line tool and passing in the path to the assembly containing tests, or by hooking up your test project to generate the specs after the test run.
To do the latter, first reference the CoreBDD.SpecGeneration library
dotnet add package CoreBDD.SpecGeneration
Next create a Fixture class within your test project, and call GenerateSpecs.OutputFeatureSpecs within the Dispose method, passing in the Assembly (or path to the Assembly) and the output folder for the generated specs.
[CollectionDefinition("CoreBDD")]
public class Collection : ICollectionFixture<GenerateSpecsFixture> { }
public class GenerateSpecsFixture : IDisposable
{
public void Dispose()
{
GenerateSpecs.OutputFeatureSpecs(this.GetType().Assembly.Location, @"..\..\..\Specs\");
}
}
When the tests complete running, a FeatureName.feature file is generated under the Specs folder of the xUnit test project. It generates Gherkin specs for the feature and related scenarios. Example CalculatorFeature.feature :
Feature: Calculator
In order to avoid silly mistakes
As a math idiot
I want to be told the sum of two numbers
Scenario: Add two numbers
Given I have entered 1 into the calculator
And I have also entered 2 into the calculator
When I press add
Then the result should be 3
Scenario: Subtract two numbers
Given I have entered 5 into the calculator
And I have also entered 2 into the calculator
When I press minus
Then the result should be 3
Command Line Tool
The command line tool makes it easy to run tasks such as test execution with Gherkin style output, generating default feature and scenario test files and generating Gherkin feature files from existing tests, or generating tests from existing feature files.
Starting from scratch using the dotnet template and cli tools:
mkdir demobdd
cd demobdd
Next create the new CoreBDD project
dotnet new corebdd
Find CoreBDD tests in current and sub directories and execute tests
corebdd test
Run tests then generate Gherkin .feature files in specified location
corebdd test --specs --output ./Specs
Scaffold a CoreBDD feature class called 'Login' in current folder
corebdd generate feature --name login --namespace demobdd
Scaffold a CoreBDD scenario class called 'LoginToWebsite' under the 'Login' feature
corebdd generate scenario --name LoginToWebsite --feature login --namespace demobdd
Scaffold CoreBDD Tests from existing gherkin '.feature' files, specifiying location of feature files and target folder for generated tests. If you have been following using the 'corebdd' test example, delete the 'Features' folder (leaving the Specs folder with .feature files intact) then run:
corebdd generate tests --path ./Specs --output ./Features --namespace demobdd
You should now have test stubs regenerated using the .feature file scenarios.