Merge branch 'develop' of github.com:TestStack/TestStack.BDDfy into testing/additional-tests

# Conflicts:
#	src/TestStack.BDDfy.Tests/Scanner/ReflectiveScanner/WhenStepMethodNameHasDoubleUnderscores.cs

Author: asos-gurpreetsingh

docs/async-support.md

@@ -0,0 +1,123 @@
+# Async Support
+
+BDDfy supports asynchronous step methods using both `Task`-returning methods and `async void` methods.
+
+## Task-Returning Steps (Recommended)
+
+The preferred approach is to return `Task` from your step methods:
+
+```csharp
+public class AsyncScenario
+{
+    private HttpClient _client = new();
+    private HttpResponseMessage _response = null!;
+
+    async Task GivenTheServiceIsRunning()
+    {
+        await _client.GetAsync("http://localhost/health");
+    }
+
+    async Task WhenIRequestTheResource()
+    {
+        _response = await _client.GetAsync("http://localhost/api/items");
+    }
+
+    async Task ThenTheResponseIsSuccessful()
+    {
+        _response.EnsureSuccessStatusCode();
+    }
+
+    [Fact]
+    public void Execute()
+    {
+        this.BDDfy();
+    }
+}
+```
+
+### With the Fluent API
+
+```csharp
+[Fact]
+public void Execute()
+{
+    this.Given(s => s.GivenTheServiceIsRunning())
+        .When(s => s.WhenIRequestTheResource())
+        .Then(s => s.ThenTheResponseIsSuccessful())
+        .BDDfy();
+}
+```
+
+The fluent API has dedicated overloads accepting `Expression<Func<TScenario, Task>>`.
+
+## Async Void Steps
+
+BDDfy can also handle `async void` methods. It installs a custom `SynchronizationContext` to detect when the method completes:
+
+```csharp
+public class AsyncVoidSteps
+{
+    private object _sut = null!;
+
+    async void GivenSomeAsyncSetup()
+    {
+        _sut = await CreateSut();
+    }
+
+    void ThenBddfyHasWaitedForSetupToComplete()
+    {
+        Assert.NotNull(_sut);
+    }
+
+    private static async Task<object> CreateSut()
+    {
+        await Task.Delay(500);
+        return new object();
+    }
+
+    [Fact]
+    public void Execute()
+    {
+        this.BDDfy();
+    }
+}
+```
+
+### Exception Handling in Async Void
+
+Exceptions thrown in `async void` methods are captured and reported normally:
+
+```csharp
+async void WhenSomethingFails()
+{
+    await Task.Yield();
+    throw new InvalidOperationException("Something went wrong");
+}
+```
+
+BDDfy will catch this exception and mark the step as failed.
+
+### Disabling Async Void Support
+
+If async void detection causes issues in your environment:
+
+```csharp
+Configurator.AsyncVoidSupportEnabled = false;
+```
+
+## Async Delegate Steps (Fluent API)
+
+Use `Func<Task>` with an explicit title:
+
+```csharp
+this.Given(async () => await SetupDatabase(), "Given the database is seeded")
+    .When(async () => await CallApi(), "When the API is called")
+    .Then(async () => await VerifyResult(), "Then the result is correct")
+    .BDDfy();
+```
+
+## Best Practices
+
+1. **Prefer `Task`-returning methods** over `async void` — they're easier to debug and don't require the special synchronization context
+2. **Avoid `Task.Result` or `.Wait()`** in step methods — use `async`/`await` throughout to prevent deadlocks
+3. **Use `async void` only** when retrofitting existing code or when the testing framework requires it

docs/configuration.md

@@ -0,0 +1,224 @@
+# Configuration
+
+BDDfy's behavior is controlled through the static `Configurator` class. Everything from step scanning to reporting is pluggable.
+
+## The Configurator Class
+
+```csharp
+using TestStack.BDDfy.Configuration;
+
+// All configuration is done via static properties:
+Configurator.Processors       // Per-scenario pipeline
+Configurator.BatchProcessors  // End-of-run reporters
+Configurator.Scanners         // Step discovery
+Configurator.IdGenerator      // Unique key generation
+Configurator.StepExecutor     // Step execution strategy
+Configurator.Humanizer        // Method name → readable text
+Configurator.FluentScannerFactory  // Fluent scanner creation
+Configurator.StepTitleFactory      // Step title generation
+Configurator.CultureInfo      // Culture for formatting
+Configurator.AsyncVoidSupportEnabled  // async void step support (default: true)
+```
+
+## Per-Scenario Processors
+
+Processors run for each scenario in order of their `ProcessType`:
+
+```csharp
+// Disable console output
+Configurator.Processors.ConsoleReport.Disable();
+
+// Add a custom processor
+Configurator.Processors.Add(() => new MyCustomProcessor());
+```
+
+Built-in processors (in execution order):
+1. **TestRunner** — executes the scenario steps
+2. **ConsoleReporter** — prints to console
+3. **ExceptionProcessor** — handles/rethrows exceptions
+4. **StoryCache** — stores results for batch reporters
+5. **Disposer** — disposes the test object if `IDisposable`
+
+### Enabling/Disabling
+
+```csharp
+Configurator.Processors.TestRunner.Disable();
+Configurator.Processors.ConsoleReport.Disable();
+Configurator.Processors.StoryCache.Disable();
+```
+
+## Batch Processors
+
+Run once after all scenarios complete (typically reporters):
+
+```csharp
+Configurator.BatchProcessors.HtmlReport.Enable();
+Configurator.BatchProcessors.HtmlMetroReport.Disable();
+Configurator.BatchProcessors.MarkDownReport.Enable();
+Configurator.BatchProcessors.DiagnosticsReport.Enable();
+
+// Add custom batch processor
+Configurator.BatchProcessors.Add(new MyBatchProcessor());
+```
+
+## Step Scanners
+
+Control how BDDfy discovers steps in your test classes:
+
+```csharp
+// Disable attribute-based scanning
+Configurator.Scanners.ExecutableAttributeScanner.Disable();
+
+// Disable method-name scanning
+Configurator.Scanners.DefaultMethodNameStepScanner.Disable();
+
+// Add a custom step scanner
+Configurator.Scanners.Add(() => new MyCustomStepScanner());
+```
+
+## Story Metadata Scanner
+
+Replace how story metadata is discovered:
+
+```csharp
+Configurator.Scanners.StoryMetadataScanner = () => new MyCustomMetadataScanner();
+```
+
+## Humanizer
+
+The humanizer converts method names into readable titles:
+
+```csharp
+// Replace with a custom humanizer
+Configurator.Humanizer = new MyHumanizer();
+
+public class MyHumanizer : IHumanizer
+{
+    public string Humanize(string name)
+    {
+        // Custom logic to convert PascalCase/underscored names to text
+        return name.Replace("_", " ");
+    }
+}
+```
+
+## Step Executor
+
+Override how individual steps are executed:
+
+```csharp
+Configurator.StepExecutor = new MyStepExecutor();
+
+public class MyStepExecutor : IStepExecutor
+{
+    public void Execute(Step step, object testObject)
+    {
+        // Add logging, timing, retry logic, etc.
+        Console.WriteLine($"Executing: {step.Title}");
+        step.Execute(testObject);
+    }
+}
+```
+
+## Step Title Factory
+
+Customize how step titles are generated from expressions:
+
+```csharp
+Configurator.StepTitleFactory = new MyStepTitleFactory();
+```
+
+### IncludeInputsInStepTitle
+
+Controls whether step arguments are appended to step titles (default: `true`):
+
+```csharp
+Configurator.StepTitleFactory.IncludeInputsInStepTitle = false;
+```
+
+### AddGherkinPrefixToSecondarySteps
+
+When a step has an explicit title (via `[Given("...")]`, `[When("...")]`, `[Then("...")]`, or `[StepTitle("...")]`), BDDfy prepends the Gherkin keyword to the title by default. For consecutive steps in the same group, this means they get an "And" prefix. Set this to `false` to disable the "And" prefix on consecutive custom-titled steps:
+
+```csharp
+Configurator.StepTitleFactory.AddGherkinPrefixToSecondarySteps = true;  // default
+```
+
+**With prefix enabled (default):**
+
+```
+Scenario: With prefix enabled
+    Given the user is logged in
+      And the cart has items
+      And the payment gateway is available
+    When the user checks out
+    Then the order is confirmed
+      And a confirmation email is sent
+```
+
+```csharp
+Configurator.StepTitleFactory.AddGherkinPrefixToSecondarySteps = false;
+```
+
+**With prefix disabled:**
+
+```
+Scenario: With prefix disabled
+    Given the user is logged in
+      the cart has items
+      the payment gateway is available
+    When the user checks out
+    Then the order is confirmed
+      a confirmation email is sent
+```
+
+> **Note:** Primary step keywords (Given/When/Then) are always applied regardless of this setting. Only the consecutive "And" prefix on custom-titled steps is affected.
+
+## Culture
+
+Set the culture used for formatting values in reports:
+
+```csharp
+Configurator.CultureInfo = new CultureInfo("en-US");
+```
+
+## Async Void Support
+
+BDDfy can detect and await `async void` step methods. Disable if it causes issues:
+
+```csharp
+Configurator.AsyncVoidSupportEnabled = false;
+```
+
+## Configuration Timing
+
+Configure BDDfy before any tests run. With xUnit, use a module initializer or assembly fixture:
+
+```csharp
+using System.Runtime.CompilerServices;
+using TestStack.BDDfy.Configuration;
+
+public static class BDDfySetup
+{
+    [ModuleInitializer]
+    public static void Initialize()
+    {
+        Configurator.BatchProcessors.HtmlReport.Disable();
+        Configurator.BatchProcessors.MarkDownReport.Enable();
+    }
+}
+```
+
+With NUnit, use `[SetUpFixture]`:
+
+```csharp
+[SetUpFixture]
+public class BDDfySetup
+{
+    [OneTimeSetUp]
+    public void Setup()
+    {
+        Configurator.BatchProcessors.HtmlMetroReport.Enable();
+    }
+}
+```