@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/e2e/browser-proof-session.ts

@@ -0,0 +1,392 @@
+import {
+  expect,
+  type ElementHandle,
+  type Locator,
+  type Page,
+} from "@playwright/test";
+
+import { getToolcraftControlFieldByTarget } from "./browser-control-target-helpers";
+
+const TOOLCRAFT_APP_ROOT_SELECTOR = '[data-slot="toolcraft-runtime-app"]';
+const TOOLCRAFT_APP_TITLE_SELECTOR = 'meta[name="toolcraft-app-title"]';
+const TOOLCRAFT_SERVER_IDENTITY_PATH = "/.toolcraft/server-identity.json";
+
+declare const toolcraftBrowserActionBrand: unique symbol;
+declare const toolcraftBrowserObservationBrand: unique symbol;
+declare const toolcraftBrowserSessionBrand: unique symbol;
+
+export type ToolcraftBrowserAction<
+  Kind extends string = "interaction",
+  Result = void,
+> = {
+  readonly [toolcraftBrowserActionBrand]: true;
+  readonly kind?: Kind;
+  readonly result?: Result;
+};
+
+export type ToolcraftBrowserObservation<T> = {
+  readonly [toolcraftBrowserObservationBrand]: T;
+};
+
+export type ToolcraftBrowserProofSession = {
+  action<Result = void>(
+    run: (page: Page) => Promise<Result>,
+  ): ToolcraftBrowserAction<"interaction", Result>;
+  controlAction<Result = void>(
+    target: string,
+    run: (control: Locator, page: Page) => Promise<Result>,
+  ): ToolcraftBrowserAction<"interaction", Result>;
+  observe<T>(
+    read: (root: HTMLElement) => T | Promise<T>,
+  ): ToolcraftBrowserObservation<T>;
+  reload(): ToolcraftBrowserAction<"reload">;
+  readonly [toolcraftBrowserSessionBrand]: true;
+};
+
+type SessionRecord = {
+  appTitle: string;
+  origin: string;
+  page: Page;
+  rootElement: ElementHandle<HTMLElement>;
+  serverRoot: string;
+  token: object;
+};
+
+type ActionRecord = {
+  kind: "interaction" | "reload";
+  run: (page: Page) => Promise<unknown>;
+  session: SessionRecord;
+  target?: string;
+};
+
+type ObservationRecord<T> = {
+  read: (root: HTMLElement) => T | Promise<T>;
+  session: SessionRecord;
+};
+
+const actionRecords = new WeakMap<object, ActionRecord>();
+const observationRecords = new WeakMap<object, ObservationRecord<unknown>>();
+const sessionRecords = new WeakMap<object, SessionRecord>();
+
+type ToolcraftServerIdentity = {
+  appTitle: string;
+  root: string;
+};
+
+function getHttpOrigin(page: Page): string {
+  let url: URL;
+
+  try {
+    url = new URL(page.url());
+  } catch {
+    throw new Error(
+      "A Toolcraft browser proof session requires a server-backed http(s) page.",
+    );
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(
+      "A Toolcraft browser proof session requires a server-backed http(s) page; synthetic, data, file, and about documents are not proof.",
+    );
+  }
+
+  return url.origin;
+}
+
+async function readToolcraftServerIdentity(
+  page: Page,
+  origin: string,
+): Promise<ToolcraftServerIdentity> {
+  const response = await page.request.get(
+    new URL(TOOLCRAFT_SERVER_IDENTITY_PATH, origin).href,
+    { headers: { "cache-control": "no-cache" } },
+  );
+
+  expect(
+    response.ok(),
+    "The Toolcraft browser proof origin must expose the current server identity endpoint.",
+  ).toBe(true);
+  const identity = (await response.json()) as Partial<ToolcraftServerIdentity>;
+  expect(
+    identity.appTitle?.trim(),
+    "The Toolcraft server identity must include a non-empty appTitle.",
+  ).toBeTruthy();
+  expect(
+    identity.root?.trim(),
+    "The Toolcraft server identity must include the current app root.",
+  ).toBeTruthy();
+
+  return {
+    appTitle: identity.appTitle!.trim(),
+    root: identity.root!.trim(),
+  };
+}
+
+async function assertLiveToolcraftSession(record: SessionRecord): Promise<void> {
+  expect(record.page.isClosed(), "The Toolcraft browser proof page must remain open.").toBe(
+    false,
+  );
+  expect(
+    getHttpOrigin(record.page),
+    "The Toolcraft browser proof page must remain on its verified server origin.",
+  ).toBe(record.origin);
+  const serverIdentity = await readToolcraftServerIdentity(
+    record.page,
+    record.origin,
+  );
+  expect(
+    serverIdentity,
+    "The Toolcraft browser proof page must remain attached to the same app server root.",
+  ).toEqual({ appTitle: record.appTitle, root: record.serverRoot });
+  const appTitle = await record.page
+    .locator(TOOLCRAFT_APP_TITLE_SELECTOR)
+    .getAttribute("content");
+  expect(
+    appTitle?.trim(),
+    "The Toolcraft browser proof page must preserve its toolcraft-app-title identity.",
+  ).toBe(record.appTitle);
+  expect(
+    await record.rootElement.evaluate(
+      (root, selector) => root.isConnected && root === document.querySelector(selector),
+      TOOLCRAFT_APP_ROOT_SELECTOR,
+    ),
+    "The Toolcraft browser proof session must remain attached to the original live runtime root.",
+  ).toBe(true);
+  await expect(
+    record.page.locator(TOOLCRAFT_APP_ROOT_SELECTOR),
+    "The Toolcraft browser proof session requires one visible current Toolcraft runtime app root.",
+  ).toHaveCount(1);
+  await expect(record.page.locator(TOOLCRAFT_APP_ROOT_SELECTOR)).toBeVisible();
+}
+
+async function getVisibleToolcraftRoot(
+  page: Page,
+): Promise<ElementHandle<HTMLElement>> {
+  const root = page.locator(TOOLCRAFT_APP_ROOT_SELECTOR);
+  await expect(
+    root,
+    "The Toolcraft browser proof session requires one visible current Toolcraft runtime app root.",
+  ).toHaveCount(1);
+  await expect(root).toBeVisible();
+  const element = await root.elementHandle();
+  expect(element).not.toBeNull();
+  return element as ElementHandle<HTMLElement>;
+}
+
+function requireAction(value: unknown): ActionRecord {
+  const record =
+    typeof value === "object" && value !== null
+      ? actionRecords.get(value)
+      : undefined;
+  if (!record) {
+    throw new Error(
+      "Semantic evidence actions must come from a Toolcraft browser proof session; raw callbacks are not browser proof.",
+    );
+  }
+  return record;
+}
+
+function requireObservation<T>(value: unknown): ObservationRecord<T> {
+  const record =
+    typeof value === "object" && value !== null
+      ? observationRecords.get(value)
+      : undefined;
+  if (!record) {
+    throw new Error(
+      "Semantic evidence observations must come from a Toolcraft browser proof session; raw callbacks are not browser proof.",
+    );
+  }
+  return record as ObservationRecord<T>;
+}
+
+function requireSession(value: unknown): SessionRecord {
+  const record =
+    typeof value === "object" && value !== null
+      ? sessionRecords.get(value)
+      : undefined;
+  if (!record) {
+    throw new Error(
+      "Browser evidence requires a verified Toolcraft browser proof session.",
+    );
+  }
+  return record;
+}
+
+export async function createToolcraftBrowserProofSession(
+  page: Page,
+): Promise<ToolcraftBrowserProofSession> {
+  const origin = getHttpOrigin(page);
+  const response = await page.reload({ waitUntil: "domcontentloaded" });
+  expect(
+    response?.ok(),
+    "A Toolcraft browser proof session must begin from a fresh successful server navigation.",
+  ).toBe(true);
+  const serverIdentity = await readToolcraftServerIdentity(page, origin);
+  const appTitle = await page.evaluate(
+    (selector) => document.querySelector(selector)?.getAttribute("content") ?? null,
+    TOOLCRAFT_APP_TITLE_SELECTOR,
+  );
+  expect(
+    appTitle?.trim(),
+    "A Toolcraft browser proof session requires a non-empty toolcraft-app-title meta marker.",
+  ).toBeTruthy();
+  expect(
+    appTitle!.trim(),
+    "The document identity must match the Toolcraft app served by the current origin.",
+  ).toBe(serverIdentity.appTitle);
+  const rootElement = await getVisibleToolcraftRoot(page);
+  const record: SessionRecord = {
+    appTitle: appTitle!.trim(),
+    origin,
+    page,
+    rootElement,
+    serverRoot: serverIdentity.root,
+    token: Object.freeze({}),
+  };
+  await assertLiveToolcraftSession(record);
+
+  const session = Object.freeze({
+    action<Result = void>(
+      run: (currentPage: Page) => Promise<Result>,
+    ): ToolcraftBrowserAction<"interaction", Result> {
+      const action = Object.freeze({}) as ToolcraftBrowserAction<
+        "interaction",
+        Result
+      >;
+      actionRecords.set(action, { kind: "interaction", run, session: record });
+      return action;
+    },
+    controlAction<Result = void>(
+      target: string,
+      run: (control: Locator, currentPage: Page) => Promise<Result>,
+    ): ToolcraftBrowserAction<"interaction", Result> {
+      const normalizedTarget = target.trim();
+      const action = Object.freeze({}) as ToolcraftBrowserAction<
+        "interaction",
+        Result
+      >;
+      actionRecords.set(action, {
+        kind: "interaction",
+        run: async (currentPage) => {
+          const control = await getToolcraftControlFieldByTarget(
+            currentPage,
+            normalizedTarget,
+          );
+          return run(control, currentPage);
+        },
+        session: record,
+        target: normalizedTarget,
+      });
+      return action;
+    },
+    observe<T>(
+      read: (root: HTMLElement) => T | Promise<T>,
+    ): ToolcraftBrowserObservation<T> {
+      const observation = Object.freeze({}) as ToolcraftBrowserObservation<T>;
+      observationRecords.set(observation, { read, session: record });
+      return observation;
+    },
+    reload(): ToolcraftBrowserAction<"reload"> {
+      const action = Object.freeze({}) as ToolcraftBrowserAction<"reload">;
+      actionRecords.set(action, {
+        kind: "reload",
+        run: (currentPage) => currentPage.reload().then(() => undefined),
+        session: record,
+      });
+      return action;
+    },
+  }) as ToolcraftBrowserProofSession;
+  sessionRecords.set(session, record);
+  return session;
+}
+
+export function assertToolcraftBrowserProofSession(
+  observation: unknown,
+  ...actions: readonly unknown[]
+): void {
+  const observationRecord = requireObservation(observation);
+  for (const action of actions) {
+    const actionRecord = requireAction(action);
+    if (actionRecord.session.token !== observationRecord.session.token) {
+      throw new Error(
+        "Semantic evidence observations and actions must belong to the same browser proof session.",
+      );
+    }
+  }
+}
+
+export function assertToolcraftBrowserActionForSession(
+  session: ToolcraftBrowserProofSession,
+  action: ToolcraftBrowserAction,
+): void {
+  const sessionRecord = requireSession(session);
+  const actionRecord = requireAction(action);
+  if (sessionRecord.token !== actionRecord.session.token) {
+    throw new Error(
+      "Browser evidence actions must belong to the same browser proof session.",
+    );
+  }
+}
+
+export function getToolcraftBrowserActionTarget(
+  action: ToolcraftBrowserAction,
+): string | undefined {
+  return requireAction(action).target;
+}
+
+export async function readToolcraftBrowserObservation<T>(
+  observation: ToolcraftBrowserObservation<T>,
+): Promise<T> {
+  const record = requireObservation<T>(observation);
+  await assertLiveToolcraftSession(record.session);
+  return record.session.rootElement.evaluate(record.read);
+}
+
+export async function runToolcraftBrowserAction(
+  action: ToolcraftBrowserAction,
+  expectedKind: "interaction" | "reload" = "interaction",
+): Promise<void> {
+  const record = requireAction(action);
+  if (record.kind !== expectedKind) {
+    throw new Error(
+      `Semantic evidence requires a ${expectedKind} browser proof action, received ${record.kind}.`,
+    );
+  }
+  await assertLiveToolcraftSession(record.session);
+  await record.run(record.session.page);
+  if (record.kind === "reload") {
+    record.session.rootElement = await getVisibleToolcraftRoot(record.session.page);
+  }
+  await assertLiveToolcraftSession(record.session);
+}
+
+export async function runToolcraftBrowserValueAction<Result>(
+  action: ToolcraftBrowserAction<"interaction", Result>,
+): Promise<Result> {
+  const record = requireAction(action);
+  if (record.kind !== "interaction") {
+    throw new Error(
+      `Semantic evidence requires a interaction browser proof action, received ${record.kind}.`,
+    );
+  }
+  await assertLiveToolcraftSession(record.session);
+  const result = await record.run(record.session.page);
+  await assertLiveToolcraftSession(record.session);
+  return result as Result;
+}
+
+export function isToolcraftBrowserProofSession(value: unknown): boolean {
+  return typeof value === "object" && value !== null && sessionRecords.has(value);
+}
+
+export function isToolcraftBrowserAction(value: unknown): value is ToolcraftBrowserAction {
+  return typeof value === "object" && value !== null && actionRecords.has(value);
+}
+
+export async function getToolcraftBrowserProofPage(
+  session: ToolcraftBrowserProofSession,
+): Promise<Page> {
+  const record = requireSession(session);
+  await assertLiveToolcraftSession(record);
+  return record.page;
+}

package/templates/starter/e2e/browser-runtime-evidence-reporter.ts

@@ -0,0 +1,136 @@
+import type {
+  FullConfig,
+  FullResult,
+  Reporter,
+  Suite,
+  TestCase,
+} from "@playwright/test/reporter";
+import {
+  TOOLCRAFT_BROWSER_ACCEPTANCE_MARKER_FILE_NAME,
+  TOOLCRAFT_BROWSER_ACCEPTANCE_MARKER_TEST_NAME,
+  TOOLCRAFT_BROWSER_PERFORMANCE_MARKER_TEST_NAME,
+  evaluateToolcraftBrowserRuntimeEvidence,
+  type ToolcraftBrowserRuntimeRequirement,
+  type ToolcraftBrowserRuntimeTest,
+} from "../src/app/test-evidence/browser-runtime-contract";
+import { starterAcceptance } from "../src/app/starter-acceptance";
+import { starterPerformance } from "../src/app/starter-performance";
+import { starterSchema } from "../src/app/starter-schema";
+import {
+  deriveToolcraftBrowserRuntimeRequirements,
+  deriveToolcraftPerformanceRuntimeRequirements,
+} from "./browser-runtime-evidence-requirements";
+
+type ToolcraftBrowserRuntimeEvidenceReporterOptions = {
+  acceptanceRequirements?: readonly ToolcraftBrowserRuntimeRequirement[];
+  performanceRequirements?: readonly ToolcraftBrowserRuntimeRequirement[];
+  reportError?: (error: string) => void;
+};
+
+function isProtectedAcceptanceMarker(test: TestCase): boolean {
+  const normalizedFile = test.location.file.replaceAll("\\", "/");
+
+  return (
+    test.title === TOOLCRAFT_BROWSER_ACCEPTANCE_MARKER_TEST_NAME &&
+    normalizedFile.endsWith(
+      `/e2e/${TOOLCRAFT_BROWSER_ACCEPTANCE_MARKER_FILE_NAME}`,
+    )
+  );
+}
+
+function isProtectedPerformanceMarker(test: TestCase): boolean {
+  const normalizedFile = test.location.file.replaceAll("\\", "/");
+  return (
+    test.title === TOOLCRAFT_BROWSER_PERFORMANCE_MARKER_TEST_NAME &&
+    normalizedFile.endsWith(
+      `/e2e/${TOOLCRAFT_BROWSER_ACCEPTANCE_MARKER_FILE_NAME}`,
+    )
+  );
+}
+
+function toRuntimeTest(test: TestCase): ToolcraftBrowserRuntimeTest {
+  return {
+    expectedStatus: test.expectedStatus,
+    results: test.results.map((result) => ({
+      attachments: result.attachments,
+      retry: result.retry,
+      status: result.status,
+    })),
+    title: test.title,
+  };
+}
+
+export default class ToolcraftBrowserRuntimeEvidenceReporter implements Reporter {
+  private readonly acceptanceRequirementsOverride:
+    | readonly ToolcraftBrowserRuntimeRequirement[]
+    | undefined;
+
+  private readonly reportError: (error: string) => void;
+  private readonly performanceRequirementsOverride:
+    | readonly ToolcraftBrowserRuntimeRequirement[]
+    | undefined;
+
+  private acceptanceRequirements: readonly ToolcraftBrowserRuntimeRequirement[] = [];
+
+  private selectedTests: TestCase[] = [];
+  private performanceRequirements: readonly ToolcraftBrowserRuntimeRequirement[] = [];
+
+  private validateFullAcceptance = false;
+  private validateFullPerformance = false;
+
+  constructor(options: ToolcraftBrowserRuntimeEvidenceReporterOptions = {}) {
+    this.acceptanceRequirementsOverride = options.acceptanceRequirements;
+    this.performanceRequirementsOverride = options.performanceRequirements;
+    this.reportError =
+      options.reportError ??
+      ((error) => console.error(`[toolcraft browser evidence] ${error}`));
+  }
+
+  onBegin(_config: FullConfig, suite: Suite): void {
+    this.selectedTests = suite.allTests();
+    this.validateFullAcceptance = this.selectedTests.some(
+      isProtectedAcceptanceMarker,
+    );
+    this.validateFullPerformance = this.selectedTests.some(
+      isProtectedPerformanceMarker,
+    );
+    this.acceptanceRequirements =
+      this.acceptanceRequirementsOverride ??
+      deriveToolcraftBrowserRuntimeRequirements(starterAcceptance, starterSchema);
+    this.performanceRequirements =
+      this.performanceRequirementsOverride ??
+      deriveToolcraftPerformanceRuntimeRequirements(starterPerformance.scenarios);
+  }
+
+  onEnd(_result: FullResult): { status: "failed" } | undefined {
+    const selectedTitles = new Set(this.selectedTests.map((test) => test.title));
+    const acceptanceRequirements = this.validateFullAcceptance
+      ? this.acceptanceRequirements
+      : this.acceptanceRequirements.filter((requirement) =>
+          selectedTitles.has(requirement.testName),
+        );
+    const performanceRequirements = this.validateFullPerformance
+      ? this.performanceRequirements
+      : this.performanceRequirements.filter((requirement) =>
+          selectedTitles.has(requirement.testName),
+        );
+    const errors = evaluateToolcraftBrowserRuntimeEvidence({
+      requirements: [...acceptanceRequirements, ...performanceRequirements],
+      tests: this.selectedTests.map(toRuntimeTest),
+    });
+
+    if (errors.length === 0) {
+      return undefined;
+    }
+
+    for (const error of errors) {
+      this.reportError(error);
+    }
+
+    return { status: "failed" };
+  }
+
+  printsToStdio(): boolean {
+    return false;
+  }
+}