From 5323e1977c52dabff7240805645ad7e6918d4c12 Mon Sep 17 00:00:00 2001
From: Rafal Mielowski <rmielowski@microsoft.com>
Date: Thu, 26 Feb 2026 18:20:30 +0100
Subject: [PATCH] Add emulator handler and tests for ForwardRequest

- Implement ForwardRequestHandler with MockBackendResponse store
- Add ForwardRequestStore for queuing mock backend responses
- Add MockBackendResponse record (StatusCode, StatusReason, Headers, Body)
- Register ForwardRequestStore in GatewayContext and TestDocumentExtensions
- Sequential responses via Returns() and default via ReturnsDefault()
- Handler applies mock response to context (status, headers, body)
- Add ForwardRequestTests with 6 test cases
- Sections: Backend

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/EmulatorPolicyChecklist.md               |  2 +-
 .../Document/TestDocumentExtensions.cs        |  3 +
 .../Emulator/Data/ForwardRequestStore.cs      | 25 +++++
 .../Emulator/Data/MockBackendResponse.cs      | 12 +++
 .../Policies/ForwardRequestHandler.cs         | 26 +++++-
 src/Testing/GatewayContext.cs                 |  1 +
 .../Emulator/Policies/ForwardRequestTests.cs  | 93 ++++++++++++++++++-
 7 files changed, 155 insertions(+), 7 deletions(-)
 create mode 100644 src/Testing/Emulator/Data/ForwardRequestStore.cs
 create mode 100644 src/Testing/Emulator/Data/MockBackendResponse.cs

diff --git a/docs/EmulatorPolicyChecklist.md b/docs/EmulatorPolicyChecklist.md
index f9faf9cd..f80ba9aa 100644
--- a/docs/EmulatorPolicyChecklist.md
+++ b/docs/EmulatorPolicyChecklist.md
@@ -50,7 +50,7 @@ Track progress of emulator policy handler implementation. Each policy needs a ha
 | ⬜ | CacheStore | CacheStoreHandler.cs | Store interaction | `emulator/cache-store` |
 | ⬜ | Cors | CorsHandler.cs | Context mutation | `emulator/cors` |
 | ⬜ | EmitMetric | EmitMetricHandler.cs | No-op + callbacks | `emulator/emit-metric` |
-| ⬜ | ForwardRequest | ForwardRequestHandler.cs | External service mock | `emulator/forward-request` |
+| ✅ | ForwardRequest | ForwardRequestHandler.cs | External service mock | `emulator/forward-request` |
 | ⬜ | JsonP | JsonPHandler.cs | Context mutation | `emulator/jsonp` |
 | ⬜ | JsonToXml | JsonToXmlHandle.cs | No-op + callbacks | `emulator/json-to-xml` |
 | ⬜ | LlmEmitTokenMetric | LlmEmitTokenMetricHandler.cs | No-op + callbacks | `emulator/llm-emit-token-metric` |
diff --git a/src/Testing/Document/TestDocumentExtensions.cs b/src/Testing/Document/TestDocumentExtensions.cs
index 6a91eb81..464e56fa 100644
--- a/src/Testing/Document/TestDocumentExtensions.cs
+++ b/src/Testing/Document/TestDocumentExtensions.cs
@@ -31,4 +31,7 @@ public static ResponseExampleStore SetupResponseExampleStore(this TestDocument d
 
     public static LoggerStore SetupLoggerStore(this TestDocument document) =>
         document.Context.LoggerStore;
+
+    public static ForwardRequestStore SetupForwardRequest(this TestDocument document) =>
+        document.Context.ForwardRequestStore;
 }
\ No newline at end of file
diff --git a/src/Testing/Emulator/Data/ForwardRequestStore.cs b/src/Testing/Emulator/Data/ForwardRequestStore.cs
new file mode 100644
index 00000000..1523ae3b
--- /dev/null
+++ b/src/Testing/Emulator/Data/ForwardRequestStore.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Data;
+
+public class ForwardRequestStore
+{
+    private readonly Queue<MockBackendResponse> _responses = new();
+    private MockBackendResponse? _default;
+
+    public ForwardRequestStore Returns(MockBackendResponse response)
+    {
+        _responses.Enqueue(response);
+        return this;
+    }
+
+    public ForwardRequestStore ReturnsDefault(MockBackendResponse response)
+    {
+        _default = response;
+        return this;
+    }
+
+    internal MockBackendResponse? GetNext() =>
+        _responses.Count > 0 ? _responses.Dequeue() : _default;
+}
diff --git a/src/Testing/Emulator/Data/MockBackendResponse.cs b/src/Testing/Emulator/Data/MockBackendResponse.cs
new file mode 100644
index 00000000..6734939b
--- /dev/null
+++ b/src/Testing/Emulator/Data/MockBackendResponse.cs
@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Data;
+
+public record MockBackendResponse
+{
+    public int StatusCode { get; init; } = 200;
+    public string StatusReason { get; init; } = "OK";
+    public Dictionary<string, string[]> Headers { get; init; } = new();
+    public string? Body { get; init; }
+}
diff --git a/src/Testing/Emulator/Policies/ForwardRequestHandler.cs b/src/Testing/Emulator/Policies/ForwardRequestHandler.cs
index dbb0a455..71cbdc33 100644
--- a/src/Testing/Emulator/Policies/ForwardRequestHandler.cs
+++ b/src/Testing/Emulator/Policies/ForwardRequestHandler.cs
@@ -1,7 +1,8 @@
-// Copyright (c) Microsoft Corporation.
+// Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
 using Microsoft.Azure.ApiManagement.PolicyToolkit.Authoring;
+using Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Expressions;
 
 namespace Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Policies;
 
@@ -12,6 +13,27 @@ internal class ForwardRequestHandler : PolicyHandlerOptionalParam<ForwardRequest
 
     protected override void Handle(GatewayContext context, ForwardRequestConfig? config)
     {
-        throw new NotImplementedException();
+        var mockResponse = context.ForwardRequestStore.GetNext();
+
+        if (mockResponse is null)
+        {
+            return;
+        }
+
+        context.Response = new MockResponse
+        {
+            StatusCode = mockResponse.StatusCode,
+            StatusReason = mockResponse.StatusReason,
+        };
+
+        foreach (var (key, values) in mockResponse.Headers)
+        {
+            context.Response.Headers[key] = values;
+        }
+
+        if (mockResponse.Body is not null)
+        {
+            context.Response.Body.Content = mockResponse.Body;
+        }
     }
 }
\ No newline at end of file
diff --git a/src/Testing/GatewayContext.cs b/src/Testing/GatewayContext.cs
index 724b10b6..8d8a710e 100644
--- a/src/Testing/GatewayContext.cs
+++ b/src/Testing/GatewayContext.cs
@@ -18,6 +18,7 @@ public class GatewayContext : MockExpressionContext
     internal readonly CacheStore CacheStore = new();
     internal readonly ResponseExampleStore ResponseExampleStore = new();
     internal readonly LoggerStore LoggerStore = new();
+    internal readonly ForwardRequestStore ForwardRequestStore = new();
 
     public GatewayContext()
     {
diff --git a/test/Test.Testing/Emulator/Policies/ForwardRequestTests.cs b/test/Test.Testing/Emulator/Policies/ForwardRequestTests.cs
index 30209b08..06063705 100644
--- a/test/Test.Testing/Emulator/Policies/ForwardRequestTests.cs
+++ b/test/Test.Testing/Emulator/Policies/ForwardRequestTests.cs
@@ -4,6 +4,7 @@
 using Microsoft.Azure.ApiManagement.PolicyToolkit.Authoring;
 using Microsoft.Azure.ApiManagement.PolicyToolkit.Testing;
 using Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Document;
+using Microsoft.Azure.ApiManagement.PolicyToolkit.Testing.Emulator.Data;
 
 namespace Test.Emulator.Emulator.Policies;
 
@@ -18,18 +19,102 @@ public void Backend(IBackendContext context)
         }
     }
 
+    class ForwardRequestWithConfig : IDocument
+    {
+        public void Backend(IBackendContext context)
+        {
+            context.ForwardRequest(new ForwardRequestConfig { Timeout = 60 });
+        }
+    }
+
+    [TestMethod]
+    public void ForwardRequest_DefaultResponse()
+    {
+        var test = new SimpleForwardRequest().AsTestDocument();
+
+        test.RunBackend();
+
+        test.Context.Response.StatusCode.Should().Be(200);
+    }
+
+    [TestMethod]
+    public void ForwardRequest_MockedResponse()
+    {
+        var test = new SimpleForwardRequest().AsTestDocument();
+        test.SetupForwardRequest().ReturnsDefault(new MockBackendResponse
+        {
+            StatusCode = 201,
+            StatusReason = "Created",
+            Body = """{"id": 42}""",
+            Headers = { { "Content-Type", ["application/json"] } }
+        });
+
+        test.RunBackend();
+
+        test.Context.Response.StatusCode.Should().Be(201);
+        test.Context.Response.StatusReason.Should().Be("Created");
+        test.Context.Response.Body.Content.Should().Be("""{"id": 42}""");
+        test.Context.Response.Headers.Should().ContainKey("Content-Type");
+    }
+
+    [TestMethod]
+    public void ForwardRequest_SequentialResponses()
+    {
+        var test = new SimpleForwardRequest().AsTestDocument();
+        test.SetupForwardRequest()
+            .Returns(new MockBackendResponse { StatusCode = 200, Body = "first" })
+            .Returns(new MockBackendResponse { StatusCode = 201, Body = "second" });
+
+        test.RunBackend();
+        test.Context.Response.StatusCode.Should().Be(200);
+        test.Context.Response.Body.Content.Should().Be("first");
+
+        test.RunBackend();
+        test.Context.Response.StatusCode.Should().Be(201);
+        test.Context.Response.Body.Content.Should().Be("second");
+    }
+
+    [TestMethod]
+    public void ForwardRequest_ErrorResponse()
+    {
+        var test = new SimpleForwardRequest().AsTestDocument();
+        test.SetupForwardRequest().ReturnsDefault(new MockBackendResponse
+        {
+            StatusCode = 500,
+            StatusReason = "Internal Server Error",
+            Body = "backend error"
+        });
+
+        test.RunBackend();
+
+        test.Context.Response.StatusCode.Should().Be(500);
+    }
+
+    [TestMethod]
+    public void ForwardRequest_WithConfig()
+    {
+        var test = new ForwardRequestWithConfig().AsTestDocument();
+        test.SetupForwardRequest().ReturnsDefault(new MockBackendResponse { StatusCode = 204 });
+
+        test.RunBackend();
+
+        test.Context.Response.StatusCode.Should().Be(204);
+    }
+
     [TestMethod]
     public void ForwardRequest_Callback()
     {
         var test = new SimpleForwardRequest().AsTestDocument();
-        var executedCallback = false;
-        test.SetupBackend().ForwardRequest().WithCallback((_, _) =>
+        var callbackExecuted = false;
+        test.SetupBackend().ForwardRequest().WithCallback((context, _) =>
         {
-            executedCallback = true;
+            callbackExecuted = true;
+            context.Response.StatusCode = 418;
         });
 
         test.RunBackend();
 
-        executedCallback.Should().BeTrue();
+        callbackExecuted.Should().BeTrue();
+        test.Context.Response.StatusCode.Should().Be(418);
     }
 }
\ No newline at end of file