A lightweight Behaviour Driven Development (BDD) framework for .NET that'll fit how you want to test.
- Describe behaviour in plain text using the Gherkin business language, i.e. Given, When, Then.
- Easily execute the behaviour against matching F# 'ticked' methods, or attribute-tagged C# or F# methods.
- Run via your normal test runners or plugins (xUnit, NUnit or standalone)
- Set breakpoints in the scenarios, step definitions or your code and go (setting breakpoints in the Gherkin is currently not supported in .NET Standard version)
Example video: http://www.youtube.com/watch?v=UuTL3nj9fIE
Simply reference TickSpec via NuGet or Paket, download the assembly or build the project from source.
- The binary should work cleanly on any .NET Standard 2.0, .NET 4.5 or later environment.
- The TickSpec solution file works with Visual Studio 2017.
- Historically, Silverlight was supported; this support and the related examples were removed in 2017 (but remain in the commit history for the archeologically inclined)
- Useful samples are available in the Examples folder https://github.com/fsprojects/TickSpec/tree/master/Examples/ and depending your choice, this one is a good start : https://github.com/fsprojects/TickSpec/tree/master/Examples/ByFramework
Feature: Refunded or replaced items should be returned to stock
Scenario: Refunded items should be returned to stock
Given a customer buys a black jumper
And I have 3 black jumpers left in stock
When he returns the jumper for a refund
Then I should have 4 black jumpers in stock
type StockItem = { Count : int }
let mutable stockItem = { Count = 0 }
let [<Given>] ``a customer buys a black jumper`` () = ()
let [<Given>] ``I have (.*) black jumpers left in stock`` (n:int) =
stockItem <- { stockItem with Count = n }
let [<When>] ``he returns the jumper for a refund`` () =
stockItem <- { stockItem with Count = stockItem.Count + 1 }
let [<Then>] ``I should have (.*) black jumpers in stock`` (n:int) =
let passed = (stockItem.Count = n)
Debug.Assert(passed)
type StockItem = { Count : int }
let [<Given>] ``a customer buys a black jumper`` () = ()
let [<Given>] ``I have (.*) black jumpers left in stock`` (n:int) =
{ Count = n }
let [<When>] ``he returns the jumper for a refund`` (stockItem:StockItem) =
{ stockItem with Count = stockItem.Count + 1 }
let [<Then>] ``I should have (.*) black jumpers in stock`` (n:int) (stockItem:StockItem) =
let passed = (stockItem.Count = n)
Debug.Assert(passed)
public class StockStepDefinitions
{
private StockItem _stockItem;
[Given(@"a customer buys a black jumper")]
public void GivenACustomerBuysABlackJumper()
{
}
[Given(@"I have (.*) black jumpers left in stock")]
public void GivenIHaveNBlackJumpersLeftInStock(int n)
{
_stockItem = new StockItem() { Count = n };
}
[When(@"he returns the jumper for a refund")]
public void WhenHeReturnsTheJumperForARefund()
{
_stockItem.Count += 1;
}
[Then(@"I should have (.*) black jumpers in stock")]
public void ThenIShouldHaveNBlackJumpersInStock(int n)
{
Debug.Assert(_stockItem.Count == n);
}
}
Arguments to Step Methods will be converted from string
to the declared types of the Step Method parameters when possible.
The following conversions are supported:
Enum
typesUnion
types with no parametersNullable<T>
types where the innerT
type can be converted fromstring
Tuple
types where each element can be converted fromstring
- Array types
T []
whereT
can be converted fromstring
and the originalstring
is comma delimited - Types supported by
System.Convert.ChangeType
A table may be passed as an argument to a Step Method:
When a market place has outright orders:
| Contract | Bid Qty | Bid Price | Offer Price | Offer Qty |
| V1 | 1 | 9505 | | |
| V2 | | | 9503 | 1 |
The parameter can be declared with type Table
:
let [<When>] ``a market place has outright orders:`` (table:Table) =
outrightOrders <- toOrders table
Alternatively, the parameter can be converted to an array of records, or other type with constructor parameters supported by the Type Conversions
type OrderRow = { Contract: string; BidQty: string; BidPrice: string; OfferPrice: string; OfferQty: string }
let [<When>] ``a market place has outright orders:`` (orderRows: OrderRow[]) =
outrightOrders <- toOrders orderRows
The Table
parameter must appear after any regex capture parameters, and before any Functional Injection
parameters:
let [<Given>] ``A market place``() =
createMarketPlace()
let [<When>] ``a market place has outright (.*) orders:``
(orderType: string) # captured
(table: Table) # table
(maketPlace: MarketPlace) # injected
=
...
A bullet list may be passed to a Step Method similarly to a Table:
Scenario: Who is the one?
Given the following actors:
* Keanu Reeves
* Bruce Willis
* Johnny Depp
When the following are not available:
* Johnny Depp
* Bruce Willis
Then Keanu Reeves is the obvious choice
The parameter type must be an array type supported by the Type Conversions:
let [<Given>] ``the following actors:`` (actors : string[]) =
availableActors <- Set.ofArray actors
As shown in Step definitions (F# without mutable field), TickSpec also allows one to request additional parameters along with the captures from the regex holes in the step name as per typical Gherkin based frameworks. Such additional parameters can be fulfilled via the following mechanisms:
-
Instances returned from Step Method return values: This involves generating and stashing an instance in one of the preceding steps in the scenario. Typically this is achieved by returning the instance from the Step Method. Whenever a step has a return value, the the value is saved under it's type (the return type of the Step Method controls what the type is). Multiple values can be returned from a Step Method by returning a tuple. There can be only one value per type stashed per scenario run. When a parameter is being resolved, TickSpec first attempts to resolve from this type-to-instance caching Dictionary.
-
Resolving dependencies: If an instance cannot be located in the type-to-instance cache based on a preceding step having stashed the value, TickSpec will attempt to use the 'widest' constructor (the one with the most arguments) of the required type to instantiate it. Any input arguments to the constructor are all resolved recursively using the same mechanism. Any constructed instances are also cached in the type-to-instance cache, so next time it will return the same instance.
-
Accessing scenario metadata: You can access contextual information about the scenario within which a step definition is executing (e.g. tags). To do this, add a parameter of type
ScenarioMetadata
in the step definition argument list (or in a constructor parameter list of a dependency) scenario information (e.g. tags), then you can referenceScenarioMetadata
in your method argument (or in constructor of dependencies) and you will get an instance describing the scenario which is invoked.
The lifetime of instances is per-scenario:- Each scenario run starts an empty type-to-instance cache, and at the end of the scenario the cache gets cleared. Moreover, if any instance is IDisposable
, Dispose
will be called.
See the example projects DependencyInjection
and FunctionalInjection
for typical and advanced examples of using this mechanism.
While the typical recommended usage of TickSpec is to keep the step definitions simple and drive a system from the outside in the simplest fashion possible, in some advanced cases it may be useful to provide a custom type resolver. This can be achieved by set
ting the StepDefinitions.ServiceProviderFactory
property. This factory method is used once per scenario run to establish an independent resolution context per scenario run. The IServiceProvider
instance is used to replace the built in instance construction mechanism (see Resolving dependencies in the previous section: Resolving referenced types). If the IServiceProvider
implementation yielded by the factory also implements IDisposable
, Dispose
is called on the Service Provider context at the end of the scenario run.
See the CustomContainer
example project for usage examples - the example demonstrates wiring of Autofac including usage of lifetime scopes per scenario and usage of the xUnit 2+ Shared Fixtures to correctly manage the sharing/ifetime of the container where one runs xUnit Test Classes in parallel as part of a large test suite.
Contributions are welcome, particularly examples and documentation. If you'd like to chat about TickSpec, please use the the gitter channel.
For issues or suggestions please raise an Issue. If you are looking to extend or change the core implementation, it's best to drop a quick note and/or a placeholder PR in order to make sure there is broad agreement on the scope of the change / nature of the feature in question before investing significant time on it; we want to keep TickSpec powerful, but minimal.