Enhancements to Gherkin Syntax Customization

.github/workflows/dotnet.yml

@@ -7,18 +7,15 @@ on:
     branches: [ "main" ]
 
 jobs:
-
   build:
-
     strategy:
       matrix:
-        #configuration: [Debug, Release]
         configuration: [Release]
 
     runs-on: ubuntu-latest
 
     env:
-      Version: 1.2.${{ github.run_number }}
+      Version: 1.3.${{ github.run_number }}
       Solution_Path: ./src/GherXunit.sln  
       Project_Path: ./src/lib/GherXunit/GherXunit.csproj
       Package_Path: ./src/lib/GherXunit/**/*.
@@ -48,5 +45,4 @@ jobs:
       if: github.ref == 'refs/heads/main'
       run: |
         dotnet pack ${{env.Project_Path}} --no-restore --configuration ${{ matrix.configuration }} -p:PackageVersion=${{ env.Version }}
-        dotnet nuget push ${{env.Package_Path}}${{ env.Version }}.nupkg --api-key ${{ secrets.NUGET_KEY }} --source ${{ env.NUGET_INDEX }}
-
+        dotnet nuget push ${{env.Package_Path}}${{ env.Version }}.nupkg --api-key ${{ secrets.NUGET_KEY }} --source ${{ env.NUGET_INDEX }}

README.md

@@ -84,17 +84,82 @@ The result of running the test scenarios defined in the `SubscriptionTest` class
 ```gherkindotnet
 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
+  ⤷ 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
+  ⤷ 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
+```
+
+### ✏️ Customizing the lexical elements of Gherkin
+
+The **GherXunit** allows you to customize the lexical elements of Gherkin, such as `Given`, `When`, `Then`, `And`, `Background`, `Scenario`, and `Feature`. 
+You can define your custom emojis or symbols to represent these elements. The following code snippet shows an example of a custom lexer for emojis:
+```csharp
+// Custom lexer for emojis
+public record EmojiGherXunitLexer : IGherXunitLexer
+{
+    public (string Key, string Value)[] Given => [("Given", "\ud83d\ude10")];
+    public (string Key, string Value)[] When => [("When", "\ud83c\udfac")];
+    public (string Key, string Value)[] Then => [("Then", "\ud83d\ude4f")];
+    public (string Key, string Value)[] And => [("And", "\ud83d\ude02")];
+    public string Background => "\ud83d\udca4";
+    public string Scenario => "\ud83e\udd52\ud83d\udcd5";
+    public string Feature => "\ud83d\udcda";
+}
+```
+The Gherkin provides two built-in lexers: `Lexers.PtBr` for Portuguese (🇵🇹🇧🇷) and `Lexers.EnUs` for English (🇺🇸). 
+You can also create your custom lexer by implementing the `IGherXunitLexer` interface. To use the custom lexer, 
+you need to pass it as a parameter when defining the test scenario.
+
+```csharp
+[Feature("Subscribers see different articles based on their subscription level")]
+public partial class LocalizationTest
+{
+    // Using Portuguese (🇵🇹🇧🇷) lexer
+    [Scenario("Inscrever-se para ver artigos gratuitos")]
+    async Task WhenFriedaLogs() => await this.ExecuteAscync(
+        refer: WhenFriedaLogsSteps,
+        lexer: Lexers.PtBr,
+        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
+               """);
+
+    // Using custom emoji lexer
+    [Scenario("Subscriber with a paid subscription can access both free and paid articles")]
+    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
+               """);
+}
+```
+The result of running the test scenarios defined in the `LocalizationTest` class using the custom lexer would be similar to the following output:
+```gherkindotnet
+TEST RESULT: 🟢 SUCCESS
+⤷ FUNCIONALIDADE Subscribers see different articles based on their subscription level
+  ⤷ CENARIO Inscrever-se para ver artigos gratuitos
+    |   DADO ↘ Free Frieda possui uma assinatura gratuita
+    | QUANDO ↘ Free Frieda faz login com suas credenciais válidas
+    |  ENTÃO ↘ ela vê um artigo gratuito
+
+TEST RESULT: 🟢 SUCCESS
+⤷ 📚 Subscribers see different articles based on their subscription level
+  ⤷ 🥒📕 Subscriber with a paid subscription can access both free and paid articles
+    | 😐 ↘ Paid Patty has a basic-level paid subscription
+    | 🎬 ↘ Paid Patty logs in with her valid credentials
+    | 🙏 ↘ she sees a Free article and a Paid article    
 ```
 
 ### 🔎 Is GherXunit for You?

README_PTBR.md

@@ -83,20 +83,87 @@ public partial class SubscriptionTest(ITestOutputHelper output): IGherXunit
 #### 📌 Exemplo de saída destacando os resultados dos testes:
 O resultado da execução dos cenários de teste definidos na classe `SubscriptionTest` seria semelhante à saída a seguir:
 
-```shell
+```gherkindotnet
 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
+  ⤷ 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
+  ⤷ 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
+```
+
+### ✏️ Customizando a Sintaxe Gherkin
+
+O **GherXunit** permite personalizar os elementos lexicais do Gherkin, como `Given`, `When`, `Then`, `And`, `Background`, `Scenario` e `Feature`.
+Você pode definir seus emojis ou símbolos personalizados para representar esses elementos. O trecho de código a seguir mostra um exemplo de um lexer personalizado para emojis:
+
+```csharp
+// Custom lexer for emojis
+public record EmojiGherXunitLexer : IGherXunitLexer
+{
+    public (string Key, string Value)[] Given => [("Given", "\ud83d\ude10")];
+    public (string Key, string Value)[] When => [("When", "\ud83c\udfac")];
+    public (string Key, string Value)[] Then => [("Then", "\ud83d\ude4f")];
+    public (string Key, string Value)[] And => [("And", "\ud83d\ude02")];
+    public string Background => "\ud83d\udca4";
+    public string Scenario => "\ud83e\udd52\ud83d\udcd5";
+    public string Feature => "\ud83d\udcda";
+}
+```
+O **GherXunit** fornece dois lexers embutidos: `Lexers.PtBr` para Português (🇵🇹🇧🇷) e `Lexers.EnUs` para Inglês (🇺🇸).
+Você também pode criar seu lexer personalizado implementando a interface `IGherXunitLexer`. Para usar o lexer personalizado,
+você precisa passá-lo como parâmetro ao definir o cenário de teste.
+
+```csharp
+[Feature("Subscribers see different articles based on their subscription level")]
+public partial class LocalizationTest
+{
+    // Using Portuguese (🇵🇹🇧🇷) lexer
+    [Scenario("Inscrever-se para ver artigos gratuitos")]
+    async Task WhenFriedaLogs() => await this.ExecuteAscync(
+        refer: WhenFriedaLogsSteps,
+        lexer: Lexers.PtBr,
+        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
+               """);
+
+    // Using custom emoji lexer
+    [Scenario("Subscriber with a paid subscription can access both free and paid articles")]
+    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
+               """);
+}
+```
+
+O resultado da execução dos cenários de teste definidos na classe `LocalizationTest` usando o lexer personalizado seria semelhante à saída a seguir:
+```gherkindotnet
+TEST RESULT: 🟢 SUCCESS
+⤷ FUNCIONALIDADE Subscribers see different articles based on their subscription level
+  ⤷ CENARIO Inscrever-se para ver artigos gratuitos
+    |   DADO ↘ Free Frieda possui uma assinatura gratuita
+    | QUANDO ↘ Free Frieda faz login com suas credenciais válidas
+    |  ENTÃO ↘ ela vê um artigo gratuito
+
+TEST RESULT: 🟢 SUCCESS
+⤷ 📚 Subscribers see different articles based on their subscription level
+  ⤷ 🥒📕 Subscriber with a paid subscription can access both free and paid articles
+    | 😐 ↘ Paid Patty has a basic-level paid subscription
+    | 🎬 ↘ Paid Patty logs in with her valid credentials
+    | 🙏 ↘ she sees a Free article and a Paid article    
 ```
 
 ### 🔎 O GherXunit é para você?

src/GherXunit.sln

@@ -2,12 +2,8 @@
 Microsoft Visual Studio Solution File, Format Version 12.00
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "lib", "lib", "{8B016D41-92A4-4ABC-9D36-D9A13D3B0E7D}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{FF816255-012E-4E4D-9C2B-E8AE0CE481A3}"
-EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GherXunit", "lib\GherXunit\GherXunit.csproj", "{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BddSample", "sample\BddSample\BddSample.csproj", "{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B}"
-EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "base", "base", "{B014B043-DFB5-4827-8775-D4E5326130F0}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GherXunit.Core", "base\GherXunit.Core\GherXunit.Core.csproj", "{5477E886-B647-4A5D-A522-2978AF9F748D}"
@@ -19,18 +15,13 @@ Global
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6} = {8B016D41-92A4-4ABC-9D36-D9A13D3B0E7D}
-		{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B} = {FF816255-012E-4E4D-9C2B-E8AE0CE481A3}
 		{5477E886-B647-4A5D-A522-2978AF9F748D} = {B014B043-DFB5-4827-8775-D4E5326130F0}
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
 		{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{121FDFEF-6F96-48F9-8DB3-ED4775C5E9F6}.Release|Any CPU.Build.0 = Release|Any CPU
-		{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{4A38E3EA-C8A3-4F02-B7D5-BC63C302865B}.Release|Any CPU.Build.0 = Release|Any CPU
 		{5477E886-B647-4A5D-A522-2978AF9F748D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{5477E886-B647-4A5D-A522-2978AF9F748D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5477E886-B647-4A5D-A522-2978AF9F748D}.Release|Any CPU.ActiveCfg = Release|Any CPU

src/base/GherXunit.Core/GherXunit.Core.csproj

@@ -12,6 +12,8 @@
         <PackageReference Include="coverlet.collector" Version="6.0.2"/>
         <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1"/>
         <PackageReference Include="xunit" Version="2.9.2"/>
+        <PackageReference Include="Moq" Version="4.20.72" />
+        <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.2" />
         <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2"/>
     </ItemGroup>
 

src/base/GherXunit.Core/Interfaces.cs

@@ -17,4 +17,16 @@ public interface IGherXunit<T> : IGherXunit, IClassFixture<T> where T : class;
 public interface IGherXunitOutputProvider
 {
     public ITestOutputHelper Output { get; }
-}
+}
+
+//Lexer
+public interface IGherXunitLexer
+{
+    public (string Key, string Value)[] Given { get; }
+    public (string Key, string Value)[] When { get; }
+    public (string Key, string Value)[] Then { get; }
+    public (string Key, string Value)[] And { get; }
+    public string Background { get; }
+    public string Scenario { get; }
+    public string Feature { get; }
+}

src/base/GherXunit.Core/Methods.cs

@@ -7,54 +7,52 @@ namespace GherXunit.Annotations;
 
 public static class GherXunitSteps
 {
-    // Async methods
-    public static async Task BackgroundAsync(this IGherXunitStep scenario, Delegate refer, string steps) => await ExecuteAscync(scenario, refer.Method, steps, true);
-    public static async Task ExecuteAscync(this IGherXunitStep scenario, string steps) => await ExecuteAscync(scenario, null, steps, false);
-    public static async Task ExecuteAscync(this IGherXunitStep scenario, Delegate refer, string steps) => await ExecuteAscync(scenario, refer.Method, steps);
-    public static async Task ExecuteAscync(this IGherXunitStep scenario, Delegate refer, object[] param, string steps) => await ExecuteAscync(scenario, refer.Method, steps, false, param);
-    public static async Task NonExecutableAsync(this IGherXunitStep scenario, string? steps = null) => await ExecuteAscync(scenario, null, steps, false);
-
-    // Sync methods
-    public static void Background(this IGherXunitStep scenario, Delegate refer, string steps) => Execute(scenario, refer.Method, steps, true);
-    public static void Execute(this IGherXunitStep scenario, string steps) => Execute(scenario, null, steps, false);
-    public static void Execute(this IGherXunitStep scenario, Delegate refer, string steps) => Execute(scenario, refer.Method, steps);
-    public static void Execute(this IGherXunitStep scenario, Delegate refer, object[] param, string steps) => Execute(scenario, refer.Method, steps, false, param);
-    public static void NonExecutable(this IGherXunitStep feature, string? steps) => Execute(feature, null, steps, false, []);
+    // Background methods
+    public static void Background(this IGherXunitStep scenario, Delegate refer, string steps, IGherXunitLexer? lexer = null) => InternalExecute(scenario, refer.Method, steps, true, lexer);
+    public static async Task BackgroundAsync(this IGherXunitStep scenario, Delegate refer, string steps, IGherXunitLexer? lexer = null) => await InternalExecuteAscync(scenario, refer.Method, steps, true, lexer);
+
+    // Execute methods
+    public static void Execute(this IGherXunitStep scenario, string steps, Delegate? refer = null, object[]? param = null,  IGherXunitLexer? lexer = null) => InternalExecute(scenario, refer?.Method, steps, false, lexer, param);
+    public static async Task ExecuteAscync(this IGherXunitStep scenario, string steps, Delegate? refer = null, object[]? param = null, IGherXunitLexer? lexer = null) => await InternalExecuteAscync(scenario, refer?.Method, steps, false, lexer, param);
+
+    // Non Executable 
+    public static void NonExecutable(this IGherXunitStep feature, string steps, IGherXunitLexer? lexer = null) => InternalExecute(feature, null, steps, false, lexer);
+    public static async Task NonExecutableAsync(this IGherXunitStep scenario, string steps, IGherXunitLexer? lexer = null) => await InternalExecuteAscync(scenario, null, steps, false, lexer);
 
     // Private methods
-    private static void Execute(this IGherXunitStep scenario, MethodInfo? method, string? steps,
-        bool isBackground = false, params object?[] param)
+    private static void InternalExecute(this IGherXunitStep scenario, MethodInfo? method, string? steps,
+        bool isBackground = false, IGherXunitLexer? lexer = null, params object[]? param)
     {
         try
         {
             method?.Invoke(scenario, param);
-            scenario.Write(method?.Name, steps, false, isBackground);
+            scenario.Write(method?.Name, steps, false, isBackground, lexer);
         }
         catch (Exception)
         {
-            scenario.Write(method?.Name, steps, true, isBackground);
+            scenario.Write(method?.Name, steps, true, isBackground, lexer);
             throw;
         }
     }
 
-    private static async Task ExecuteAscync(this IGherXunitStep scenario, MethodInfo? method, string? steps,
-        bool isBackground = false, params object?[] param)
+    private static async Task InternalExecuteAscync(this IGherXunitStep scenario, MethodInfo? method, string? steps,
+        bool isBackground = false, IGherXunitLexer? lexer = null, params object[]? param)
     {
         try
         {
             var task = method is null ? Task.CompletedTask : (Task)method.Invoke(scenario, param)!;
             await task;
 
-            scenario.Write(method?.Name, steps, false, isBackground);
+            scenario.Write(method?.Name, steps, false, isBackground, lexer);
         }
         catch (Exception)
         {
-            scenario.Write(method?.Name, steps, true, isBackground);
+            scenario.Write(method?.Name, steps, true, isBackground, lexer);
             throw;
         }
     }
 
-    private static void Write(this IGherXunitStep scenario, string? methodName, string? steps, bool isException = false, bool isBackground = false)
+    private static void Write(this IGherXunitStep scenario, string? methodName, string? steps, bool isException = false, bool isBackground = false, IGherXunitLexer? lexer = null)
     {
         if (steps is null) return;
 
@@ -65,8 +63,8 @@ private static void Write(this IGherXunitStep scenario, string? methodName, stri
         var scenarioText = iTest is null
             ? $"{(isBackground ? "Background" : "Scenario")} {methodName}\r\n"
             : $"{(isBackground ? "Background" : "Scenario")} {iTest.DisplayName}\r\n";
-
-        var stepString = new StepStringHandler();
+        
+        var stepString = new StringHandler(lexer ?? Lexers.EnUs);
         stepString.AppendLiteral($"{statusResult}{featuresText}{scenarioText}{steps}");
 
         output?.WriteLine(".");

src/sample/BddSample/Samples/Features/SubscriptionTest.Steps.cs → src/base/GherXunit.Core/Samples/Localization/LocalizationTest.Steps.cs

@@ -1,9 +1,9 @@
 using GherXunit.Annotations;
 using Xunit.Abstractions;
 
-namespace BddTests.Samples.Features;
+namespace BddTests.Samples.Localization;
 
-public partial class SubscriptionTest(ITestOutputHelper output): IGherXunit
+public partial class LocalizationTest(ITestOutputHelper output): IGherXunit
 {
     public ITestOutputHelper Output { get; } = output;
     private void WhenPattyLogsSteps() => Assert.True(true);