@ripplo/testing 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { C as CookieEntry, R as RipploBuilder } from './builder-DTWMrbuv.js';
+export { a as CookieOptions, D as DslConfig, P as Precondition, b as PreconditionDeps, c as PreconditionImpl, d as PreconditionRecord, e as ResolveDeps, S as SetupContext, T as TeardownContext, f as createRipplo } from './builder-DTWMrbuv.js';
+import { CompileResult } from './compiler.js';
+export { CompiledTest, compile } from './compiler.js';
+export { D as DslNodeInput } from './step-DLfkKI3V.js';
+import 'zod';
+import '@ripplo/spec';
+
+interface LintDiagnostic {
+    readonly message: string;
+    readonly rule: string;
+    readonly step: string | undefined;
+    readonly test: string;
+}
+interface LintResult {
+    readonly diagnostics: ReadonlyArray<LintDiagnostic>;
+}
+declare function lint(result: CompileResult): LintResult;
+
+interface EngineResult {
+    readonly cookies: ReadonlyArray<CookieEntry>;
+    readonly data: Record<string, Record<string, string>>;
+    readonly error: string | undefined;
+    readonly executed: ReadonlyArray<string>;
+    readonly runId: string;
+    readonly success: boolean;
+}
+interface ExecuteBatchOptions {
+    readonly appUrl: string | undefined;
+}
+interface PreconditionEngine {
+    readonly executeBatch: (names: ReadonlyArray<string>, options?: ExecuteBatchOptions) => Promise<EngineResult>;
+    readonly teardown: (names: ReadonlyArray<string>, data: Record<string, Record<string, string>>) => Promise<void>;
+}
+declare function createEngine(ripplo: RipploBuilder): PreconditionEngine;
+
+interface WebhookHeaders {
+    readonly "webhook-id": string | undefined;
+    readonly "webhook-signature": string | undefined;
+    readonly "webhook-timestamp": string | undefined;
+}
+declare function verifyWebhookSignature(payload: string, headers: WebhookHeaders, secret: string): boolean;
+interface SerializedCookie {
+    readonly domain: string | undefined;
+    readonly expires: Date | undefined;
+    readonly httpOnly: boolean | undefined;
+    readonly name: string;
+    readonly path: string | undefined;
+    readonly sameSite: "lax" | "none" | "strict" | undefined;
+    readonly secure: boolean | undefined;
+    readonly value: string;
+}
+declare function serializeCookie(cookie: CookieEntry): SerializedCookie;
+declare function buildSetCookieHeader(cookie: SerializedCookie): string;
+
+export { CompileResult, CookieEntry, type EngineResult, type ExecuteBatchOptions, type LintDiagnostic, type LintResult, type PreconditionEngine, RipploBuilder, type SerializedCookie, buildSetCookieHeader, createEngine, lint, serializeCookie, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,464 @@
+import {
+  compile
+} from "./chunk-X2FROZPN.js";
+import "./chunk-MGATMMCZ.js";
+import {
+  buildSetCookieHeader,
+  createEngine,
+  dslConfigSchema,
+  readPreconditionName,
+  serializeCookie,
+  verifyWebhookSignature
+} from "./chunk-KWUKVAGI.js";
+
+// src/builder.ts
+function createRipplo(rawConfig) {
+  const config = dslConfigSchema.parse(rawConfig);
+  const preconditions = [];
+  const tests = [];
+  const preconditionNames = /* @__PURE__ */ new Set();
+  const testNames = /* @__PURE__ */ new Set();
+  return {
+    getConfig: () => config,
+    getPreconditions: () => preconditions,
+    getTests: () => tests,
+    getUnimplemented() {
+      return {
+        preconditions: preconditions.filter((p) => !p.implemented).map((p) => p.name),
+        tests: tests.filter((t) => !t.implemented).map((t) => t.name)
+      };
+    },
+    implement(handle, impl) {
+      const preconditionName = readPreconditionName(handle);
+      const idx = preconditions.findIndex((p) => p.name === preconditionName);
+      if (idx === -1) {
+        throw new Error(`Cannot implement unknown precondition: "${preconditionName}"`);
+      }
+      const existing = preconditions[idx];
+      if (existing == null) {
+        throw new Error(`Cannot implement unknown precondition: "${preconditionName}"`);
+      }
+      if (existing.implemented) {
+        throw new Error(`Precondition "${preconditionName}" is already implemented`);
+      }
+      const mapping = existing.depMapping;
+      preconditions[idx] = {
+        ...existing,
+        implemented: true,
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TData narrows Record<string, string>, safe at engine boundary
+        teardown: impl.teardown,
+        setup: async (ctx, allDeps) => {
+          const resolved = {};
+          mapping.forEach(([key, depName]) => {
+            const data = allDeps[depName];
+            if (data != null) {
+              resolved[key] = data;
+            }
+          });
+          return impl.setup(ctx, resolved);
+        }
+      };
+    },
+    precondition(name) {
+      if (preconditionNames.has(name)) {
+        throw new Error(`Duplicate precondition name: "${name}"`);
+      }
+      preconditionNames.add(name);
+      return buildPrecondition(name, preconditions);
+    },
+    test(id) {
+      validateTestId(id);
+      if (testNames.has(id)) {
+        throw new Error(`Duplicate test id: "${id}"`);
+      }
+      testNames.add(id);
+      return buildTestName(id, tests);
+    }
+  };
+}
+function buildDepMapping(deps) {
+  return Object.entries(deps).map(([key, dep]) => [key, readPreconditionName(dep)]);
+}
+function remapDeps(mapping, allDeps) {
+  const resolved = {};
+  mapping.forEach(([key, depName]) => {
+    const data = allDeps[depName];
+    if (data != null) {
+      resolved[key] = data;
+    }
+  });
+  return resolved;
+}
+function makePrecondition(name) {
+  return { name };
+}
+function castBuilder(value) {
+  return value;
+}
+function pushStub(params) {
+  params.preconditions.push({
+    dependsOn: params.depMapping.map(([_, depName]) => depName),
+    depMapping: params.depMapping,
+    description: params.description,
+    implemented: false,
+    name: params.name,
+    returns: [],
+    teardown: void 0,
+    setup: () => Promise.resolve({})
+  });
+  return makePrecondition(params.name);
+}
+function buildPrecondition(name, preconditions) {
+  let description = "";
+  let currentDeps = {};
+  const self = {
+    contract: castBuilder(
+      () => pushStub({ depMapping: buildDepMapping(currentDeps), description, name, preconditions })
+    ),
+    requires: castBuilder(requiresImpl),
+    setup: castBuilder(setupNoDepsImpl),
+    description(text) {
+      description = text;
+      return self;
+    },
+    notImplemented() {
+      pushStub({ depMapping: [], description, name, preconditions });
+      return makePrecondition(name);
+    }
+  };
+  return self;
+  function requiresImpl(deps) {
+    currentDeps = deps;
+    const mapping = buildDepMapping(deps);
+    const withDeps = {
+      contract: castBuilder(
+        () => pushStub({ depMapping: mapping, description, name, preconditions })
+      ),
+      setup: castBuilder(setupWithDepsImpl),
+      description(text) {
+        description = text;
+        return withDeps;
+      },
+      notImplemented() {
+        pushStub({ depMapping: mapping, description, name, preconditions });
+        return makePrecondition(name);
+      }
+    };
+    return castBuilder(withDeps);
+    function setupWithDepsImpl(fn) {
+      return registerPrecondition(deps, fn);
+    }
+  }
+  function setupNoDepsImpl(fn) {
+    return registerPrecondition({}, async (ctx) => fn(ctx));
+  }
+  function registerPrecondition(deps, fn) {
+    const mapping = buildDepMapping(deps);
+    const def = {
+      dependsOn: mapping.map(([_, depName]) => depName),
+      depMapping: mapping,
+      description,
+      implemented: true,
+      name,
+      returns: [],
+      teardown: void 0,
+      setup: async (ctx, allDeps) => {
+        const resolved = remapDeps(mapping, allDeps);
+        return fn(ctx, resolved);
+      }
+    };
+    preconditions.push(def);
+    return {
+      teardown(tdFn) {
+        def.teardown = tdFn;
+        return makePrecondition(name);
+      }
+    };
+  }
+}
+var TEST_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateTestId(id) {
+  if (!TEST_ID_PATTERN.test(id)) {
+    throw new Error(
+      `Invalid test id "${id}". Must be lowercase alphanumeric with hyphens (e.g. "my-test-id").`
+    );
+  }
+}
+function buildTestName(id, tests) {
+  return {
+    name(displayName) {
+      return buildTestRequires({ id, name: displayName, tests });
+    }
+  };
+}
+function buildTestRequires({ id, name, tests }) {
+  let description = "";
+  const self = {
+    requires: castBuilder(requiresImpl),
+    description(text) {
+      description = text;
+      return self;
+    }
+  };
+  return self;
+  function requiresImpl(reqs) {
+    const reqNames = Object.values(reqs).map((r) => readPreconditionName(r));
+    const requiresKeys = {};
+    Object.entries(reqs).forEach(([key, precondition]) => {
+      requiresKeys[key] = readPreconditionName(precondition);
+    });
+    return buildOutcome({ description, id, name, reqNames, requiresKeys, tests });
+  }
+}
+function buildOutcome({
+  description: initialDesc,
+  id,
+  name,
+  reqNames,
+  requiresKeys,
+  tests
+}) {
+  let description = initialDesc;
+  return {
+    description(text) {
+      description = text;
+      return this;
+    },
+    expectedOutcome(text) {
+      return buildStartsAt({
+        description,
+        expectedOutcome: text,
+        id,
+        name,
+        reqNames,
+        requiresKeys,
+        tests
+      });
+    }
+  };
+}
+function buildStartsAt({
+  description,
+  expectedOutcome,
+  id,
+  name,
+  reqNames,
+  requiresKeys,
+  tests
+}) {
+  return {
+    startsAt: castBuilder(startsAtImpl),
+    notImplemented() {
+      tests.push({
+        description,
+        expectedOutcome,
+        id,
+        implemented: false,
+        name,
+        requires: [...reqNames],
+        requiresKeys,
+        startsAtFn: void 0,
+        stepsFn: void 0
+      });
+    }
+  };
+  function startsAtImpl(fn) {
+    return {
+      steps: castBuilder(stepsImpl)
+    };
+    function stepsImpl(stepsFn) {
+      tests.push({
+        description,
+        expectedOutcome,
+        id,
+        implemented: true,
+        name,
+        requires: [...reqNames],
+        requiresKeys,
+        startsAtFn: fn,
+        stepsFn
+      });
+    }
+  }
+}
+
+// src/lint.ts
+function lint(result) {
+  const diagnostics = [];
+  result.tests.forEach((test) => {
+    const nodes = getOrderedNodes(test);
+    const report = (diagnostic) => {
+      diagnostics.push({ ...diagnostic, test: test.slug });
+    };
+    RULES.forEach((rule) => {
+      rule(nodes, test, report);
+    });
+  });
+  return { diagnostics };
+}
+function getOrderedNodes(test) {
+  const result = [];
+  let currentId = test.spec.entryNode;
+  const visited = /* @__PURE__ */ new Set();
+  while (currentId != null && !visited.has(currentId)) {
+    visited.add(currentId);
+    const found = test.spec.nodes[currentId];
+    if (found == null) {
+      break;
+    }
+    result.push(found);
+    currentId = found.next;
+  }
+  return result;
+}
+function exactTextMatch(nodes, _test, report) {
+  nodes.forEach((node) => {
+    if (node.type === "assertText" && "operator" in node && node.operator !== "equals") {
+      report({
+        message: `${node.type} uses operator "${node.operator}" \u2014 only "equals" is allowed for determinism`,
+        rule: "exact-text-match",
+        step: node.label ?? node.id
+      });
+    }
+  });
+}
+function noHardcodedData(nodes, test, report) {
+  const hasVariables = Object.keys(test.spec.variables ?? {}).length > 0;
+  if (!hasVariables) {
+    return;
+  }
+  nodes.forEach((node) => {
+    if (node.type === "fill" && isStaticStringValue(node.value)) {
+      const val = node.value.value;
+      if (!isTemplateVar(val) && looksLikeDynamicData(val)) {
+        report({
+          message: `fill() uses hardcoded value "${val}" \u2014 consider using precondition data via {{namespace.key}}`,
+          rule: "no-hardcoded-data",
+          step: node.label ?? node.id
+        });
+      }
+    }
+  });
+}
+function preferPreconditionData(nodes, test, report) {
+  const variableKeys = Object.keys(test.spec.variables ?? {});
+  if (variableKeys.length === 0) {
+    return;
+  }
+  const hasAnyTemplateRef = nodes.some((node) => JSON.stringify(node).includes("{{"));
+  if (!hasAnyTemplateRef) {
+    report({
+      message: "Test requires preconditions but steps() never references precondition data \u2014 destructure and use it",
+      rule: "prefer-precondition-data",
+      step: void 0
+    });
+  }
+}
+function missingLabel(nodes, _test, report) {
+  nodes.forEach((node) => {
+    if (node.label == null || node.label.length === 0) {
+      report({
+        message: `Step "${node.id}" lacks .as("...") label \u2014 every step must be labeled`,
+        rule: "missing-label",
+        step: node.id
+      });
+    }
+  });
+}
+function noDuplicateLabels(nodes, _test, report) {
+  const seen = /* @__PURE__ */ new Map();
+  nodes.forEach((node) => {
+    if (node.label == null) {
+      return;
+    }
+    const existing = seen.get(node.label);
+    if (existing == null) {
+      seen.set(node.label, node.id);
+    } else {
+      report({
+        message: `Duplicate label "${node.label}" \u2014 also used by ${existing}`,
+        rule: "no-duplicate-labels",
+        step: node.label
+      });
+    }
+  });
+}
+function assertAfterAction(nodes, _test, report) {
+  let consecutiveActions = 0;
+  nodes.forEach((node) => {
+    if (isAssertionNode(node)) {
+      consecutiveActions = 0;
+    } else {
+      consecutiveActions++;
+      if (consecutiveActions === 3) {
+        report({
+          message: "3+ consecutive actions without an assertion \u2014 add verification between actions",
+          rule: "assert-after-action",
+          step: node.label ?? node.id
+        });
+      }
+    }
+  });
+}
+function assertMatchesOutcome(nodes, _test, report) {
+  if (nodes.length === 0) {
+    return;
+  }
+  const lastNode = nodes.at(-1);
+  if (lastNode != null && !isAssertionNode(lastNode)) {
+    report({
+      message: "Last step is an action, not an assertion \u2014 expectedOutcome should be verified by assertions at the end",
+      rule: "assert-matches-outcome",
+      step: lastNode.label ?? lastNode.id
+    });
+  }
+}
+function noEmptySteps(nodes, _test, report) {
+  if (nodes.length === 0) {
+    report({
+      message: "Test has zero steps",
+      rule: "no-empty-steps",
+      step: void 0
+    });
+  }
+}
+function isStaticStringValue(val) {
+  if (typeof val !== "object" || val == null) {
+    return false;
+  }
+  if (!("type" in val) || val.type !== "static") {
+    return false;
+  }
+  if (!("value" in val) || typeof val.value !== "string") {
+    return false;
+  }
+  return true;
+}
+function isTemplateVar(value) {
+  return value.includes("{{");
+}
+function looksLikeDynamicData(value) {
+  return value.includes("@") || /\b[a-f0-9]{8,}\b/.test(value) || /^(test|ripplo|example|sample|demo)/i.test(value);
+}
+function isAssertionNode(node) {
+  return node.type.startsWith("assert");
+}
+var RULES = [
+  exactTextMatch,
+  noHardcodedData,
+  preferPreconditionData,
+  missingLabel,
+  noDuplicateLabels,
+  assertAfterAction,
+  assertMatchesOutcome,
+  noEmptySteps
+];
+export {
+  buildSetCookieHeader,
+  compile,
+  createEngine,
+  createRipplo,
+  lint,
+  serializeCookie,
+  verifyWebhookSignature
+};

package/dist/locators.d.ts

@@ -0,0 +1,30 @@
+type AriaRole = "alert" | "alertdialog" | "button" | "checkbox" | "combobox" | "dialog" | "form" | "grid" | "heading" | "img" | "link" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "navigation" | "option" | "progressbar" | "radio" | "region" | "row" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "switch" | "tab" | "tabpanel" | "textbox" | "toolbar" | "tooltip" | "tree" | "treeitem";
+type LocatorSpec = RoleLocatorSpec | TestIdLocatorSpec;
+interface RoleLocatorSpec {
+    readonly by: "role";
+    readonly name: string | undefined;
+    readonly role: AriaRole;
+}
+interface TestIdLocatorSpec {
+    readonly by: "testId";
+    readonly value: string;
+}
+declare const STRATEGY_BRAND: unique symbol;
+declare const ROLE_BRAND: unique symbol;
+declare const LOCATOR_INTERNAL: unique symbol;
+interface Locator<TStrategy extends string> {
+    readonly [LOCATOR_INTERNAL]: LocatorSpec;
+    readonly [STRATEGY_BRAND]: TStrategy;
+}
+interface RoleLocator<TRole extends AriaRole> extends Locator<"role"> {
+    readonly [ROLE_BRAND]: TRole;
+}
+declare function readLocator(loc: Locator<string>): LocatorSpec;
+type AnyLocator = Locator<"role" | "testId">;
+type InputLocator = Locator<"testId"> | RoleLocator<"combobox" | "searchbox" | "spinbutton" | "textbox">;
+type SelectLocator = Locator<"testId"> | RoleLocator<"combobox" | "listbox">;
+type CheckLocator = Locator<"testId"> | RoleLocator<"checkbox" | "switch">;
+declare function role<TRole extends AriaRole>(ariaRole: TRole, name?: string): RoleLocator<TRole>;
+declare function testId(id: string): Locator<"testId">;
+
+export { type AnyLocator, type AriaRole, type CheckLocator, type InputLocator, type Locator, type LocatorSpec, type RoleLocator, type SelectLocator, readLocator, role, testId };

package/dist/locators.js

@@ -0,0 +1,10 @@
+import {
+  readLocator,
+  role,
+  testId
+} from "./chunk-DCJBLS2U.js";
+export {
+  readLocator,
+  role,
+  testId
+};

package/dist/nextjs.d.ts

@@ -0,0 +1,12 @@
+import { R as RipploBuilder } from './builder-DTWMrbuv.js';
+import 'zod';
+import './step-DLfkKI3V.js';
+import '@ripplo/spec';
+
+interface CreateNextHandlerParams {
+    readonly ripplo: RipploBuilder;
+}
+type NextHandler = (req: Request) => Promise<Response>;
+declare function createNextHandler({ ripplo }: CreateNextHandlerParams): NextHandler;
+
+export { type CreateNextHandlerParams, createNextHandler };

package/dist/nextjs.js

@@ -0,0 +1,105 @@
+import {
+  batchRequestSchema,
+  buildSetCookieHeader,
+  createEngine,
+  serializeCookie,
+  teardownRequestSchema,
+  verifyWebhookSignature
+} from "./chunk-KWUKVAGI.js";
+
+// src/adapters/nextjs.ts
+function createNextHandler({ ripplo }) {
+  const engine = createEngine(ripplo);
+  const webhookSecret = ripplo.getConfig().webhookSecret;
+  return async function handler(req) {
+    const action = lastPathSegment(req.url);
+    if (action !== "execute-batch" && action !== "teardown") {
+      return jsonResponse({ error: "Not found" }, 404);
+    }
+    const verified = await verifyAndReadBody(req, webhookSecret);
+    if ("error" in verified) {
+      return verified.error;
+    }
+    if (action === "execute-batch") {
+      return handleExecuteBatch({ body: verified.body, engine, req });
+    }
+    return handleTeardown({ body: verified.body, engine });
+  };
+}
+async function handleExecuteBatch({
+  body,
+  engine,
+  req
+}) {
+  const json = tryParseJson(body);
+  const parsed = json == null ? null : batchRequestSchema.safeParse(json);
+  if (parsed == null || !parsed.success) {
+    return jsonResponse({ error: "Invalid request body", success: false }, 400);
+  }
+  const host = req.headers.get("host");
+  if (host == null || host.length === 0) {
+    return jsonResponse({ error: "Missing host header", success: false }, 400);
+  }
+  const proto = req.headers.get("x-forwarded-proto") ?? "http";
+  const appUrl = `${proto}://${host}`;
+  const result = await engine.executeBatch(parsed.data.preconditions, { appUrl });
+  const headers = new Headers({ "content-type": "application/json" });
+  result.cookies.forEach((cookie) => {
+    headers.append("Set-Cookie", buildSetCookieHeader(serializeCookie(cookie)));
+  });
+  return new Response(
+    JSON.stringify({
+      data: result.data,
+      error: result.error,
+      executed: result.executed,
+      runId: result.runId,
+      success: result.success
+    }),
+    { headers, status: 200 }
+  );
+}
+async function handleTeardown({ body, engine }) {
+  const json = tryParseJson(body);
+  const parsed = json == null ? null : teardownRequestSchema.safeParse(json);
+  if (parsed == null || !parsed.success) {
+    return jsonResponse({ error: "Invalid request body", success: false }, 400);
+  }
+  await engine.teardown(parsed.data.preconditions, parsed.data.data);
+  return jsonResponse({ success: true }, 200);
+}
+async function verifyAndReadBody(req, webhookSecret) {
+  if (webhookSecret.length === 0) {
+    return { error: jsonResponse({ error: "Webhook secret not configured" }, 403) };
+  }
+  const body = await req.text();
+  const headers = {
+    "webhook-id": req.headers.get("webhook-id") ?? void 0,
+    "webhook-signature": req.headers.get("webhook-signature") ?? void 0,
+    "webhook-timestamp": req.headers.get("webhook-timestamp") ?? void 0
+  };
+  if (!verifyWebhookSignature(body, headers, webhookSecret)) {
+    return { error: jsonResponse({ error: "Invalid webhook signature" }, 401) };
+  }
+  return { body };
+}
+function lastPathSegment(url) {
+  const pathname = new URL(url).pathname;
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  return segments.at(-1) ?? "";
+}
+function tryParseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function jsonResponse(payload, status) {
+  return new Response(JSON.stringify(payload), {
+    headers: { "content-type": "application/json" },
+    status
+  });
+}
+export {
+  createNextHandler
+};

package/dist/step-DLfkKI3V.d.ts

@@ -0,0 +1,19 @@
+import { SpecNode } from '@ripplo/spec';
+
+type DslNodeType = "assertAttribute" | "assertChecked" | "assertCount" | "assertDisabled" | "assertEnabled" | "assertFocused" | "assertNotChecked" | "assertNotFocused" | "assertNotVisible" | "assertText" | "assertUrl" | "assertValue" | "assertVisible" | "check" | "clear" | "click" | "clipboard" | "dblclick" | "drag" | "extractText" | "fill" | "focus" | "goto" | "handleDialog" | "hover" | "press" | "rightClick" | "scrollIntoView" | "select" | "setPermission" | "setViewport" | "type" | "uncheck" | "upload";
+type StepBaseFields = "comment" | "id" | "label" | "next" | "timeout";
+type DslNodeInput = SpecNode extends infer N ? N extends SpecNode ? N["type"] extends DslNodeType ? Omit<N, StepBaseFields> : never : never : never;
+
+declare const STEP_INTERNAL: unique symbol;
+interface StepData<TNode extends DslNodeInput> {
+    readonly label: string;
+    readonly node: TNode;
+}
+interface Step<TNode extends DslNodeInput = DslNodeInput> {
+    readonly [STEP_INTERNAL]: StepData<TNode>;
+}
+interface UnlabeledStep<TNode extends DslNodeInput = DslNodeInput> {
+    as(label: string): Step<TNode>;
+}
+
+export type { DslNodeInput as D, Step as S, UnlabeledStep as U };