@gcoredev/fastedge-test 0.1.6 → 0.2.0

package/docs/RUNNER.md

@@ -102,10 +102,6 @@ interface IWasmRunner {
     method: string,
     headers: Record<string, string>,
     body: string,
-    responseHeaders: Record<string, string>,
-    responseBody: string,
-    responseStatus: number,
-    responseStatusText: string,
     properties: Record<string, unknown>,
     enforceProductionPropertyRules: boolean
   ): Promise<FullFlowResult>;
@@ -126,6 +122,14 @@ load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void>
 
 Calling `load()` again on the same runner replaces the current module and restarts any underlying process.
 
+**`httpPort` pinning (HTTP-WASM only).** When `config.httpPort` is set, the spawned `fastedge-run` process is bound to that specific port instead of allocating from the dynamic pool (8100–8199). If the port is already in use, `load()` throws:
+
+```
+fastedge-run port <N> is not available — release it or choose a different httpPort in fastedge-config.test.json
+```
+
+There is no fallback to dynamic allocation — pinning is only useful if the address is stable. Intended for Codespaces/Docker port-forwarding setups, live-preview URLs, or external tooling that requires a fixed target. For proxy-wasm runners, `httpPort` is ignored.
+
 ### execute (HTTP-WASM)
 
 Executes an HTTP request through the WASM module. Only available on `HttpWasmRunner` (http-wasm). Calling this on a `ProxyWasmRunner` throws.
@@ -134,7 +138,33 @@ Executes an HTTP request through the WASM module. Only available on `HttpWasmRun
 execute(request: HttpRequest): Promise<HttpResponse>
 ```
 
-The runner forwards the request to the locally spawned `fastedge-run` process and returns the response including any logs captured from the process.
+`request.path` is a path on the locally spawned `fastedge-run` server, not a full URL. The runner forwards the request to that local process and returns the response including logs captured from the process stdout/stderr.
+
+**Redirects are not followed.** The underlying fetch uses `redirect: "manual"`, so 3xx responses reach the caller intact — status code and `Location` header — rather than being transparently followed. This matches FastEdge edge behavior, where redirects are returned to the client rather than followed server-side, and lets tests assert on redirect status and `Location`.
+
+To follow a redirect, inspect `response.headers.location` and handle by `Location` shape:
+
+- **Relative Location** (e.g. `/new-path`) — reuse directly as `request.path`.
+- **Absolute same-host Location** (e.g. `http://localhost:8100/new-path`) — parse via `new URL()` and re-issue with `pathname + search` as `request.path`.
+- **Absolute cross-host Location** (e.g. `https://other.example.com/`) — cannot be followed through the runner; the 3xx response is the terminal state for the test.
+
+```typescript
+import { createRunner } from '@gcoredev/fastedge-test';
+
+const runner = await createRunner('./my-http-app.wasm');
+
+// Relative Location: reuse directly as path
+let response = await runner.execute({ path: '/moved', method: 'GET', headers: {} });
+if (response.status >= 300 && response.status < 400 && response.headers['location']) {
+  response = await runner.execute({
+    path: response.headers['location'] as string, // e.g. "/new-location"
+    method: 'GET',
+    headers: {},
+  });
+}
+
+await runner.cleanup();
+```
 
 ### callHook (Proxy-WASM)
 
@@ -158,10 +188,6 @@ callFullFlow(
   method: string,
   headers: Record<string, string>,
   body: string,
-  responseHeaders: Record<string, string>,
-  responseBody: string,
-  responseStatus: number,
-  responseStatusText: string,
   properties: Record<string, unknown>,
   enforceProductionPropertyRules: boolean
 ): Promise<FullFlowResult>
@@ -175,16 +201,14 @@ callFullFlow(
 | `method`                         | `string`                  | HTTP method                                                                                                           |
 | `headers`                        | `Record<string, string>`  | Request headers                                                                                                       |
 | `body`                           | `string`                  | Request body                                                                                                          |
-| `responseHeaders`                | `Record<string, string>`  | Upstream response headers (used as initial state for response hooks)                                                  |
-| `responseBody`                   | `string`                  | Upstream response body                                                                                                |
-| `responseStatus`                 | `number`                  | Upstream response status code                                                                                         |
-| `responseStatusText`             | `string`                  | Upstream response status text                                                                                         |
 | `properties`                     | `Record<string, unknown>` | Shared properties passed to all hooks                                                                                 |
 | `enforceProductionPropertyRules` | `boolean`                 | When `true`, restricts property access to match CDN production behavior                                               |
 
+The upstream response is generated at runtime — either by a real HTTP fetch against `url`, or by the built-in responder when `url === "built-in"`. There is no caller-provided mock response.
+
 Hook execution order: `onRequestHeaders` → `onRequestBody` → *(real HTTP fetch or built-in responder)* → `onResponseHeaders` → `onResponseBody`.
 
-**Local response short-circuit:** If a WASM module calls `send_http_response` (proxy-wasm: `proxy_send_local_response`) during `onRequestHeaders` or `onRequestBody` and returns `StopIteration` (return code `1`), the remaining hooks and origin fetch are **skipped**. The `finalResponse` in the result is built from the locally-sent status, headers, and body — matching CDN production behavior. This is how redirect modules (e.g., geo-redirect) and early error responses work.
+**Local response short-circuit.** If a WASM module calls `proxy_send_local_response` during `onRequestHeaders` or `onRequestBody` and returns `StopIteration` (return code `1`), the remaining hooks and origin fetch are skipped. The `finalResponse` in the result is built from the locally-sent status, headers, and body — matching CDN production behavior. This is how redirect modules (e.g., geo-redirect) and early error responses work.
 
 Only available on `ProxyWasmRunner`. Calling on `HttpWasmRunner` throws.
 
@@ -272,23 +296,25 @@ When testing proxy-wasm modules without a real origin server, pass `BUILTIN_SHOR
 
 ```typescript
 import { createRunner, BUILTIN_SHORTHAND } from '@gcoredev/fastedge-test';
+import type { FullFlowResult } from '@gcoredev/fastedge-test';
 
 const runner = await createRunner('./my-cdn-app.wasm');
-const result = await runner.callFullFlow(
+const result: FullFlowResult = await runner.callFullFlow(
   BUILTIN_SHORTHAND, // no origin fetch
   'GET',
   { 'accept': 'application/json' },
   '',
-  {}, '', 200, 'OK', {}, true
+  {},   // properties
+  true, // enforceProductionPropertyRules
 );
 ```
 
 **Built-in responder behavior** — controlled by request headers set before the origin phase:
 
-| Header               | Effect                                                                          |
-| -------------------- | ------------------------------------------------------------------------------- |
-| `x-debugger-status`  | HTTP status code for the generated response (default: `200`)                    |
-| `x-debugger-content` | Response body mode: `"body-only"`, `"status-only"`, or full JSON echo (default) |
+| Header               | Effect                                                                           |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `x-debugger-status`  | HTTP status code for the generated response (default: `200`)                     |
+| `x-debugger-content` | Response body mode: `"body-only"`, `"status-only"`, or full JSON echo (default)  |
 
 When `x-debugger-content` is omitted, the built-in responder returns a JSON echo of the request method, headers, body, and URL. Both control headers are stripped before response hooks execute so they do not appear in hook input state.
 
@@ -306,15 +332,17 @@ interface RunnerConfig {
   };
   enforceProductionPropertyRules?: boolean;
   runnerType?: WasmType;
+  httpPort?: number;
 }
 ```
 
-| Field                            | Type       | Default         | Description                                                                                                                                                                                                                                                               |
-| -------------------------------- | ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dotenv.enabled`                 | `boolean`  | `false`         | Whether to load `.env` files                                                                                                                                                                                                                                              |
-| `dotenv.path`                    | `string`   | `undefined`     | Directory to load dotenv files from. When omitted, `fastedge-run` uses the process CWD — correct for most npm package users whose `.env` files live at the project root. Only set this when your dotenv files are in a non-standard location (e.g. a test fixture directory). |
-| `enforceProductionPropertyRules` | `boolean`  | `true`          | Restrict property access to match CDN production behavior                                                                                                                                                                                                                 |
-| `runnerType`                     | `WasmType` | auto-detected   | Override WASM type detection                                                                                                                                                                                                                                              |
+| Field                            | Type       | Default         | Description                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------- | ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dotenv.enabled`                 | `boolean`  | `false`         | Whether to load `.env` files                                                                                                                                                                                                                                                                                                                 |
+| `dotenv.path`                    | `string`   | `undefined`     | Directory to load dotenv files from. When omitted, `fastedge-run` uses the process CWD — correct for most npm package users whose `.env` files live at the project root. Only set this when your dotenv files are in a non-standard location (e.g. a test fixture directory).                                                                |
+| `enforceProductionPropertyRules` | `boolean`  | `true`          | Restrict property access to match CDN production behavior                                                                                                                                                                                                                                                                                    |
+| `runnerType`                     | `WasmType` | *auto-detected* | Override WASM type detection                                                                                                                                                                                                                                                                                                                 |
+| `httpPort`                       | `number`   | `undefined`     | HTTP-WASM only. Pin the spawned `fastedge-run` subprocess to a specific port instead of allocating from the dynamic pool (8100–8199). `load()` throws if the port is busy — there is no fallback to dynamic allocation. Intended for Codespaces/Docker port-forwarding or external tooling requiring a fixed address. Ignored for proxy-wasm. |
 
 ### HttpRequest & HttpResponse
 
@@ -329,7 +357,11 @@ interface HttpRequest {
 interface HttpResponse {
   status: number;
   statusText: string;
-  headers: Record<string, string>;
+  // Node's IncomingHttpHeaders (from "node:http"):
+  //   known single-valued headers (content-type, location, etag, …) are typed as string
+  //   set-cookie is always string[] when present
+  //   unknown headers are string | string[] | undefined
+  headers: IncomingHttpHeaders;
   body: string;
   contentType: string | null;
   isBase64?: boolean;
@@ -343,20 +375,37 @@ interface HttpResponse {
 
 `HttpResponse.logs` contains log entries captured from the `fastedge-run` process stdout/stderr during the request.
 
+**Multi-valued headers.** `Set-Cookie` is preserved as a `string[]` — each `Set-Cookie` header emitted by the WASM app (or an upstream origin) becomes a separate array entry. This matches RFC 6265 §3 and Node's fetch behavior. Example:
+
+```typescript
+const response = await runner.execute({ path: '/login', method: 'POST', headers: {} });
+const cookies = response.headers['set-cookie']; // string[] | undefined
+for (const cookie of cookies ?? []) {
+  console.log(cookie);
+}
+```
+
+Single-valued headers read as plain strings with no narrowing needed:
+
+```typescript
+const location = response.headers['location'];        // string | undefined
+const contentType = response.headers['content-type']; // string | undefined
+```
+
 ### HookCall
 
 ```typescript
 type HookCall = {
   hook: string;
   request: {
-    headers: HeaderMap;
+    headers: HeaderRecord;
     body: string;
     method?: string;
     path?: string;
     scheme?: string;
   };
-  response: {
-    headers: HeaderMap;
+  response?: {
+    headers: HeaderRecord;
     body: string;
     status?: number;
     statusText?: string;
@@ -367,14 +416,16 @@ type HookCall = {
 };
 ```
 
-| Field                            | Description                                                                                         |
-| -------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `hook`                           | Hook name: `"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`       |
-| `request`                        | Request state passed to the hook                                                                    |
-| `response`                       | Response state passed to the hook                                                                   |
-| `properties`                     | Shared properties (e.g. `request.path`, `vm_config`, `plugin_config`)                               |
-| `dotenvEnabled`                  | Optional per-call dotenv override. Use `applyDotenv()` for persistent changes.                      |
-| `enforceProductionPropertyRules` | Defaults to `true`. Set to `false` to allow property reads that would be blocked on production CDN. |
+| Field                            | Description                                                                                                                                                                  |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hook`                           | Hook name: `"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`                                                                                |
+| `request`                        | Request state passed to the hook                                                                                                                                             |
+| `response`                       | Seed state for response hooks called via `callHook()`. Ignored by `callFullFlow()` and by request hooks — the full-flow path generates the upstream response at runtime.     |
+| `properties`                     | Shared properties (e.g. `request.path`, `vm_config`, `plugin_config`)                                                                                                       |
+| `dotenvEnabled`                  | Optional per-call dotenv override. Use `applyDotenv()` for persistent changes.                                                                                              |
+| `enforceProductionPropertyRules` | Defaults to `true`. Set to `false` to allow property reads that would be blocked on production CDN.                                                                         |
+
+`HeaderRecord` is `Record<string, string | string[]>` — multi-valued headers (e.g. multiple `Set-Cookie`) are represented as `string[]`.
 
 ### HookResult
 
@@ -383,26 +434,26 @@ type HookResult = {
   returnCode: number | null;
   logs: { level: number; message: string }[];
   input: {
-    request: { headers: HeaderMap; body: string };
-    response: { headers: HeaderMap; body: string };
+    request: { headers: HeaderRecord; body: string };
+    response: { headers: HeaderRecord; body: string };
     properties?: Record<string, unknown>;
   };
   output: {
-    request: { headers: HeaderMap; body: string };
-    response: { headers: HeaderMap; body: string };
+    request: { headers: HeaderRecord; body: string };
+    response: { headers: HeaderRecord; body: string };
     properties?: Record<string, unknown>;
   };
   properties: Record<string, unknown>;
 };
 ```
 
-| Field        | Description                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------ |
-| `returnCode` | The numeric value returned by the WASM hook export, or `null` if the export was not found |
-| `logs`       | Log entries emitted via `proxy_log` during hook execution                                  |
-| `input`      | Request/response state as seen by the hook before execution                                |
-| `output`     | Request/response state after hook execution (reflects WASM mutations)                      |
-| `properties` | All shared properties after hook execution                                                 |
+| Field        | Description                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------- |
+| `returnCode` | The numeric value returned by the WASM hook export, or `null` if the export was not found  |
+| `logs`       | Log entries emitted via `proxy_log` during hook execution                                   |
+| `input`      | Request/response state as seen by the hook before execution                                 |
+| `output`     | Request/response state after hook execution (reflects WASM mutations)                       |
+| `properties` | All shared properties after hook execution                                                  |
 
 ### FullFlowResult
 
@@ -412,7 +463,7 @@ type FullFlowResult = {
   finalResponse: {
     status: number;
     statusText: string;
-    headers: HeaderMap;
+    headers: HeaderRecord;
     body: string;
     contentType: string;
     isBase64?: boolean;
@@ -421,19 +472,23 @@ type FullFlowResult = {
 };
 ```
 
-| Field                  | Description                                                                                                                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hookResults`          | A `Record` keyed by hook name (`"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`), each containing a `HookResult`                          |
-| `finalResponse`        | The final response after all hooks have executed, or the local response if a hook short-circuited (see `callFullFlow`). `body` is base64-encoded when `isBase64` is `true`. |
-| `calculatedProperties` | Runtime properties computed from the request URL (e.g. `request.path`, `request.host`)                                                                                      |
+| Field                  | Description                                                                                                                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hookResults`          | A `Record` keyed by hook name (`"onRequestHeaders"`, `"onRequestBody"`, `"onResponseHeaders"`, `"onResponseBody"`), each containing a `HookResult`                           |
+| `finalResponse`        | The final response after all hooks have executed, or the local response if a hook short-circuited (see `callFullFlow`). `body` is base64-encoded when `isBase64` is `true`.  |
+| `calculatedProperties` | Runtime properties computed from the request URL (e.g. `request.path`, `request.host`)                                                                                       |
 
 ### Supporting Types
 
 ```typescript
 type WasmType = 'http-wasm' | 'proxy-wasm';
 
+// Single-valued headers only — used as callFullFlow input parameters
 type HeaderMap = Record<string, string>;
 
+// Single- or multi-valued headers — used in HookCall, HookResult, and FullFlowResult
+type HeaderRecord = Record<string, string | string[]>;
+
 type LogEntry = {
   level: number;
   message: string;
@@ -461,7 +516,7 @@ interface IStateManager {
   emitRequestStarted(
     url: string,
     method: string,
-    headers: Record<string, string>,
+    headers: Record<string, string | string[]>,
     source?: EventSource,
   ): void;
 
@@ -470,12 +525,12 @@ interface IStateManager {
     returnCode: number | null,
     logCount: number,
     input: {
-      request: { headers: Record<string, string>; body: string };
-      response: { headers: Record<string, string>; body: string };
+      request: { headers: Record<string, string | string[]>; body: string };
+      response: { headers: Record<string, string | string[]>; body: string };
     },
     output: {
-      request: { headers: Record<string, string>; body: string };
-      response: { headers: Record<string, string>; body: string };
+      request: { headers: Record<string, string | string[]>; body: string };
+      response: { headers: Record<string, string | string[]>; body: string };
     },
     source?: EventSource,
   ): void;
@@ -485,7 +540,7 @@ interface IStateManager {
     finalResponse: {
       status: number;
       statusText: string;
-      headers: Record<string, string>;
+      headers: Record<string, string | string[]>;
       body: string;
       contentType: string;
       isBase64?: boolean;
@@ -507,7 +562,7 @@ interface IStateManager {
     response: {
       status: number;
       statusText: string;
-      headers: Record<string, string>;
+      headers: Record<string, string | string[] | undefined>;
       body: string;
       contentType: string | null;
       isBase64?: boolean;
@@ -538,19 +593,15 @@ async function testCdnApp() {
   try {
     // Execute the full CDN request/response lifecycle
     const result: FullFlowResult = await runner.callFullFlow(
-      'https://example.com/api/data',          // request URL
-      'GET',                                    // method
-      { 'accept': 'application/json' },         // request headers
-      '',                                       // request body
-      { 'content-type': 'application/json' },   // upstream response headers
-      '{"key":"value"}',                        // upstream response body
-      200,                                      // upstream response status
-      'OK',                                     // upstream response status text
+      'https://example.com/api/data',   // request URL
+      'GET',                            // method
+      { 'accept': 'application/json' }, // request headers
+      '',                               // request body
       {
         'request.path': '/api/data',
         'request.host': 'example.com',
-      },                                        // shared properties
-      true,                                     // enforce production property rules
+      },                                // shared properties
+      true,                             // enforce production property rules
     );
 
     // Inspect hook results
@@ -606,11 +657,12 @@ async function testCdnAppOffline() {
   try {
     // Use built-in responder — no origin server required
     const result: FullFlowResult = await runner.callFullFlow(
-      BUILTIN_SHORTHAND,  // generates a local response instead of fetching
+      BUILTIN_SHORTHAND, // generates a local response instead of fetching
       'GET',
       { 'accept': 'application/json' },
       '',
-      {}, '', 200, 'OK', {}, true,
+      {},   // properties
+      true, // enforceProductionPropertyRules
     );
 
     console.log('Final status:', result.finalResponse.status);

package/docs/TEST_CONFIG.md

@@ -1,6 +1,6 @@
 # Test Configuration
 
-Configuration file reference for `fastedge-config.test.json` — the per-test JSON file that defines the WASM binary, request, response, CDN properties, and environment variable loading for a single test scenario.
+Configuration file reference for `fastedge-config.test.json` — the per-test JSON file that defines the WASM binary, request, CDN properties, and environment variable loading for a single test scenario.
 
 ## Overview
 
@@ -8,8 +8,8 @@ Each test scenario is described by a `fastedge-config.test.json` file. The file
 
 The config schema is a union of two variants selected by `appType`:
 
-- **`proxy-wasm`** (CDN mode, default): The WASM module intercepts an upstream HTTP request. Uses `request.url` (full URL). Supports a mock origin `response`.
-- **`http-wasm`**: The WASM module acts as an origin HTTP server. Uses `request.path` (path only). No `response` field.
+- **`proxy-wasm`** (CDN mode, default): The WASM module intercepts an upstream HTTP request. Uses `request.url` (full URL). The upstream response is generated at runtime — either by a real fetch against `request.url`, or by the built-in responder when `request.url === "built-in"`.
+- **`http-wasm`**: The WASM module acts as an origin HTTP server. Uses `request.path` (path only).
 
 **Required fields** (per JSON Schema `required` arrays):
 - Top-level: `properties`, `appType`, and `request`
@@ -22,27 +22,25 @@ The config schema is a union of two variants selected by `appType`:
 
 ### Top-Level Fields
 
-| JSON Path            | Type      | Required (Schema)                      | Default          | Description                                                                                           |
-| -------------------- | --------- | -------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
-| `$schema`            | `string`  | No                                     | —                | URI pointing to the JSON Schema file for IDE autocompletion and validation.                           |
-| `description`        | `string`  | No                                     | —                | Human-readable label for this test scenario.                                                          |
-| `wasm`               | `object`  | No                                     | —                | WASM binary configuration. Required when running without a programmatic `wasmBuffer`.                 |
-| `wasm.path`          | `string`  | Yes (if `wasm` present)                | —                | Path to the compiled `.wasm` binary, relative to the config file or absolute.                        |
-| `wasm.description`   | `string`  | No                                     | —                | Human-readable label for the WASM binary.                                                             |
-| `appType`            | `string`  | Yes (schema) / CDN has runtime default | `"proxy-wasm"`   | App variant. `"proxy-wasm"` for CDN mode; `"http-wasm"` for HTTP mode. HTTP-WASM has no default.    |
-| `request`            | `object`  | **Yes**                                | —                | Incoming HTTP request to simulate.                                                                    |
-| `request.method`     | `string`  | Yes (schema) / runtime default         | `"GET"`          | HTTP method (e.g. `"GET"`, `"POST"`).                                                                 |
-| `request.url`        | `string`  | **Yes** (CDN only)                     | —                | Full URL for the simulated upstream request (e.g. `"https://example.com/api"`). CDN mode only.       |
-| `request.path`       | `string`  | **Yes** (HTTP-WASM only)               | —                | Request path (e.g. `"/api/submit"`). HTTP-WASM mode only. The WASM module acts as the origin server. |
-| `request.headers`    | `object`  | Yes (schema) / runtime default         | `{}`             | Key/value map of request headers. All keys and values must be strings.                                |
-| `request.body`       | `string`  | Yes (schema) / runtime default         | `""`             | Request body as a plain string. Use an empty string for requests with no body.                        |
-| `response`           | `object`  | No                                     | —                | Mock origin response for CDN mode. Not applicable to HTTP-WASM.                                       |
-| `response.headers`   | `object`  | Yes (if `response` present)            | `{}`             | Key/value map of mock origin response headers.                                                        |
-| `response.body`      | `string`  | Yes (if `response` present)            | `""`             | Mock origin response body as a plain string.                                                          |
-| `properties`         | `object`  | **Yes** (schema) / runtime default     | `{}`             | CDN property key/value pairs passed to the WASM execution context. Values may be any JSON type.      |
-| `dotenv`             | `object`  | No                                     | —                | Dotenv file loading configuration.                                                                    |
-| `dotenv.enabled`     | `boolean` | No                                     | —                | Whether to load a `.env` file before execution.                                                       |
-| `dotenv.path`        | `string`  | No                                     | —                | Path to the `.env` file. If omitted, resolves `.env` relative to the config file directory.          |
+| JSON Path            | Type      | Required (Schema)                      | Default        | Description                                                                                                                                            |
+| -------------------- | --------- | -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `$schema`            | `string`  | No                                     | —              | URI pointing to the JSON Schema file for IDE autocompletion and validation.                                                                            |
+| `description`        | `string`  | No                                     | —              | Human-readable label for this test scenario.                                                                                                           |
+| `wasm`               | `object`  | No                                     | —              | WASM binary configuration. Required when running without a programmatic `wasmBuffer`.                                                                  |
+| `wasm.path`          | `string`  | Yes (if `wasm` present)                | —              | Path to the compiled `.wasm` binary, relative to the config file or absolute.                                                                         |
+| `wasm.description`   | `string`  | No                                     | —              | Human-readable label for the WASM binary.                                                                                                              |
+| `appType`            | `string`  | Yes (schema) / CDN has runtime default | `"proxy-wasm"` | App variant. `"proxy-wasm"` for CDN mode; `"http-wasm"` for HTTP mode. HTTP-WASM has no default.                                                      |
+| `request`            | `object`  | **Yes**                                | —              | Incoming HTTP request to simulate.                                                                                                                     |
+| `request.method`     | `string`  | Yes (schema) / runtime default         | `"GET"`        | HTTP method (e.g. `"GET"`, `"POST"`).                                                                                                                  |
+| `request.url`        | `string`  | **Yes** (CDN only)                     | —              | Full URL for the simulated upstream request (e.g. `"https://example.com/api"`). CDN mode only.                                                        |
+| `request.path`       | `string`  | **Yes** (HTTP-WASM only)               | —              | Request path (e.g. `"/api/submit"`). HTTP-WASM mode only. The WASM module acts as the origin server.                                                  |
+| `request.headers`    | `object`  | Yes (schema) / runtime default         | `{}`           | Key/value map of request headers. All keys and values must be strings.                                                                                 |
+| `request.body`       | `string`  | Yes (schema) / runtime default         | `""`           | Request body as a plain string. Use an empty string for requests with no body.                                                                         |
+| `properties`         | `object`  | **Yes** (schema) / runtime default     | `{}`           | CDN property key/value pairs passed to the WASM execution context. Values may be any JSON type.                                                        |
+| `dotenv`             | `object`  | No                                     | —              | Dotenv file loading configuration.                                                                                                                     |
+| `dotenv.enabled`     | `boolean` | No                                     | —              | Whether to load a `.env` file before execution.                                                                                                        |
+| `dotenv.path`        | `string`  | No                                     | —              | Path to the `.env` file. If omitted, resolves `.env` relative to the config file directory.                                                            |
+| `httpPort`           | `integer` | No                                     | —              | HTTP-WASM only. Pin the subprocess to a specific port (1024–65535) instead of dynamic allocation from the 8100–8199 pool. Throws if the port is busy. |
 
 ### Required vs. Default Distinction
 
@@ -64,6 +62,55 @@ When `dotenv.enabled` is `true`, the runner loads a `.env` file and merges its c
 
 **Security note**: Do not commit `.env` files containing secrets. Add `.env` to `.gitignore` and use `dotenv.enabled: true` with `dotenv.path` pointing to a file that exists only in the local or CI environment.
 
+## HTTP Port Pinning
+
+`httpPort` is an optional integer field available only in HTTP-WASM configs (`appType: "http-wasm"`). It pins the `fastedge-run` subprocess to a fixed port instead of dynamically allocating one from the pool (8100–8199). The schema rejects `httpPort` on proxy-wasm configs.
+
+### Default Behaviour
+
+Without `httpPort`, the runner allocates a port from the 8100–8199 range for each test run. The allocated port is not stable across runs.
+
+### When to Use Port Pinning
+
+- **Codespaces / Docker port-forwarding**: Port-forward rules reference a specific port number. Without pinning, the port changes between runs and breaks the forwarding rule.
+- **Stable live-preview URLs**: Browser tabs or external tooling pointing at a fixed URL (e.g. `http://localhost:8250`) require a stable port.
+- **External tooling integration**: Monitoring, load testing, or proxy configurations that hard-code a target address.
+
+### Fail-Fast Semantics
+
+If the pinned port is already in use, `HttpWasmRunner.load()` throws immediately:
+
+```
+fastedge-run port 8250 is not available — release it or choose a different httpPort in fastedge-config.test.json
+```
+
+There is no fallback to dynamic allocation. Free the port or choose a different one before running.
+
+### Port Range Considerations
+
+Pinning a port inside the 8100–8199 dynamic pool is allowed by the schema but risks collisions with other concurrent debug sessions using dynamic allocation. For production-like setups or shared environments, choose a port outside the pool (e.g. 8250 or any unused port above 8199).
+
+### Example
+
+```json
+{
+  "$schema": "./node_modules/@gcoredev/fastedge-test/schemas/fastedge-config.test.schema.json",
+  "description": "HTTP-WASM handler with pinned port for Codespaces",
+  "appType": "http-wasm",
+  "wasm": {
+    "path": "./dist/http-handler.wasm"
+  },
+  "request": {
+    "method": "GET",
+    "path": "/health",
+    "headers": {},
+    "body": ""
+  },
+  "properties": {},
+  "httpPort": 8250
+}
+```
+
 ## Examples
 
 ### Minimal CDN Configuration
@@ -153,37 +200,32 @@ An HTTP-WASM scenario simulating a `POST` request with a JSON body. `appType` mu
 }
 ```
 
-### Custom Origin Response
+### Built-In Responder (No Network)
 
-A CDN scenario where the mock origin returns a specific response. Use this to test how the WASM handler transforms or conditionally passes through origin responses.
+A CDN scenario that uses the test runner's built-in responder instead of reaching out to a real origin. Set `request.url` to `"built-in"` — the runner generates a local response and skips the upstream fetch. This is the fastest way to exercise a CDN WASM app without depending on network reachability.
 
 ```json
 {
   "$schema": "./node_modules/@gcoredev/fastedge-test/schemas/fastedge-config.test.schema.json",
-  "description": "CDN handler with custom mock origin response",
+  "description": "CDN handler against the built-in responder",
   "appType": "proxy-wasm",
   "wasm": {
     "path": "./dist/handler.wasm"
   },
   "request": {
     "method": "GET",
-    "url": "https://example.com/cached-resource",
+    "url": "built-in",
     "headers": {},
     "body": ""
   },
-  "response": {
-    "headers": {
-      "content-type": "application/json",
-      "cache-control": "max-age=86400"
-    },
-    "body": "{\"status\": \"ok\", \"data\": []}"
-  },
   "properties": {
     "CACHE_TTL": 86400
   }
 }
 ```
 
+The default built-in response is a full JSON echo of the request. Override via control headers on the request: `x-debugger-status` sets the HTTP status; `x-debugger-content: status-only` omits the body; `x-debugger-content: body-only` echoes only the request body (with its inferred content-type).
+
 ## IDE Integration
 
 Adding `$schema` to your config file enables JSON Schema validation and autocompletion in VSCode and any editor that supports the JSON Language Server.
@@ -240,10 +282,6 @@ type CdnConfig = {
     headers: Record<string, string>;       // default: {}
     body:    string;                       // default: ""
   };
-  response?: {
-    headers: Record<string, string>;       // default: {}
-    body:    string;                       // default: ""
-  };
   properties: Record<string, unknown>;     // default: {}
   dotenv?: {
     enabled?: boolean;
@@ -265,6 +303,7 @@ type HttpConfig = {
     headers: Record<string, string>;       // default: {}
     body:    string;                       // default: ""
   };
+  httpPort?:    number;                    // pin subprocess port (1024–65535); throws if busy
   properties: Record<string, unknown>;     // default: {}
   dotenv?: {
     enabled?: boolean;
@@ -282,9 +321,9 @@ const config = await loadConfigFile("./fastedge-config.test.json");
 
 if (config.appType === "proxy-wasm") {
   console.log(config.request.url);   // string — CDN full URL
-  console.log(config.response);      // ResponseConfig | undefined
 } else {
   console.log(config.request.path);  // string — HTTP-WASM path
+  console.log(config.httpPort);      // number | undefined
 }
 ```