@schwabyio/gta 0.13.0 → 0.14.1

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { OpenProjectFunction } from './types.js';
+export declare const openProject: OpenProjectFunction;
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { createRequire as __gtaCreateRequire } from 'node:module';
+const require = __gtaCreateRequire(import.meta.url);
+import {
+  openProject
+} from "./chunks/chunk-4JUUUUWB.js";
+import "./chunks/chunk-4W4TFJ53.js";
+import "./chunks/chunk-S563G22M.js";
+
+// src/library/index.ts
+var openProject2 = openProject;
+export {
+  openProject2 as openProject
+};

package/dist/playwright.d.ts

@@ -0,0 +1,37 @@
+import { expect } from '@playwright/test';
+import type { PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
+import type { GravityProject, OpenOptions, RunOptions, RunOutcome, UseOptions, VarValue } from './types.js';
+export interface GravityOptions extends OpenOptions {
+    /** The project folder, relative to the Playwright config's folder. Absent: that folder. */
+    project?: string;
+}
+/** The `gravity` option, for `defineConfig<{}, GravityConfig>`. */
+export interface GravityConfig {
+    gravity: GravityOptions;
+}
+export interface GtaRunOptions extends Omit<RunOptions, 'signal'> {
+    /** On a failure, go on with the test and fail it at the end, as `expect.soft` does. */
+    soft?: boolean;
+}
+export interface GtaUseOptions extends Omit<UseOptions, 'signal'> {
+    /** On a failure, go on with the test and fail it at the end, as `expect.soft` does. */
+    soft?: boolean;
+}
+/** The `gta` fixture. */
+export interface Gta {
+    /** The project, opened once for each worker. */
+    readonly project: GravityProject;
+    /** `project.run`, reported as a step, failing the test when the run fails. */
+    run(collection: string, options?: GtaRunOptions): Promise<RunOutcome>;
+    /** `project.use`, reported as a step, failing the test when the run fails. */
+    use(name: string, params?: Record<string, VarValue>, options?: GtaUseOptions): Promise<RunOutcome>;
+}
+export interface GravityFixtures {
+    gta: Gta;
+}
+export interface GravityWorkerFixtures extends GravityConfig {
+    gravityProject: GravityProject;
+}
+export type * from './types.js';
+export { expect };
+export declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & GravityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & GravityWorkerFixtures>;

package/dist/playwright.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { createRequire as __gtaCreateRequire } from 'node:module';
+const require = __gtaCreateRequire(import.meta.url);
+import {
+  openProject
+} from "./chunks/chunk-4JUUUUWB.js";
+import "./chunks/chunk-4W4TFJ53.js";
+import {
+  iterationName,
+  resultName
+} from "./chunks/chunk-S563G22M.js";
+
+// src/library/playwright.ts
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test as base } from "@playwright/test";
+var test = base.extend({
+  gravity: [{}, { scope: "worker", option: true }],
+  // Once for each worker: settings read, and an environment's flag command run, once.
+  gravityProject: [
+    async ({ gravity }, use, workerInfo) => {
+      const { project = ".", ...options } = gravity;
+      const { configFile, rootDir } = workerInfo.config;
+      const from = configFile ? path.dirname(configFile) : rootDir;
+      await use(await openProject(path.resolve(from, project), options));
+    },
+    { scope: "worker", title: "open the Gravity project" }
+  ],
+  gta: async ({ gravityProject }, use) => {
+    const runs = { ending: new AbortController(), running: /* @__PURE__ */ new Set() };
+    await use(gtaFor(gravityProject, runs));
+    runs.ending.abort();
+    await Promise.allSettled(runs.running);
+  }
+});
+var checks = expect.extend({
+  toHavePassed(outcome, title, caller) {
+    const message = messageOf(title, outcome);
+    if (outcome.passed) return { pass: true, name: "toHavePassed", message: () => message };
+    const error = new Error(message);
+    if (caller) {
+      error.stack = `Error: ${message}
+    at ${caller.file}:${caller.line}:${caller.column}`;
+    }
+    throw error;
+  }
+});
+function messageOf(title, outcome) {
+  const { summary, error } = outcome;
+  const failed = summary.failed + summary.errored;
+  const headline = error ? `${title}: ${error}` : `${title}: ${failed} of ${summary.total} ${summary.total === 1 ? "step" : "steps"} failed`;
+  const details = outcome.failures.split("\n").slice(1).filter((line) => !error || line.trim() !== `\u2717 ${error}`);
+  return details.length > 0 ? `${headline}
+
+${details.join("\n")}` : headline;
+}
+function gtaFor(project, runs) {
+  return {
+    project,
+    run: (collection, { soft, onResult, ...options } = {}) => reported(
+      `gta ${collection}`,
+      { soft, onResult },
+      runs,
+      (hooks) => project.run(collection, { ...options, ...hooks })
+    ),
+    use: (set, params, { soft, onResult, ...options } = {}) => reported(
+      `gta use ${set}`,
+      { soft, onResult },
+      runs,
+      (hooks) => project.use(set, params, { ...options, ...hooks })
+    )
+  };
+}
+async function reported(title, options, runs, start) {
+  const location = callerLocation();
+  return base.step(
+    title,
+    async () => {
+      let reporting = Promise.resolve();
+      const run = start({
+        signal: runs.ending.signal,
+        onResult: (result, step) => {
+          options.onResult?.(result, step);
+          reporting = reporting.then(() => reportResult(result, step));
+        }
+      });
+      runs.running.add(run);
+      const outcome = await run.finally(() => runs.running.delete(run));
+      await reporting;
+      if (!outcome.passed && !runs.ending.signal.aborted) {
+        if (options.soft) checks.soft(outcome).toHavePassed(title, location);
+        else checks(outcome).toHavePassed(title, location);
+      }
+      return outcome;
+    },
+    location ? { location } : {}
+  );
+}
+async function reportResult(result, step) {
+  await base.step(
+    titleOf(result, step),
+    async (info) => {
+      if (result.status !== "skipped" && result.request.url !== "") {
+        await info.attach("request and response", { body: exchangeOf(result) });
+      }
+      if (result.status === "skipped") info.skip(true, result.skipped?.reason);
+      if (result.status === "fail" || result.status === "error") {
+        throw new Error(problemsOf(result));
+      }
+    },
+    { location: { file: step.file, line: step.line ?? 1, column: 1 } }
+  ).catch(() => {
+  });
+}
+function titleOf(result, step) {
+  const parts = [iterationName(resultName(result), step)];
+  if (result.response) parts.push(String(result.response.status));
+  else if (result.status === "skipped") parts.push("skipped");
+  if (result.status !== "skipped") parts.push(`${Math.round(result.durationMs)} ms`);
+  return parts.join(" \xB7 ");
+}
+function problemsOf(result) {
+  const lines = [];
+  if (result.error) lines.push(`${result.error.phase} error: ${result.error.message}`);
+  for (const check of result.assertions) {
+    if (check.status !== "fail") continue;
+    lines.push(`${check.name}${check.message ? `: ${check.message}` : ""}`);
+    if (check.expected !== void 0) lines.push(`  expected ${check.expected}`);
+    if (check.actual !== void 0) lines.push(`  actual   ${check.actual}`);
+  }
+  return lines.join("\n") || "failed";
+}
+var BODY_LIMIT = 256 * 1024;
+var clip = (body) => body.length > BODY_LIMIT ? `${body.slice(0, BODY_LIMIT)}
+\u2026 (${body.length - BODY_LIMIT} more characters)` : body;
+function exchangeOf(result) {
+  const { request, response } = result;
+  const lines = [`${request.method} ${request.url}`];
+  for (const header of request.headers) lines.push(`${header.name}: ${header.value}`);
+  if (request.body) lines.push("", clip(request.body));
+  lines.push("");
+  if (response) {
+    lines.push(
+      `${response.status} ${response.statusText} \xB7 ${Math.round(response.timings.totalMs)} ms \xB7 ${response.sizeBytes} bytes`
+    );
+    for (const header of response.headers) lines.push(`${header.name}: ${header.value}`);
+    if (response.bodyEncoding === "base64")
+      lines.push("", `[binary body, ${response.sizeBytes} bytes]`);
+    else if (response.body) lines.push("", clip(response.body));
+  } else {
+    lines.push(result.error ? `No response: ${result.error.message}` : "No response");
+  }
+  if (result.assertions.length > 0) {
+    lines.push("", "Checks:");
+    for (const check of result.assertions) {
+      lines.push(`${check.status === "pass" ? "\u2713" : "\u2715"} ${check.name}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+var ours = path.dirname(fileURLToPath(import.meta.url));
+function callerLocation() {
+  for (const frame of (new Error().stack ?? "").split("\n").slice(1)) {
+    const match = /^\s*at (?:.*? \()?(.+?):(\d+):(\d+)\)?\s*$/.exec(frame);
+    if (!match) continue;
+    const file = match[1].startsWith("file://") ? fileURLToPath(match[1]) : match[1];
+    if (file.startsWith("node:") || !path.isAbsolute(file)) continue;
+    if (file.startsWith(ours + path.sep) || path.dirname(file) === ours) continue;
+    if (file.includes(`${path.sep}node_modules${path.sep}`)) continue;
+    return { file, line: Number(match[2]), column: Number(match[3]) };
+  }
+  return void 0;
+}
+export {
+  expect,
+  test
+};

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+/**
+ * The types of gta's library, `@schwabyio/gta`: a project's collections and
+ * reusable requests run from code, such as a Playwright test.
+ *
+ * Written out here rather than taken from the core, so the published `.d.ts`
+ * files stand alone: the core's are zod's inferences, and neither ships.
+ * `project.ts` fails to compile when the two drift apart.
+ */
+/** A variable's value: plain data only (SPEC.md §4). */
+export type VarValue = string | number | boolean | null;
+/** A feature flag's value (SPEC.md §2.9). */
+export type FlagValue = string | number | boolean;
+export interface HeaderEntry {
+    name: string;
+    value: string;
+}
+export interface SentRequest {
+    method: string;
+    /** After variables are resolved. */
+    url: string;
+    headers: HeaderEntry[];
+    body: string | null;
+}
+/** How an event stream was read (SPEC.md §2.3). */
+export interface EventStreamRead {
+    endedBy: 'close' | 'maxEvents' | 'streamTimeout' | 'untilEvent' | 'limit' | 'stopped' | 'held';
+    /** Milliseconds from the response headers to each event, in order. */
+    at: number[];
+    /** For a step that opens or reads a connection (SPEC.md §2.11). */
+    connection?: {
+        name: string;
+        open: boolean;
+    };
+}
+export interface ReceivedResponse {
+    status: number;
+    statusText: string;
+    /** Where the response came from, after any redirects. */
+    url: string;
+    headers: HeaderEntry[];
+    body: string;
+    bodyKind: 'json' | 'xml' | 'html' | 'text' | 'binary' | 'empty' | 'events';
+    /** `base64` when `body` is the bytes in base64: a binary body that is not text, an image's. */
+    bodyEncoding?: 'base64';
+    sizeBytes: number;
+    redirectCount: number;
+    timings: {
+        /** Epoch milliseconds. */
+        startedAt: number;
+        ttfbMs: number;
+        totalMs: number;
+    };
+    stream?: EventStreamRead;
+}
+/** Whose script something came from. */
+export type ScriptOwner = 'endpoint-file' | 'endpoint' | 'base' | 'collection' | 'set' | 'step' | 'use';
+/** Where a script made a check: whose script, and its line there, from 1. */
+export interface ScriptSource {
+    script: ScriptOwner;
+    line: number;
+    /** For a check a check file made: that file, and its line. */
+    check?: {
+        file: string;
+        line: number;
+    };
+}
+/** One check a step's tests made. */
+export interface AssertionResult {
+    name: string;
+    status: 'pass' | 'fail';
+    message?: string;
+    target?: 'status' | 'header' | 'body' | 'strict' | 'custom';
+    /** The header name, or the body path as written. */
+    path?: string;
+    expected?: string;
+    actual?: string;
+    /** Strict validation only: body paths nothing checked. */
+    unasserted?: string[];
+    /** A body check only: the paths it vouched for. */
+    covered?: string[];
+    source?: ScriptSource;
+}
+export interface RunError {
+    phase: 'use' | 'flags' | 'forEach' | 'interpolate' | 'body' | 'pre-request' | 'http' | 'connection' | 'tests';
+    message: string;
+    code?: string;
+    stack?: string;
+    /** For a script error: its line in that script, from 1. */
+    line?: number;
+    script?: ScriptOwner;
+}
+/** One request a run sent, and what came of it: the same result gta's JSON report holds. */
+export interface RunResult {
+    item: {
+        path: string | null;
+        name: string;
+        seq: number | null;
+    };
+    request: SentRequest;
+    response: ReceivedResponse | null;
+    assertions: AssertionResult[];
+    /** Body paths the tests ignored (`gta.ignoreResponseBodyProperty`). */
+    ignored?: Array<{
+        path: string;
+        source?: ScriptSource;
+    }>;
+    /** `gta.sortResponseBodyArrays` as applied. */
+    sortedBy?: string[];
+    /** What the step's scripts wrote with `console`. */
+    logs?: Array<{
+        level: 'log' | 'info' | 'warn' | 'error';
+        message: string;
+        phase: 'pre-request' | 'tests';
+    }>;
+    error: RunError | null;
+    status: 'pass' | 'fail' | 'error' | 'skipped';
+    /** Why a skipped step did not run. */
+    skipped?: {
+        reason: string;
+    };
+    durationMs: number;
+    /**
+     * For a request a use step ran: the reusable requests as `use` named them,
+     * the use step's name, and which of their steps, from 0.
+     */
+    use?: {
+        set: string;
+        name?: string;
+        child: number;
+        of: number;
+    };
+    /** For a setup or teardown step. */
+    stage?: 'setup' | 'teardown';
+    /** For a step with `forEach`: which item, from 0. */
+    forEach?: {
+        index: number;
+        of: number;
+        item: string;
+    };
+}
+/** A run's totals, and every result. */
+export interface CollectionRunSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    errored: number;
+    /** Skipped by a flag or a script, and never attempted after a bail or a cancel. */
+    skipped: number;
+    durationMs: number;
+    results: RunResult[];
+}
+/** Where a result's step is written, for a person to go and look. */
+export interface StepRef {
+    /** The file, absolute: the collection's, or for `use`, the reusable requests file's. */
+    file: string;
+    /** The step's line in it, from 1; null when it cannot be told. */
+    line: number | null;
+    /** The step's place in its list, from 0. */
+    index: number;
+    /** For a setup or teardown step, which list it is in. */
+    stage?: 'setup' | 'teardown';
+    /** For a collection with a data file: the row it ran with, from 1. */
+    iteration?: {
+        index: number;
+        of: number;
+        label: string | null;
+    };
+}
+export interface OpenOptions {
+    /** The environment to run against, by name. Absent: `environmentType` from settings.yml. */
+    environment?: string;
+    /** Feature flag values, over the environment's and `GTA_FLAG_*` (SPEC.md §2.9). */
+    flags?: Record<string, FlagValue>;
+    /** Stop a run at its first failing step. Absent: `bail` from settings.yml. */
+    bail?: boolean;
+    /** Milliseconds a run may take before it is stopped. Absent: `timeoutCollection` from settings.yml. */
+    timeoutCollection?: number;
+}
+export interface RunOptions {
+    /**
+     * The steps to run: a step's name, as reports show it, or its place in
+     * `steps:` from 1. They run in the file's order. Absent: every step. Setup
+     * and teardown run either way.
+     */
+    steps?: ReadonlyArray<string | number>;
+    /** Values to start with, over the environment and under a data row. */
+    vars?: Record<string, VarValue>;
+    /** Stop at the first failing step. Absent: the project's `bail`. */
+    bail?: boolean;
+    signal?: AbortSignal;
+    /** As each request finishes, with the step it came from. */
+    onResult?: (result: RunResult, step: StepRef) => void;
+}
+export type UseOptions = Omit<RunOptions, 'steps'>;
+export interface RunOutcome {
+    /** Nothing failed or errored, and the run finished. */
+    passed: boolean;
+    /** The collection's id, or the reusable requests as `use` named them. */
+    id: string;
+    /** Its file, absolute. */
+    file: string;
+    /** Why it did not run, or did not finish: a file that will not load, a timeout, a cancel. */
+    error: string | null;
+    /** Every request's result, in order, secrets hidden. */
+    summary: CollectionRunSummary;
+    /** Where each result's step is: one per result, in the same order. */
+    steps: StepRef[];
+    /**
+     * Every value the run set or captured, by name: `gta.set`, and checks that
+     * save what they read. The last one set wins. Not redacted.
+     */
+    values: Record<string, VarValue>;
+    /** What went wrong, as gta prints it under Failures; empty when it passed. */
+    failures: string;
+}
+/** A project, open: its settings read, its feature flags resolved. */
+export interface GravityProject {
+    /** The project folder, absolute. */
+    readonly root: string;
+    /** `name` from project.yml, or the folder's name. */
+    readonly name: string;
+    /** The environment runs use; null for none. */
+    readonly environment: string | null;
+    /** The environments it has. */
+    readonly environments: string[];
+    readonly flags: Record<string, FlagValue>;
+    /** Its collections, by id. */
+    readonly collections: string[];
+    /** Problems with the project's layout that stop nothing, such as a folder too deep. */
+    readonly warnings: string[];
+    /**
+     * Run a collection, named by its id or its place in `collections/`
+     * (`checkout/sessions`): setup, its steps once for each data row, then
+     * teardown, as gta runs it. Resolves however the steps fare; rejects only
+     * for a name nothing answers to.
+     */
+    run(collection: string, options?: RunOptions): Promise<RunOutcome>;
+    /**
+     * Run reusable requests as a use step would (SPEC.md §2.5): `login` is
+     * `requests/login.yml`, in the project or its global project. A param left
+     * out takes its default.
+     */
+    use(name: string, params?: Record<string, VarValue>, options?: UseOptions): Promise<RunOutcome>;
+}
+/** Open the project in `folder`, the one holding `collections/`. */
+export type OpenProjectFunction = (folder: string, options?: OpenOptions) => Promise<GravityProject>;

package/dist/worker.js

@@ -3,7 +3,7 @@ import { createRequire as __gtaCreateRequire } from 'node:module';
 const require = __gtaCreateRequire(import.meta.url);
 import {
   runJob
-} from "./chunks/chunk-ABBBM5UZ.js";
+} from "./chunks/chunk-S563G22M.js";
 
 // src/worker.ts
 import { parentPort, workerData } from "node:worker_threads";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schwabyio/gta",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "type": "module",
   "description": "gta, the Gravity Test Automation command-line runner: HTTP API tests written as YAML files, run from a terminal or CI.",
   "keywords": [
@@ -13,7 +13,8 @@
     "cli",
     "yaml",
     "junit",
-    "ci"
+    "ci",
+    "playwright"
   ],
   "license": "MIT",
   "homepage": "https://github.com/schwabyio/gravity#readme",
@@ -28,6 +29,18 @@
   "bin": {
     "gta": "dist/gta.js"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright.d.ts",
+      "default": "./dist/playwright.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
@@ -37,14 +50,24 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "@playwright/test": ">=1.51.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "node build.mjs",
     "prepack": "node build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@schwabyio/gravity-core": "*",
     "esbuild": "0.28.2",
+    "typescript": "5.9.3",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   }