@nifrajs/runner 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @nifrajs/runner
+
+Run requests through a nifra app and capture **structured results** — the shared engine behind the
+website playground (humans) and the agent run/verify tool (an AI writes code → runs it → sees the
+failure → fixes it). It only touches `app.fetch(Request) → Response`, which is Web-standard, so it runs
+unchanged in the browser, Bun, Node, Deno, and on the edge — and depends on nothing.
+
+```ts
+import { runApp } from "@nifrajs/runner"
+import { app } from "./app"
+
+const results = await runApp(app, [
+  { path: "/users/1" },
+  { method: "POST", path: "/users", body: { name: "Ada" } },
+])
+// → [{ method, path, ok, status, headers, body, durationMs }, …]
+```
+
+- **`runApp(app, requests, options?)`** — run a batch in order; one `RunResult` per request. Never
+  throws: a crash on any request becomes that result's `error` and the batch continues.
+- **`runRequest(app, spec, options?)`** — a single request.
+
+A plain object/array `body` is JSON-encoded (with a JSON content-type unless you set one); a
+string/`Uint8Array` is sent as-is. Relative paths resolve against `options.origin`
+(default `http://nifra.local`). Body text is captured up to `options.maxBodyChars` (default 64 KB).
+
+It's a **runner, not a security sandbox**: it calls the app you hand it in-process, with no isolation.
+Isolation, when you need it, comes from the host — the browser tab for the playground, your own
+process/CI for the agent runner. Don't feed it code you wouldn't already run.

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Run requests through a nifra app and capture **structured results** — the shared engine behind the
+ * website playground (humans) and the agent run/verify tool (AI writes code → runs it → sees the
+ * failure → fixes). It only touches `app.fetch(Request) → Response`, which is Web-standard, so it runs
+ * unchanged in the browser, Bun, Node, Deno, and on the edge — and depends on nothing.
+ *
+ *   import { runApp } from "@nifrajs/runner"
+ *   const results = await runApp(app, [
+ *     { path: "/users/1" },
+ *     { method: "POST", path: "/users", body: { name: "Ada" } },
+ *   ])
+ *   // → [{ status: 200, ok: true, body: {...}, durationMs }, …]
+ *
+ * It is a *runner*, not a security sandbox: it calls the app you hand it in-process, with no isolation.
+ * Isolation, when you need it, comes from the host — the browser tab for the playground, your own
+ * process/CI for the agent runner. Don't feed it code you wouldn't already run.
+ */
+/** Anything with a Web-standard fetch handler — a nifra app, or any `(Request) => Response`. Declared
+ * structurally so this package has zero dependency on `@nifrajs/core`. */
+export interface AppLike {
+    fetch(request: Request): Response | Promise<Response>;
+}
+/** One request to drive through the app. */
+export interface RequestSpec {
+    /** HTTP method. Default `"GET"`. */
+    readonly method?: string;
+    /** Path (`"/users/1"`) or an absolute URL. Relative paths resolve against a local origin. */
+    readonly path: string;
+    /** Request headers. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Body. A plain object/array is JSON-encoded (with a JSON content-type unless you set one); a
+     * string/`Uint8Array` is sent as-is. Ignored for GET/HEAD (those can't carry a body). */
+    readonly body?: unknown;
+    /** Optional label echoed back on the result (handy in the playground UI). */
+    readonly label?: string;
+}
+/** The captured outcome of one request. */
+export interface RunResult {
+    readonly label?: string;
+    readonly method: string;
+    readonly path: string;
+    /** `true` when the app returned a 2xx response. `false` for non-2xx, or when `app.fetch` threw. */
+    readonly ok: boolean;
+    /** HTTP status — present when the app returned a response (absent when it threw). */
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Parsed JSON when the response is JSON; otherwise the (possibly truncated) text. */
+    readonly body?: unknown;
+    /** The response body as text, truncated to `maxBodyChars`. */
+    readonly bodyText?: string;
+    /** `true` when `bodyText` was cut to the cap. */
+    readonly truncated?: boolean;
+    /** Wall-clock time for this request, milliseconds. */
+    readonly durationMs: number;
+    /** Set when `app.fetch` threw (the app crashed) rather than returning a response. */
+    readonly error?: {
+        readonly name: string;
+        readonly message: string;
+        readonly stack?: string;
+    };
+}
+export interface RunOptions {
+    /** Origin used to resolve relative paths. Default `"http://nifra.local"`. */
+    readonly origin?: string;
+    /** Cap on captured body text, in characters. Default 65536. */
+    readonly maxBodyChars?: number;
+}
+/** Drive a single request through the app, capturing the outcome (never throws — a thrown app error
+ * becomes `result.error`). */
+export declare function runRequest(app: AppLike, spec: RequestSpec, options?: RunOptions): Promise<RunResult>;
+/**
+ * Run a batch of requests through the app, in order, and return a result per request. Never throws:
+ * an app crash on any request is captured as that result's `error` and the run continues.
+ */
+export declare function runApp(app: AppLike, requests: readonly RequestSpec[], options?: RunOptions): Promise<RunResult[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;0EAC0E;AAC1E,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CACtD;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uBAAuB;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD;6FACyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9F;AAED,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAgDD;8BAC8B;AAC9B,wBAAsB,UAAU,CAC9B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,CAAC,CA+CpB;AASD;;;GAGG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,SAAS,WAAW,EAAE,EAChC,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,SAAS,EAAE,CAAC,CAMtB"}

package/dist/index.js

@@ -0,0 +1,128 @@
+/**
+ * Run requests through a nifra app and capture **structured results** — the shared engine behind the
+ * website playground (humans) and the agent run/verify tool (AI writes code → runs it → sees the
+ * failure → fixes). It only touches `app.fetch(Request) → Response`, which is Web-standard, so it runs
+ * unchanged in the browser, Bun, Node, Deno, and on the edge — and depends on nothing.
+ *
+ *   import { runApp } from "@nifrajs/runner"
+ *   const results = await runApp(app, [
+ *     { path: "/users/1" },
+ *     { method: "POST", path: "/users", body: { name: "Ada" } },
+ *   ])
+ *   // → [{ status: 200, ok: true, body: {...}, durationMs }, …]
+ *
+ * It is a *runner*, not a security sandbox: it calls the app you hand it in-process, with no isolation.
+ * Isolation, when you need it, comes from the host — the browser tab for the playground, your own
+ * process/CI for the agent runner. Don't feed it code you wouldn't already run.
+ */
+const DEFAULT_ORIGIN = "http://nifra.local";
+const DEFAULT_MAX_BODY = 64 * 1024;
+const now = () => typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+const METHODS_WITHOUT_BODY = new Set(["GET", "HEAD"]);
+/** A plain JSON-ish object/array (encode it as JSON) — vs a string/binary body we pass through. */
+function isJsonBody(body) {
+    if (body === null || typeof body !== "object")
+        return false;
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer || body instanceof Blob)
+        return false;
+    if (typeof FormData !== "undefined" && body instanceof FormData)
+        return false;
+    if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream)
+        return false;
+    return true;
+}
+function buildRequest(spec, origin) {
+    const method = (spec.method ?? "GET").toUpperCase();
+    const url = /^https?:\/\//i.test(spec.path) ? spec.path : new URL(spec.path, origin).toString();
+    const headers = new Headers(spec.headers);
+    const init = { method, headers };
+    if (spec.body !== undefined && !METHODS_WITHOUT_BODY.has(method)) {
+        if (isJsonBody(spec.body)) {
+            if (!headers.has("content-type"))
+                headers.set("content-type", "application/json");
+            init.body = JSON.stringify(spec.body);
+        }
+        else {
+            init.body = spec.body;
+        }
+    }
+    return new Request(url, init);
+}
+function headersToObject(headers) {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}
+/** Drive a single request through the app, capturing the outcome (never throws — a thrown app error
+ * becomes `result.error`). */
+export async function runRequest(app, spec, options = {}) {
+    const origin = options.origin ?? DEFAULT_ORIGIN;
+    const maxBody = options.maxBodyChars ?? DEFAULT_MAX_BODY;
+    const method = (spec.method ?? "GET").toUpperCase();
+    const base = {
+        ...(spec.label === undefined ? {} : { label: spec.label }),
+        method,
+        path: spec.path,
+    };
+    const start = now();
+    let request;
+    try {
+        request = buildRequest(spec, origin);
+    }
+    catch (err) {
+        // A malformed spec (bad URL, GET-with-body via a custom method, …) — report it, don't throw.
+        return { ...base, ok: false, durationMs: now() - start, error: toError(err) };
+    }
+    try {
+        const res = await app.fetch(request);
+        const text = await res.text();
+        const truncated = text.length > maxBody;
+        const bodyText = truncated ? text.slice(0, maxBody) : text;
+        const contentType = res.headers.get("content-type") ?? "";
+        let body = bodyText;
+        if (contentType.includes("application/json") && text.length > 0) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                // Content-Type lied, or the body is partial — keep the text form.
+            }
+        }
+        return {
+            ...base,
+            ok: res.ok,
+            status: res.status,
+            statusText: res.statusText,
+            headers: headersToObject(res.headers),
+            body,
+            bodyText,
+            ...(truncated ? { truncated } : {}),
+            durationMs: now() - start,
+        };
+    }
+    catch (err) {
+        return { ...base, ok: false, durationMs: now() - start, error: toError(err) };
+    }
+}
+function toError(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message, ...(err.stack ? { stack: err.stack } : {}) };
+    }
+    return { name: "Error", message: String(err) };
+}
+/**
+ * Run a batch of requests through the app, in order, and return a result per request. Never throws:
+ * an app crash on any request is captured as that result's `error` and the run continues.
+ */
+export function runApp(app, requests, options = {}) {
+    return requests.reduce(async (acc, spec) => {
+        const results = await acc;
+        results.push(await runRequest(app, spec, options));
+        return results;
+    }, Promise.resolve([]));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nifrajs/runner",
+  "version": "0.1.0-alpha.1",
+  "description": "Run requests through a nifra app's fetch and capture structured results — the engine behind the playground and the agent run/verify tool. Dependency-free; runs in the browser, Bun, Node, Deno, and on the edge.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/runner"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+/**
+ * Run requests through a nifra app and capture **structured results** — the shared engine behind the
+ * website playground (humans) and the agent run/verify tool (AI writes code → runs it → sees the
+ * failure → fixes). It only touches `app.fetch(Request) → Response`, which is Web-standard, so it runs
+ * unchanged in the browser, Bun, Node, Deno, and on the edge — and depends on nothing.
+ *
+ *   import { runApp } from "@nifrajs/runner"
+ *   const results = await runApp(app, [
+ *     { path: "/users/1" },
+ *     { method: "POST", path: "/users", body: { name: "Ada" } },
+ *   ])
+ *   // → [{ status: 200, ok: true, body: {...}, durationMs }, …]
+ *
+ * It is a *runner*, not a security sandbox: it calls the app you hand it in-process, with no isolation.
+ * Isolation, when you need it, comes from the host — the browser tab for the playground, your own
+ * process/CI for the agent runner. Don't feed it code you wouldn't already run.
+ */
+
+/** Anything with a Web-standard fetch handler — a nifra app, or any `(Request) => Response`. Declared
+ * structurally so this package has zero dependency on `@nifrajs/core`. */
+export interface AppLike {
+  fetch(request: Request): Response | Promise<Response>
+}
+
+/** One request to drive through the app. */
+export interface RequestSpec {
+  /** HTTP method. Default `"GET"`. */
+  readonly method?: string
+  /** Path (`"/users/1"`) or an absolute URL. Relative paths resolve against a local origin. */
+  readonly path: string
+  /** Request headers. */
+  readonly headers?: Readonly<Record<string, string>>
+  /** Body. A plain object/array is JSON-encoded (with a JSON content-type unless you set one); a
+   * string/`Uint8Array` is sent as-is. Ignored for GET/HEAD (those can't carry a body). */
+  readonly body?: unknown
+  /** Optional label echoed back on the result (handy in the playground UI). */
+  readonly label?: string
+}
+
+/** The captured outcome of one request. */
+export interface RunResult {
+  readonly label?: string
+  readonly method: string
+  readonly path: string
+  /** `true` when the app returned a 2xx response. `false` for non-2xx, or when `app.fetch` threw. */
+  readonly ok: boolean
+  /** HTTP status — present when the app returned a response (absent when it threw). */
+  readonly status?: number
+  readonly statusText?: string
+  readonly headers?: Readonly<Record<string, string>>
+  /** Parsed JSON when the response is JSON; otherwise the (possibly truncated) text. */
+  readonly body?: unknown
+  /** The response body as text, truncated to `maxBodyChars`. */
+  readonly bodyText?: string
+  /** `true` when `bodyText` was cut to the cap. */
+  readonly truncated?: boolean
+  /** Wall-clock time for this request, milliseconds. */
+  readonly durationMs: number
+  /** Set when `app.fetch` threw (the app crashed) rather than returning a response. */
+  readonly error?: { readonly name: string; readonly message: string; readonly stack?: string }
+}
+
+export interface RunOptions {
+  /** Origin used to resolve relative paths. Default `"http://nifra.local"`. */
+  readonly origin?: string
+  /** Cap on captured body text, in characters. Default 65536. */
+  readonly maxBodyChars?: number
+}
+
+const DEFAULT_ORIGIN = "http://nifra.local"
+const DEFAULT_MAX_BODY = 64 * 1024
+
+const now = (): number =>
+  typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now()
+
+const METHODS_WITHOUT_BODY: ReadonlySet<string> = new Set(["GET", "HEAD"])
+
+/** A plain JSON-ish object/array (encode it as JSON) — vs a string/binary body we pass through. */
+function isJsonBody(body: unknown): body is Record<string, unknown> | unknown[] {
+  if (body === null || typeof body !== "object") return false
+  if (body instanceof Uint8Array || body instanceof ArrayBuffer || body instanceof Blob)
+    return false
+  if (typeof FormData !== "undefined" && body instanceof FormData) return false
+  if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) return false
+  return true
+}
+
+function buildRequest(spec: RequestSpec, origin: string): Request {
+  const method = (spec.method ?? "GET").toUpperCase()
+  const url = /^https?:\/\//i.test(spec.path) ? spec.path : new URL(spec.path, origin).toString()
+
+  const headers = new Headers(spec.headers as Record<string, string> | undefined)
+  const init: RequestInit = { method, headers }
+
+  if (spec.body !== undefined && !METHODS_WITHOUT_BODY.has(method)) {
+    if (isJsonBody(spec.body)) {
+      if (!headers.has("content-type")) headers.set("content-type", "application/json")
+      init.body = JSON.stringify(spec.body)
+    } else {
+      init.body = spec.body as RequestInit["body"]
+    }
+  }
+  return new Request(url, init)
+}
+
+function headersToObject(headers: Headers): Record<string, string> {
+  const out: Record<string, string> = {}
+  headers.forEach((value, key) => {
+    out[key] = value
+  })
+  return out
+}
+
+/** Drive a single request through the app, capturing the outcome (never throws — a thrown app error
+ * becomes `result.error`). */
+export async function runRequest(
+  app: AppLike,
+  spec: RequestSpec,
+  options: RunOptions = {},
+): Promise<RunResult> {
+  const origin = options.origin ?? DEFAULT_ORIGIN
+  const maxBody = options.maxBodyChars ?? DEFAULT_MAX_BODY
+  const method = (spec.method ?? "GET").toUpperCase()
+  const base = {
+    ...(spec.label === undefined ? {} : { label: spec.label }),
+    method,
+    path: spec.path,
+  }
+
+  const start = now()
+  let request: Request
+  try {
+    request = buildRequest(spec, origin)
+  } catch (err) {
+    // A malformed spec (bad URL, GET-with-body via a custom method, …) — report it, don't throw.
+    return { ...base, ok: false, durationMs: now() - start, error: toError(err) }
+  }
+
+  try {
+    const res = await app.fetch(request)
+    const text = await res.text()
+    const truncated = text.length > maxBody
+    const bodyText = truncated ? text.slice(0, maxBody) : text
+    const contentType = res.headers.get("content-type") ?? ""
+    let body: unknown = bodyText
+    if (contentType.includes("application/json") && text.length > 0) {
+      try {
+        body = JSON.parse(text)
+      } catch {
+        // Content-Type lied, or the body is partial — keep the text form.
+      }
+    }
+    return {
+      ...base,
+      ok: res.ok,
+      status: res.status,
+      statusText: res.statusText,
+      headers: headersToObject(res.headers),
+      body,
+      bodyText,
+      ...(truncated ? { truncated } : {}),
+      durationMs: now() - start,
+    }
+  } catch (err) {
+    return { ...base, ok: false, durationMs: now() - start, error: toError(err) }
+  }
+}
+
+function toError(err: unknown): { name: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, ...(err.stack ? { stack: err.stack } : {}) }
+  }
+  return { name: "Error", message: String(err) }
+}
+
+/**
+ * Run a batch of requests through the app, in order, and return a result per request. Never throws:
+ * an app crash on any request is captured as that result's `error` and the run continues.
+ */
+export function runApp(
+  app: AppLike,
+  requests: readonly RequestSpec[],
+  options: RunOptions = {},
+): Promise<RunResult[]> {
+  return requests.reduce<Promise<RunResult[]>>(async (acc, spec) => {
+    const results = await acc
+    results.push(await runRequest(app, spec, options))
+    return results
+  }, Promise.resolve([]))
+}