@gcoredev/fastedge-test 0.1.6 → 0.2.0

package/dist/lib/runner/IWasmRunner.d.ts

@@ -3,6 +3,7 @@
  *
  * Defines the common contract for both ProxyWasmRunner and HttpWasmRunner
  */
+import type { IncomingHttpHeaders } from "node:http";
 import type { IStateManager } from "./IStateManager.js";
 import type { HookCall, HookResult, FullFlowResult } from "./types.js";
 export type WasmType = "http-wasm" | "proxy-wasm";
@@ -18,6 +19,15 @@ export interface RunnerConfig {
     enforceProductionPropertyRules?: boolean;
     /** Override automatic WASM type detection. Use when detection produces wrong results. */
     runnerType?: WasmType;
+    /**
+     * HTTP-WASM only. Pin the spawned `fastedge-run` HTTP server to a specific
+     * port instead of allocating from the dynamic pool (8100-8199). Intended for
+     * Codespaces/Docker port-forwarding setups, stable live-preview URLs, or any
+     * external tooling that requires a fixed target. `load()` throws if the port
+     * is already in use — there is no fallback to dynamic allocation. Ignored
+     * for proxy-wasm runners.
+     */
+    httpPort?: number;
 }
 /**
  * HTTP Request type for HTTP WASM runner
@@ -29,12 +39,18 @@ export interface HttpRequest {
     body?: string;
 }
 /**
- * HTTP Response type for HTTP WASM runner
+ * HTTP Response type for HTTP WASM runner.
+ *
+ * `headers` uses Node's `IncomingHttpHeaders` shape — common single-valued
+ * headers (`content-type`, `location`, `etag`, …) are typed as `string`;
+ * `set-cookie` is `string[]`; unknown keys are `string | string[] | undefined`.
+ * This preserves RFC 6265 Set-Cookie semantics (each cookie kept separate)
+ * and matches consumer expectations for Node's fetch/http ecosystem.
  */
 export interface HttpResponse {
     status: number;
     statusText: string;
-    headers: Record<string, string>;
+    headers: IncomingHttpHeaders;
     body: string;
     contentType: string | null;
     isBase64?: boolean;
@@ -54,7 +70,22 @@ export interface IWasmRunner {
      */
     load(bufferOrPath: Buffer | string, config?: RunnerConfig): Promise<void>;
     /**
-     * Execute a request through the WASM module (HTTP WASM only)
+     * Execute a request through the WASM module (HTTP WASM only).
+     *
+     * Redirects are surfaced verbatim — the underlying fetch uses
+     * `redirect: "manual"` so tests can assert on 3xx status and the `Location`
+     * header. This matches how a FastEdge edge deployment returns redirects to
+     * the client rather than following them server-side.
+     *
+     * `execute` only hits the WASM app under test — `request.path` is a path on
+     * the spawned `fastedge-run` server, not a full URL. To follow a redirect
+     * the caller must inspect `response.headers.location`:
+     * - Relative Location (`/foo`) — reuse as `request.path` directly.
+     * - Absolute same-host Location — extract `pathname + search` via `new URL()`
+     *   and re-issue with that path.
+     * - Absolute cross-host Location — cannot be followed through the runner;
+     *   the 302 is the terminal state for the test.
+     *
      * @param request The HTTP request to execute
      * @returns The HTTP response
      */
@@ -66,20 +97,21 @@ export interface IWasmRunner {
      */
     callHook(hookCall: HookCall): Promise<HookResult>;
     /**
-     * Execute full request/response flow (Proxy-WASM only)
-     * @param url Request URL
+     * Execute full request/response flow (Proxy-WASM only).
+     *
+     * 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 fixture-level mock response.
+     *
+     * @param url Request URL, or `"built-in"` to use the built-in responder
      * @param method HTTP method
      * @param headers Request headers
      * @param body Request body
-     * @param responseHeaders Response headers
-     * @param responseBody Response body
-     * @param responseStatus Response status code
-     * @param responseStatusText Response status text
      * @param properties Shared properties
      * @param enforceProductionPropertyRules Whether to enforce property access rules
      * @returns Full flow execution result
      */
-    callFullFlow(url: string, 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>;
+    callFullFlow(url: string, method: string, headers: Record<string, string>, body: string, properties: Record<string, unknown>, enforceProductionPropertyRules: boolean): Promise<FullFlowResult>;
     /**
      * Apply dotenv settings to the current runner without reloading the WASM.
      * For ProxyWasmRunner: resets stores and re-loads dotenv files in-place.

package/dist/lib/runner/PortManager.d.ts

@@ -18,8 +18,11 @@ export declare class PortManager {
      * This is necessary when multiple server processes run simultaneously —
      * each has its own PortManager with independent in-memory state, so
      * in-memory tracking alone is not enough to prevent cross-process conflicts.
+     *
+     * Public so pinned-port callers (HttpWasmRunner with RunnerConfig.httpPort)
+     * can reuse the same OS-level check without going through allocate().
      */
-    private isPortFree;
+    isPortFree(port: number): Promise<boolean>;
     /**
      * Allocate an available port from the pool.
      * Combines in-memory tracking (avoids TCP TIME_WAIT reuse within this process)

package/dist/lib/runner/PropertyResolver.d.ts

@@ -1,4 +1,4 @@
-import type { HeaderMap } from "./types";
+import type { HeaderMap, HeaderRecord } from "./types";
 export declare class PropertyResolver {
     private properties;
     private requestHeaders;
@@ -28,13 +28,13 @@ export declare class PropertyResolver {
      * User properties take precedence over calculated ones
      */
     getAllProperties(): Record<string, unknown>;
-    setRequestMetadata(headers: HeaderMap, method: string, path?: string, scheme?: string): void;
+    setRequestMetadata(headers: HeaderMap | HeaderRecord, method: string, path?: string, scheme?: string): void;
     /**
      * Extract runtime properties from target URL
      * This parses the URL to populate request.url, request.host, request.path, etc.
      */
     extractRuntimePropertiesFromUrl(targetUrl: string): void;
-    setResponseMetadata(headers: HeaderMap, status: number, statusText: string): void;
+    setResponseMetadata(headers: HeaderMap | HeaderRecord, status: number, statusText: string): void;
     resolve(path: string): unknown;
     private resolveStandard;
     private resolvePathSegments;

package/dist/lib/runner/ProxyWasmRunner.d.ts

@@ -59,9 +59,12 @@ export declare class ProxyWasmRunner implements IWasmRunner {
     private getHookContext;
     private logDebug;
     /**
-     * Interface-compliant callFullFlow method
+     * Interface-compliant callFullFlow method.
+     *
+     * The upstream response is generated at runtime by a real HTTP fetch
+     * against `url` or by the built-in responder when `url === "built-in"`.
      */
-    callFullFlow(url: string, 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>;
+    callFullFlow(url: string, method: string, headers: Record<string, string>, body: string, properties: Record<string, unknown>, enforceProductionPropertyRules: boolean): Promise<FullFlowResult>;
     /**
      * Not supported for Proxy-WASM (HTTP WASM only)
      */

package/dist/lib/runner/standalone.d.ts

@@ -7,7 +7,7 @@
  * Usage:
  *   import { createRunner } from './server/runner/standalone.js';
  *   const runner = await createRunner('./path/to/wasm.wasm');
- *   const result = await runner.callFullFlow('https://example.com', 'GET', {}, '', {}, '', 200, 'OK', {}, true);
+ *   const result = await runner.callFullFlow('https://example.com', 'GET', {}, '', {}, true);
  */
 import type { IWasmRunner, RunnerConfig } from "./IWasmRunner.js";
 /**

package/dist/lib/runner/types.d.ts

@@ -1,16 +1,25 @@
 export type HeaderMap = Record<string, string>;
 export type HeaderTuples = [string, string][];
+export type HeaderRecord = Record<string, string | string[]>;
 export type HookCall = {
     hook: string;
     request: {
-        headers: HeaderMap;
+        headers: HeaderRecord;
         body: string;
         method?: string;
         path?: string;
         scheme?: string;
     };
-    response: {
-        headers: HeaderMap;
+    /**
+     * Seed state for the response hooks (`onResponseHeaders` / `onResponseBody`)
+     * when calling them in isolation via `callHook()`. The full-flow path
+     * (`callFullFlow`) generates the upstream response at runtime and does not
+     * consume this field — request hooks ignore it, and response hooks are
+     * called with the response built from the live origin fetch or built-in
+     * responder output.
+     */
+    response?: {
+        headers: HeaderRecord;
         body: string;
         status?: number;
         statusText?: string;
@@ -27,22 +36,22 @@ export type HookResult = {
     }[];
     input: {
         request: {
-            headers: HeaderMap;
+            headers: HeaderRecord;
             body: string;
         };
         response: {
-            headers: HeaderMap;
+            headers: HeaderRecord;
             body: string;
         };
         properties?: Record<string, unknown>;
     };
     output: {
         request: {
-            headers: HeaderMap;
+            headers: HeaderRecord;
             body: string;
         };
         response: {
-            headers: HeaderMap;
+            headers: HeaderRecord;
             body: string;
         };
         properties?: Record<string, unknown>;
@@ -78,7 +87,7 @@ export type FullFlowResult = {
     finalResponse: {
         status: number;
         statusText: string;
-        headers: HeaderMap;
+        headers: HeaderRecord;
         body: string;
         contentType: string;
         isBase64?: boolean;

package/dist/lib/schemas/api.d.ts

@@ -6,6 +6,7 @@ export declare const ApiLoadBodySchema: z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    httpPort: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const ApiSendBodySchema: z.ZodObject<{
     url: z.ZodUnion<readonly [z.ZodLiteral<"built-in">, z.ZodString]>;
@@ -15,10 +16,6 @@ export declare const ApiSendBodySchema: z.ZodObject<{
         headers: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>>;
         body: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
     }, z.core.$strip>>;
-    response: z.ZodOptional<z.ZodObject<{
-        headers: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>>;
-        body: z.ZodOptional<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
-    }, z.core.$strip>>;
     properties: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$strip>;
 export declare const ApiCallBodySchema: z.ZodObject<{
@@ -52,6 +49,7 @@ export declare const ApiConfigBodySchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         appType: z.ZodLiteral<"http-wasm">;
+        httpPort: z.ZodOptional<z.ZodNumber>;
         request: z.ZodObject<{
             method: z.ZodDefault<z.ZodString>;
             path: z.ZodString;
@@ -77,10 +75,6 @@ export declare const ApiConfigBodySchema: z.ZodObject<{
             headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
             body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         }, z.core.$strip>;
-        response: z.ZodOptional<z.ZodObject<{
-            headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-            body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-        }, z.core.$strip>>;
     }, z.core.$strip>]>;
 }, z.core.$strip>;
 export type ApiLoadBody = z.infer<typeof ApiLoadBodySchema>;

package/dist/lib/schemas/config.d.ts

@@ -15,10 +15,6 @@ export declare const HttpRequestConfigSchema: z.ZodObject<{
     headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
-export declare const ResponseConfigSchema: z.ZodObject<{
-    headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-    body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-}, z.core.$strip>;
 declare const CdnConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -38,10 +34,6 @@ declare const CdnConfigSchema: z.ZodObject<{
         headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
         body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     }, z.core.$strip>;
-    response: z.ZodOptional<z.ZodObject<{
-        headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-        body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const HttpConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
@@ -56,6 +48,7 @@ declare const HttpConfigSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     appType: z.ZodLiteral<"http-wasm">;
+    httpPort: z.ZodOptional<z.ZodNumber>;
     request: z.ZodObject<{
         method: z.ZodDefault<z.ZodString>;
         path: z.ZodString;
@@ -76,6 +69,7 @@ export declare const TestConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     appType: z.ZodLiteral<"http-wasm">;
+    httpPort: z.ZodOptional<z.ZodNumber>;
     request: z.ZodObject<{
         method: z.ZodDefault<z.ZodString>;
         path: z.ZodString;
@@ -101,10 +95,6 @@ export declare const TestConfigSchema: z.ZodUnion<readonly [z.ZodObject<{
         headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
         body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     }, z.core.$strip>;
-    response: z.ZodOptional<z.ZodObject<{
-        headers: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
-        body: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    }, z.core.$strip>>;
 }, z.core.$strip>]>;
 export declare const RequestConfigSchema: z.ZodObject<{
     method: z.ZodDefault<z.ZodString>;
@@ -116,7 +106,6 @@ export type WasmConfig = z.infer<typeof WasmConfigSchema>;
 export type CdnRequestConfig = z.infer<typeof CdnRequestConfigSchema>;
 export type HttpRequestConfig = z.infer<typeof HttpRequestConfigSchema>;
 export type RequestConfig = z.infer<typeof CdnRequestConfigSchema>;
-export type ResponseConfig = z.infer<typeof ResponseConfigSchema>;
 export type CdnConfig = z.infer<typeof CdnConfigSchema>;
 export type HttpConfig = z.infer<typeof HttpConfigSchema>;
 export type TestConfig = z.infer<typeof TestConfigSchema>;

package/dist/lib/schemas/index.d.ts

@@ -1,4 +1,4 @@
-export { WasmConfigSchema, RequestConfigSchema, ResponseConfigSchema, TestConfigSchema, } from './config';
-export type { WasmConfig, RequestConfig, ResponseConfig, TestConfig, } from './config';
+export { WasmConfigSchema, RequestConfigSchema, TestConfigSchema, } from './config';
+export type { WasmConfig, RequestConfig, TestConfig, } from './config';
 export { ApiLoadBodySchema, ApiSendBodySchema, ApiCallBodySchema, ApiConfigBodySchema, } from './api';
 export type { ApiLoadBody, ApiSendBody, ApiCallBody, ApiConfigBody, } from './api';

package/dist/lib/test-framework/assertions.d.ts

@@ -9,8 +9,12 @@ import type { HttpResponse } from "../runner/IWasmRunner.js";
 /**
  * Assert that a named header exists (and optionally matches a value)
  * in the hook's output request headers.
+ *
+ * When `expected` is a string and the header is multi-valued, passes if
+ * any value matches (`.includes()` semantics). When `expected` is a string[],
+ * requires an exact array match.
  */
-export declare function assertRequestHeader(result: HookResult, name: string, expected?: string): void;
+export declare function assertRequestHeader(result: HookResult, name: string, expected?: string | string[]): void;
 /**
  * Assert that a named header is absent in the hook's output request headers.
  */
@@ -18,8 +22,12 @@ export declare function assertNoRequestHeader(result: HookResult, name: string):
 /**
  * Assert that a named header exists (and optionally matches a value)
  * in the hook's output response headers.
+ *
+ * When `expected` is a string and the header is multi-valued (e.g. set-cookie),
+ * passes if any value matches (`.includes()` semantics). When `expected` is a
+ * string[], requires an exact array match.
  */
-export declare function assertResponseHeader(result: HookResult, name: string, expected?: string): void;
+export declare function assertResponseHeader(result: HookResult, name: string, expected?: string | string[]): void;
 /**
  * Assert that a named header is absent in the hook's output response headers.
  */
@@ -31,8 +39,10 @@ export declare function assertFinalStatus(result: FullFlowResult, expected: numb
 /**
  * Assert that a named header exists (and optionally matches a value)
  * in the final response headers from a full-flow run.
+ *
+ * Multi-value semantics match {@link assertResponseHeader}.
  */
-export declare function assertFinalHeader(result: FullFlowResult, name: string, expected?: string): void;
+export declare function assertFinalHeader(result: FullFlowResult, name: string, expected?: string | string[]): void;
 /**
  * Assert the hook return code (e.g. 0 = Ok, 1 = Pause).
  */
@@ -68,8 +78,12 @@ export declare function assertHttpStatus(response: HttpResponse, expected: numbe
 /**
  * Assert that a named header exists (and optionally matches a value)
  * in the HTTP response.
+ *
+ * Multi-value semantics: when `expected` is a string and the header is
+ * multi-valued (e.g. set-cookie is `string[]` per RFC 6265), passes if any
+ * value matches. When `expected` is a string[], requires exact array match.
  */
-export declare function assertHttpHeader(response: HttpResponse, name: string, expected?: string): void;
+export declare function assertHttpHeader(response: HttpResponse, name: string, expected?: string | string[]): void;
 /**
  * Assert that a named header is absent in the HTTP response.
  */