GherXunit 1.3.56

🚀 GherXUnit: An Alternative for BDD with xUnit

🇧🇷 Versão em Português | 🇬🇧 English Version

The adoption of Behavior-Driven Development (BDD) has become increasingly common in software development, promoting better communication between technical and non-technical teams. However, its integration with traditional testing frameworks is not always straightforward.

GherXunit emerges as a viable alternative for teams looking to explore the benefits of BDD within the xUnit framework, without requiring external tools such as Cucumber or SpecFlow. It acts as a superset of xUnit, allowing tests to be written in Gherkin.

✅ Where Can GherXunit Help?

GherXunit aims to offer an alternative for teams already using xUnit and looking to incorporate the BDD structure without completely changing their tools. Among its benefits are:

• ✔ Using Gherkin syntax directly in xUnit, reducing external dependencies.
• ✔ More modular and organized code, using partial classes to separate scenarios and steps.
• ✔ Better integration with unit tests, allowing a smoother transition between different levels of testing.

📦 Getting Started

This package is available through Nuget Packages.

Version	Downloads	Status

💡 How Does It Work?

The core idea of GherXunit is to allow test scenarios to be written in a structure familiar to those already using xUnit. For that, it provides a set of attributes and methods that allow the definition of test scenarios using Gherkin syntax. The following sections provide examples of how to define test scenarios and implement step methods using GherXunit.

📌 Example of Scenario Definition:

The following code snippet shows a test scenario defined using Gherkin syntax in a class named SubscriptionTest:

using GherXunit.Annotations;
...

[Feature("Subscribers see different articles based on their subscription level")]
public partial class SubscriptionTest
{
    [Scenario("Free subscribers see only the free articles")]
    async Task WhenFriedaLogs() => await this.ExecuteAscync(
        refer: WhenFriedaLogsSteps,
        steps: """
               Given Free Frieda has a free subscription
               When Free Frieda logs in with her valid credentials
               Then she sees a Free article
               """);

    [Scenario("Subscriber with a paid subscription can access both free and paid articles")]
    void WhenPattyLogs() => this.Execute(
        refer: WhenPattyLogsSteps,
        steps: """
               Given Paid Patty has a basic-level paid subscription
               When Paid Patty logs in with her valid credentials
               Then she sees a Free article and a Paid article
               """);
}

📌 Example of Step Implementation:

The following code snippet shows the implementation of the step methods for the test scenario defined in the SubscriptionTest class:

public partial class SubscriptionTest(ITestOutputHelper output): IGherXunit
{
    public ITestOutputHelper Output { get; } = output;
    private void WhenPattyLogsSteps() => Assert.True(true);
    private async Task WhenFriedaLogsSteps() => await Task.CompletedTask;
}

📌 Example of output highlighting the test results:

The result of running the test scenarios defined in the SubscriptionTest class would be similar to the following output:

TEST RESULT: 🟢 SUCCESS
⤷ FEATURE Subscribers see different articles based on their subscription level
  ⤷ SCENARIO Free subscribers see only the free articles
    | GIVEN ↘ Free Frieda has a free subscription
    |  WHEN ↘ Free Frieda logs in with her valid credentials
    |  THEN ↘ she sees a Free article

TEST RESULT: 🟢 SUCCESS
⤷ FEATURE Subscribers see different articles based on their subscription level
  ⤷ SCENARIO Subscriber with a paid subscription can access both free and paid articles
    | GIVEN ↘ Paid Patty has a basic-level paid subscription
    |  WHEN ↘ Paid Patty logs in with her valid credentials
    |  THEN ↘ she sees a Free article and a Paid article

🔎 Is GherXunit for You?

If your team already uses xUnit and wants to experiment with a BDD approach without drastically changing its workflow, GherXunit may be an option to consider. It does not eliminate all BDD challenges but seeks to facilitate its adoption in environments where xUnit is already widely used. See more usage examples and implementation details for Background, Rule, Features, and other elements in the sample code available in the GherXunit repository.

📚 References

• 📖 Farooq, M. S., et al. (2023). Behavior Driven Development: A Systematic Literature Review. IEEE Access. DOI: 10.1109/ACCESS.2023.3302356.
• 📖 North, D. (2006). Introducing BDD. DanNorth.net. Available at: https://dannorth.net/introducing-bdd/.
• 📖 xUnit. (2023). xUnit.net. Available at: https://xunit.net/.
• 📖 Gherkin. (2023). Gherkin. Available at: https://cucumber.io/docs/gherkin/.

📌 Definindo o Lexer globalmente

A partir da versão 1.3.0, você pode definir o Lexer padrão para todos os testes do projeto (ou de uma classe) usando GherXunitConfig.DefaultLexer:

public partial class LocalizationTest
{
    static LocalizationTest()
    {
        GherXunitConfig.DefaultLexer = Lexers.PtBr; // Define o padrão para todos os testes desta classe
    }

    [Scenario("Inscrever-se para ver artigos gratuitos")]
    async Task WhenFriedaLogs() => await this.ExecuteAscync(
        refer: WhenFriedaLogsSteps,
        steps: """
               Dado Free Frieda possui uma assinatura gratuita
               Quando Free Frieda faz login com suas credenciais válidas
               Então ela vê um artigo gratuito
               """);

    // Para cenários que precisam de um lexer diferente, basta passar o parâmetro normalmente:
    [Scenario("Custom emoji lexer")]
    void WhenPattyLogs() => this.Execute(
        refer: WhenPattyLogsSteps,
        lexer: new EmojiGherXunitLexer(),
        steps: """
               Given Paid Patty has a basic-level paid subscription
               When Paid Patty logs in with her valid credentials
               Then she sees a Free article and a Paid article
               """);
}

Dica: O parâmetro lexer só precisa ser informado no teste se você quiser sobrescrever o padrão global.