TL;DR - Gherkin end-to-end example
BDD has already been mentioned[0] but I thought a concrete example would be helpful.
The following excerpts are from a Gherkin specification for bowling[1]. These examples use SpecFlow, Xunit, and C# but the specific technology is not what is important.
Here is a Gherkin feature[2] for scoring a game of bowling.
Feature: Score Calculation
In order to know my performance
As a player
I want the system to calculate my total score
Features consist of scenarios. Here is the scenario[3] for a game with a total score of zero.
Scenario: Gutter game
Given a new bowling game
When all of my balls are landing in the gutter
Then my total score should be 0
Scenarios are mapped to unit tests. Here is the code[4] that implements this scenario.
[Given(@"a new bowling game")]
public void GivenANewBowlingGame()
{
_game = new Game();
}
[When(@"all of my balls are landing in the gutter")]
public void WhenAllOfMyBallsAreLandingInTheGutter()
{
for (int i = 0; i < 20; i++)
{
_game.Roll(0);
}
}
[Then(@"my total score should be (\d+)")]
public void ThenMyTotalScoreShouldBe(int score)
{
Assert.Equal(score, _game.Score);
}
Hopefully this is enough to give you a sense of whether Gherkin would work for you.
[0] https://news.ycombinator.com/item?id=14222650
[1] https://github.com/techtalk/SpecFlow-Examples/tree/master/Bo...
[2] https://github.com/techtalk/SpecFlow-Examples/blob/master/Bo...
[3] https://github.com/techtalk/SpecFlow-Examples/blob/master/Bo...
[4] https://github.com/techtalk/SpecFlow-Examples/blob/master/Bo...
Edited to fix formatting of examples.