@solidxai/core 0.1.2 → 0.1.4

package/src/testing/reporter/console-reporter.ts

@@ -0,0 +1,229 @@
+// Purpose: Basic console reporter implementation.
+
+import type { Reporter } from "./reporter.types";
+import type { OpStep } from "../contracts/testing-metadata.types";
+
+const INDENT = "  ";
+const STEP_INDENT = INDENT;
+const MAX_DETAIL_LEN = 140;
+
+function formatError(err: unknown): string {
+  if (!err) return "";
+  if (err instanceof Error) {
+    return err.stack || err.message;
+  }
+  return String(err);
+}
+
+function indentLines(text: string, indent: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length ? `${indent}${line}` : indent))
+    .join("\n");
+}
+
+function truncate(value: string, maxLen: number = MAX_DETAIL_LEN): string {
+  if (value.length <= maxLen) return value;
+  return `${value.slice(0, maxLen - 1)}…`;
+}
+
+function formatHttpBody(body: unknown): string {
+  if (body === null || body === undefined) return "";
+  if (typeof body === "string") {
+    const trimmed = body.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      try {
+        return JSON.stringify(JSON.parse(trimmed), null, 2);
+      } catch {
+        return body;
+      }
+    }
+    return body;
+  }
+  try {
+    return JSON.stringify(body, null, 2);
+  } catch {
+    return String(body);
+  }
+}
+
+function withoutQuery(url: string): string {
+  const idx = url.indexOf("?");
+  return idx === -1 ? url : url.slice(0, idx);
+}
+
+function maskIfSensitive(value: string, hints: string[]): string {
+  const lower = hints.join(" ").toLowerCase();
+  if (lower.includes("password") || lower.includes("pwd")) {
+    return "••••••";
+  }
+  return value;
+}
+
+function stepDetails(step: OpStep): string | undefined {
+  const withObj = (step.with ?? {}) as Record<string, any>;
+
+  switch (step.op) {
+    case "api.request": {
+      const method = String(withObj.method ?? "").toUpperCase();
+      const url = typeof withObj.url === "string" ? withoutQuery(withObj.url) : "";
+      if (!method && !url) return undefined;
+      return `${method} ${url}`.trim();
+    }
+    case "api.auth.bearerFromLogin": {
+      const url = typeof withObj.url === "string" ? withoutQuery(withObj.url) : "";
+      return url ? `url: ${url}` : undefined;
+    }
+    case "ui.goto": {
+      return withObj.url ? `url: ${withObj.url}` : undefined;
+    }
+    case "ui.click":
+    case "ui.expectVisible": {
+      return withObj.selector ? `selector: ${withObj.selector}` : undefined;
+    }
+    case "ui.fill":
+    case "ui.select": {
+      const selector = withObj.selector ? `selector: ${withObj.selector}` : "";
+      const value =
+        withObj.value !== undefined
+          ? `value: ${maskIfSensitive(String(withObj.value), [String(withObj.selector ?? ""), String(step.op)])}`
+          : "";
+      return [selector, value].filter(Boolean).join(", ") || undefined;
+    }
+    case "ui.press": {
+      const selector = withObj.selector ? `selector: ${withObj.selector}` : "";
+      const key = withObj.key ? `key: ${withObj.key}` : "";
+      return [selector, key].filter(Boolean).join(", ") || undefined;
+    }
+    case "ui.expectUrl": {
+      const equals = withObj.equals ? `equals: ${withObj.equals}` : "";
+      const contains = withObj.contains ? `contains: ${withObj.contains}` : "";
+      return [equals, contains].filter(Boolean).join(", ") || undefined;
+    }
+    case "ui.expectText": {
+      const selector = withObj.selector ? `selector: ${withObj.selector}` : "";
+      const equals = withObj.equals ? `equals: ${truncate(String(withObj.equals))}` : "";
+      const contains = withObj.contains ? `contains: ${truncate(String(withObj.contains))}` : "";
+      return [selector, equals, contains].filter(Boolean).join(", ") || undefined;
+    }
+    case "assert.httpStatus": {
+      return withObj.is !== undefined ? `status: ${withObj.is}` : undefined;
+    }
+    case "assert.jsonPath": {
+      const path = withObj.path ? `path: ${withObj.path}` : "";
+      const equals = withObj.equals !== undefined ? `equals: ${truncate(String(withObj.equals))}` : "";
+      return [path, equals].filter(Boolean).join(", ") || undefined;
+    }
+    case "assert.contains":
+    case "assert.equals":
+    case "assert.matches": {
+      const expected =
+        withObj.expected !== undefined
+          ? `expected: ${truncate(String(withObj.expected))}`
+          : withObj.pattern
+            ? `pattern: ${truncate(String(withObj.pattern))}`
+            : withObj.equals !== undefined
+              ? `equals: ${truncate(String(withObj.equals))}`
+              : "";
+      return expected || undefined;
+    }
+    case "util.sleep": {
+      return withObj.ms !== undefined ? `ms: ${withObj.ms}` : undefined;
+    }
+    case "util.log": {
+      return withObj.message ? `message: ${truncate(String(withObj.message))}` : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function formatStepLabel(step: OpStep): string {
+  const base = step.name ? `${step.op} (${step.name})` : step.op;
+  const details = stepDetails(step);
+  if (!details) return base;
+  return `${base} (${details})`;
+}
+
+export class ConsoleReporter implements Reporter {
+  onScenarioStart(scenario: { id: string; name?: string }): void {
+    const label = scenario.name ? `${scenario.id} (${scenario.name})` : scenario.id;
+    console.log(`\n▶ Scenario: ${label}`);
+  }
+
+  onScenarioEnd(
+    scenario: { id: string; name?: string },
+    result: { ok: boolean; error?: unknown; durationMs: number },
+  ): void {
+    const label = scenario.name ? `${scenario.id} (${scenario.name})` : scenario.id;
+    const status = result.ok ? "✔" : "✖";
+    console.log(`${status} Scenario: ${label} (${result.durationMs}ms)`);
+  }
+
+  onStepStart(args: {
+    scenarioId: string;
+    phase: string;
+    step: OpStep;
+  }): void {
+    const label = formatStepLabel(args.step);
+    const phase = args.phase.toUpperCase();
+    console.log(`${STEP_INDENT}↳ ${phase} ${label}`);
+  }
+
+  onStepEnd(args: {
+    scenarioId: string;
+    phase: string;
+    step: OpStep;
+    ok: boolean;
+    error?: unknown;
+    durationMs: number;
+  }): void {
+    const label = formatStepLabel(args.step);
+    const phase = args.phase.toUpperCase();
+    const status = args.ok ? "✔" : "✖";
+    console.log(
+      `${STEP_INDENT}${status} ${phase} ${label} (${args.durationMs}ms)`
+    );
+    if (!args.ok && args.error) {
+      const details = formatError(args.error);
+      console.error(indentLines(details, `${STEP_INDENT}${INDENT}`));
+      const httpBody = (args.error as any)?.httpResponseBody;
+      if (httpBody !== undefined) {
+        const formatted = formatHttpBody(httpBody);
+        const bodyText = formatted.length ? formatted : "<empty>";
+        console.error(
+          indentLines(
+            `HTTP Response Body:\n${bodyText}`,
+            `${STEP_INDENT}${INDENT}`,
+          ),
+        );
+      }
+    }
+  }
+
+  onSpecResult(args: {
+    scenarioId: string;
+    specId: string;
+    stepName?: string;
+    result: { ok: boolean; details?: Record<string, any> };
+  }): void {
+    console.log(`${INDENT}↳ SPEC ${args.specId} ok=${args.result.ok}`);
+    if (args.result.details) {
+      const details = JSON.stringify(args.result.details, null, 2);
+      console.log(indentLines(details, `${INDENT}${INDENT}`));
+    }
+  }
+
+  attach(args: {
+    scenarioId: string;
+    name: string;
+    contentType: string;
+    data: Buffer | string;
+  }): void {
+    const header = `ATTACH ${args.name} (${args.contentType})`;
+    console.log(indentLines(header, `${STEP_INDENT}${INDENT}`));
+    const dataText = Buffer.isBuffer(args.data) ? args.data.toString("utf8") : String(args.data ?? "");
+    if (!dataText.length) return;
+    console.log(indentLines(dataText, `${STEP_INDENT}${INDENT}${INDENT}`));
+  }
+}

package/src/testing/reporter/reporter.types.ts

@@ -0,0 +1,36 @@
+import type { StepPhase } from "../contracts/runtime-context.types";
+import type { OpStep, ScenarioSpec } from "../contracts/testing-metadata.types";
+import type { SolidTestSpecResult } from "../contracts/test-spec.types";
+
+export interface Reporter {
+  onScenarioStart(scenario: ScenarioSpec): void;
+  onScenarioEnd(
+    scenario: ScenarioSpec,
+    result: { ok: boolean; error?: unknown; durationMs: number },
+  ): void;
+  onStepStart(args: {
+    scenarioId: string;
+    phase: StepPhase;
+    step: OpStep;
+  }): void;
+  onStepEnd(args: {
+    scenarioId: string;
+    phase: StepPhase;
+    step: OpStep;
+    ok: boolean;
+    error?: unknown;
+    durationMs: number;
+  }): void;
+  onSpecResult?(args: {
+    scenarioId: string;
+    specId: string;
+    stepName?: string;
+    result: SolidTestSpecResult;
+  }): void;
+  attach?(args: {
+    scenarioId: string;
+    name: string;
+    contentType: string;
+    data: Buffer | string;
+  }): void;
+}

package/src/testing/runner/lifecycle.ts

@@ -0,0 +1,31 @@
+import type { TestContext } from "../contracts/runtime-context.types";
+import type { OpStep, ScenarioSpec, StepBlock } from "../contracts/testing-metadata.types";
+
+type StartedFlag = { value: boolean };
+
+function stepsFromBlock(block: StepBlock): OpStep[] {
+  if ("given" in block) return [block.given];
+  if ("when" in block) return [block.when];
+  if ("and" in block) return [block.and];
+  if ("then" in block) return Array.isArray(block.then) ? block.then : [block.then];
+  return [block];
+}
+
+export function scenarioNeedsUi(scenario: ScenarioSpec): boolean {
+  if (scenario.type === "ui" || scenario.type === "mixed") return true;
+  for (const block of scenario.steps) {
+    for (const step of stepsFromBlock(block)) {
+      if (step.op.startsWith("ui.")) return true;
+    }
+  }
+  return false;
+}
+
+export async function ensureUiStarted(
+  ctxBase: Omit<TestContext, "scenarioId" | "scenarioType" | "params">,
+  startedFlag: StartedFlag,
+): Promise<void> {
+  if (!ctxBase.ui || startedFlag.value) return;
+  await ctxBase.ui.start();
+  startedFlag.value = true;
+}

package/src/testing/runner/run-from-metadata.ts

@@ -0,0 +1,87 @@
+import type { Reporter } from "../reporter/reporter.types";
+import type { TestingMetadata, TestingDataRecord } from "../contracts/testing-metadata.types";
+import type { ApiAdapterOptions } from "../adapters/api/api.types";
+import type { PlaywrightAdapterOptions } from "../adapters/ui/ui.types";
+import { ApiAdapter } from "../adapters/api/api-adapter";
+import { PlaywrightAdapter } from "../adapters/ui/playwright-adapter";
+import { registerApiSteps } from "../steps/api";
+import { registerUiSteps } from "../steps/ui";
+import { registerAssertSteps } from "../steps/assert";
+import { registerUtilSteps } from "../steps/util";
+import { registerTestSteps } from "../steps/test";
+import { SimpleResourceStore } from "../core/resource-store";
+import { StepRegistry } from "../core/step-registry";
+import { SpecRegistry } from "../core/spec-registry";
+import { TestingEngine } from "../core/testing-engine";
+import { filterScenarios } from "./scenario-filter";
+import { ensureUiStarted, scenarioNeedsUi } from "./lifecycle";
+import { ConsoleReporter } from "../reporter/console-reporter";
+
+
+function buildTestDataIndex(data?: TestingDataRecord[]): Record<string, Record<string, any>> {
+  const index: Record<string, Record<string, any>> = {};
+  if (!Array.isArray(data)) return index;
+  for (const record of data) {
+    if (!record?.modelUserKey || !record?.recUserKeyValue) continue;
+    if (!index[record.modelUserKey]) {
+      index[record.modelUserKey] = {};
+    }
+    index[record.modelUserKey][record.recUserKeyValue] = record.data ?? {};
+  }
+  return index;
+}
+
+export type RunnerOptions = {
+  metadata: TestingMetadata;
+  scenarioIds?: string[];
+  includeTags?: string[];
+  skipScenarioIds?: string[];
+  reporter?: Reporter;
+  api?: ApiAdapterOptions;
+  ui?: PlaywrightAdapterOptions;
+  defaults?: { timeoutMs?: number; retries?: number };
+  options?: { printApiLogs?: boolean };
+  specs?: (registry: SpecRegistry) => void;
+};
+
+export async function runFromMetadata(opts: RunnerOptions): Promise<void> {
+  const registry = new StepRegistry();
+  registerApiSteps(registry);
+  registerUiSteps(registry);
+  registerAssertSteps(registry);
+  registerUtilSteps(registry);
+  registerTestSteps(registry);
+
+  const engine = new TestingEngine(registry, opts.defaults);
+  const scenarios = filterScenarios(opts.metadata.testing.scenarios, {
+    scenarioIds: opts.scenarioIds,
+    includeTags: opts.includeTags,
+    skipScenarioIds: opts.skipScenarioIds,
+  });
+
+  const specRegistry = new SpecRegistry();
+  const testData = buildTestDataIndex(opts.metadata.testing?.data);
+  if (opts.specs) {
+    opts.specs(specRegistry);
+  }
+
+  const resources = new SimpleResourceStore();
+  const reporter = opts.reporter ?? new ConsoleReporter();
+  const api = new ApiAdapter(opts.api);
+  const ui = new PlaywrightAdapter(opts.ui);
+  const ctxBase = { resources, reporter, api, ui, specRegistry, testData, options: opts.options };
+  const uiStarted = { value: false };
+
+  try {
+    for (const scenario of scenarios) {
+      if (scenarioNeedsUi(scenario)) {
+        await ensureUiStarted(ctxBase, uiStarted);
+      }
+      await engine.runScenario(scenario, ctxBase);
+    }
+  } finally {
+    if (uiStarted.value) {
+      await ui.stop();
+    }
+  }
+}

package/src/testing/runner/scenario-filter.ts

@@ -0,0 +1,33 @@
+import type { ScenarioSpec } from "../contracts/testing-metadata.types";
+
+type ScenarioFilterOptions = {
+  scenarioIds?: string[];
+  includeTags?: string[];
+  skipScenarioIds?: string[];
+};
+
+export function filterScenarios(
+  scenarios: ScenarioSpec[],
+  opts: ScenarioFilterOptions,
+): ScenarioSpec[] {
+  let result = scenarios;
+
+  if (opts.scenarioIds && opts.scenarioIds.length > 0) {
+    const idSet = new Set(opts.scenarioIds);
+    result = result.filter((scenario) => idSet.has(scenario.id));
+  }
+
+  if (opts.includeTags && opts.includeTags.length > 0) {
+    result = result.filter((scenario) => {
+      const tags = scenario.tags ?? [];
+      return opts.includeTags!.every((tag) => tags.includes(tag));
+    });
+  }
+
+  if (opts.skipScenarioIds && opts.skipScenarioIds.length > 0) {
+    const skipSet = new Set(opts.skipScenarioIds);
+    result = result.filter((scenario) => !skipSet.has(scenario.id));
+  }
+
+  return result;
+}

package/src/testing/steps/api/auth.step.ts

@@ -0,0 +1,66 @@
+// Purpose: API auth step registrations.
+
+import type { TestContext } from "../../contracts/runtime-context.types";
+import type { OpStep } from "../../contracts/testing-metadata.types";
+import { StepRegistry } from "../../core/step-registry";
+
+type BearerFromLoginInput = {
+  url: string;
+  username: string;
+  password: string;
+};
+
+export function registerAuthSteps(registry: StepRegistry): void {
+  registry.register(
+    "api.auth.bearerFromLogin",
+    async (ctx: TestContext, step: OpStep) => {
+      if (!ctx.api) {
+        throw new Error(
+          'Missing API adapter on context for op "api.auth.bearerFromLogin"',
+        );
+      }
+
+      const input = (step.with ?? {}) as BearerFromLoginInput;
+      if (!input.url) {
+        throw new Error(
+          'Missing "url" in step.with for op "api.auth.bearerFromLogin"',
+        );
+      }
+      if (!input.username) {
+        throw new Error(
+          'Missing "username" in step.with for op "api.auth.bearerFromLogin"',
+        );
+      }
+      if (!input.password) {
+        throw new Error(
+          'Missing "password" in step.with for op "api.auth.bearerFromLogin"',
+        );
+      }
+
+      const response = await ctx.api.http({
+        method: "POST",
+        url: input.url,
+        json: {
+          username: input.username,
+          password: input.password,
+        },
+      });
+
+      if (response.status < 200 || response.status >= 300) {
+        throw new Error(
+          `Login failed with status ${response.status}: ${response.bodyText}`,
+        );
+      }
+
+      const bodyJson = response.bodyJson as
+        | { data?: { accessToken?: unknown }; accessToken?: unknown }
+        | undefined;
+      const token = bodyJson?.data?.accessToken ?? bodyJson?.accessToken;
+      if (typeof token !== "string" || token.length === 0) {
+        throw new Error("Missing access token in login response");
+      }
+
+      return token;
+    },
+  );
+}

package/src/testing/steps/api/index.ts

@@ -0,0 +1,10 @@
+// Purpose: API step registrations.
+
+import { StepRegistry } from "../../core/step-registry";
+import { registerAuthSteps } from "./auth.step";
+import { registerApiRequestStep } from "./request.step";
+
+export function registerApiSteps(registry: StepRegistry): void {
+  registerApiRequestStep(registry);
+  registerAuthSteps(registry);
+}