@ripplo/testing 0.0.11 → 0.1.0

package/dist/index.js

@@ -1,62 +1,97 @@
 import {
   compile
-} from "./chunk-LEIKZ6BE.js";
+} from "./chunk-KNF4K4JH.js";
 import "./chunk-MGATMMCZ.js";
 import {
-  DEFAULT_IGNORE_PATHS,
-  DEFAULT_WATCH_PATHS,
+  buildObserver,
   buildSetCookieHeader,
   createEngine,
-  dslConfigSchema,
-  readPreconditionName,
   serializeCookie,
   verifyWebhookSignature
-} from "./chunk-7ETQVVAA.js";
+} from "./chunk-CD3M7H5A.js";
+import {
+  DEFAULT_IGNORE_PATHS,
+  DEFAULT_WATCH_PATHS,
+  dslConfigSchema,
+  readObserverName,
+  readPreconditionName
+} from "./chunk-3IL457A7.js";
 
 // src/builder.ts
 function createRipplo(rawConfig) {
   const config = dslConfigSchema.parse(rawConfig);
   const preconditions = [];
+  const observers = [];
   const tests = [];
   const preconditionNames = /* @__PURE__ */ new Set();
+  const observerNames = /* @__PURE__ */ new Set();
   const testNames = /* @__PURE__ */ new Set();
+  function implementPrecondition(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}"`);
+    }
+    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);
+      }
+    };
+  }
+  function implementObserver(handle, impl) {
+    const name = readObserverName(handle);
+    const idx = observers.findIndex((o) => o.name === name);
+    if (idx === -1) {
+      throw new Error(`Cannot implement unknown observer: "${name}"`);
+    }
+    const existing = observers[idx];
+    if (existing == null) {
+      throw new Error(`Cannot implement unknown observer: "${name}"`);
+    }
+    observers[idx] = {
+      ...existing,
+      implemented: true,
+      run: async (ctx, params) => {
+        return impl(ctx, params);
+      }
+    };
+  }
   return {
+    implementObserver,
+    implementPrecondition,
     getConfig: () => config,
+    getObservers: () => observers,
     getPreconditions: () => preconditions,
     getTests: () => tests,
     getUnimplemented() {
       return {
+        observers: observers.filter((o) => !o.implemented).map((o) => o.name),
         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}"`);
+    observer(name) {
+      if (observerNames.has(name)) {
+        observers.splice(0, observers.length, ...observers.filter((o) => o.name !== name));
       }
-      const existing = preconditions[idx];
-      if (existing == null) {
-        throw new Error(`Cannot implement unknown precondition: "${preconditionName}"`);
-      }
-      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);
-        }
-      };
+      observerNames.add(name);
+      return buildObserver({ name, observers });
     },
     precondition(name) {
       if (preconditionNames.has(name)) {
@@ -69,13 +104,13 @@ function createRipplo(rawConfig) {
       preconditionNames.add(name);
       return buildPrecondition(name, preconditions);
     },
-    test(id) {
+    test(id, options) {
       validateTestId(id);
       if (testNames.has(id)) {
         tests.splice(0, tests.length, ...tests.filter((t) => t.id !== id));
       }
       testNames.add(id);
-      return buildTestName(id, tests);
+      return buildTestName(id, tests, options?.uiOnly);
     }
   };
 }
@@ -187,14 +222,19 @@ function validateTestId(id) {
     );
   }
 }
-function buildTestName(id, tests) {
+function buildTestName(id, tests, uiOnly) {
   return {
     name(displayName) {
-      return buildTestRequires({ id, name: displayName, tests });
+      return buildTestRequires({ id, name: displayName, tests, uiOnly });
     }
   };
 }
-function buildTestRequires({ id, name, tests }) {
+function buildTestRequires({
+  id,
+  name,
+  tests,
+  uiOnly
+}) {
   let description = "";
   const self = {
     requires: castBuilder(requiresImpl),
@@ -210,7 +250,7 @@ function buildTestRequires({ id, name, tests }) {
     Object.entries(reqs).forEach(([key, precondition]) => {
       requiresKeys[key] = readPreconditionName(precondition);
     });
-    return buildOutcome({ description, id, name, reqNames, requiresKeys, tests });
+    return buildOutcome({ description, id, name, reqNames, requiresKeys, tests, uiOnly });
   }
 }
 function buildOutcome({
@@ -219,7 +259,8 @@ function buildOutcome({
   name,
   reqNames,
   requiresKeys,
-  tests
+  tests,
+  uiOnly
 }) {
   let description = initialDesc;
   return {
@@ -235,7 +276,8 @@ function buildOutcome({
         name,
         reqNames,
         requiresKeys,
-        tests
+        tests,
+        uiOnly
       });
     }
   };
@@ -247,7 +289,8 @@ function buildStartsAt({
   name,
   reqNames,
   requiresKeys,
-  tests
+  tests,
+  uiOnly
 }) {
   return {
     startsAt: castBuilder(startsAtImpl),
@@ -261,7 +304,8 @@ function buildStartsAt({
         requires: [...reqNames],
         requiresKeys,
         startsAtFn: void 0,
-        stepsFn: void 0
+        stepsFn: void 0,
+        uiOnly
       });
     }
   };
@@ -279,7 +323,8 @@ function buildStartsAt({
         requires: [...reqNames],
         requiresKeys,
         startsAtFn: fn,
-        stepsFn
+        stepsFn,
+        uiOnly
       });
     }
   }
@@ -624,6 +669,73 @@ function expectedOutcomeKeywordCoverage(nodes, test, report) {
     });
   }
 }
+var BACKEND_MUTATION_KEYWORDS = /save|submit|create|delete|remove|send|invite|update|confirm|publish|apply|pay|subscribe|upgrade|cancel|archive|rename/i;
+function isLikelyBackendMutation(node) {
+  if (node.type === "upload") {
+    return true;
+  }
+  if (node.type === "handleDialog" && node.action === "accept") {
+    return true;
+  }
+  if (node.type !== "click") {
+    return false;
+  }
+  const loc = node.locator;
+  const name = loc.by === "role" ? loc.name ?? "" : loc.value;
+  return BACKEND_MUTATION_KEYWORDS.test(name);
+}
+function mutationWithoutObserverCoverage(nodes, test, report) {
+  if (!test.implemented || test.spec.uiOnly === true) {
+    return;
+  }
+  nodes.forEach((node, index) => {
+    if (!isLikelyBackendMutation(node)) {
+      return;
+    }
+    if ("uiOnly" in node && node.uiOnly === true) {
+      return;
+    }
+    const rest = nodes.slice(index + 1);
+    const nextMutationIdx = rest.findIndex((n) => isLikelyBackendMutation(n));
+    const windowEnd = nextMutationIdx === -1 ? rest.length : nextMutationIdx;
+    const window = rest.slice(0, windowEnd);
+    const hasObserver = window.some((n) => n.type === "assertObserver");
+    if (hasObserver) {
+      return;
+    }
+    report({
+      message: `"${node.label ?? node.id}" looks like it mutates backend state but no assert.backend(...) observer verifies it \u2014 the test can pass while the server is broken. You need to add an observer that checks the persisted result (see .ripplo/observers/ for examples). Only if this action truly does NOT change any server state (pure client-side interaction, presentation toggle, etc.) should you fall back to marking the step { uiOnly: true } to silence this rule.`,
+      rule: "mutation-without-observer-coverage",
+      step: node.label ?? node.id
+    });
+  });
+}
+function observerParamsReferenceVariables(nodes, test, report) {
+  const variableKeys = Object.keys(test.spec.variables ?? {});
+  if (variableKeys.length === 0) {
+    return;
+  }
+  nodes.forEach((node) => {
+    if (node.type !== "assertObserver") {
+      return;
+    }
+    const paramEntries = Object.entries(node.params);
+    if (paramEntries.length === 0) {
+      return;
+    }
+    const anyReferencesVariable = paramEntries.some(([, ref]) => {
+      return isStaticStringValue(ref) && isTemplateVar(ref.value);
+    });
+    if (anyReferencesVariable) {
+      return;
+    }
+    report({
+      message: `assert.backend "${node.label ?? node.id}" passes only hardcoded params while the test defines precondition variables \u2014 observer assertions should reference {{namespace.key}} so they match the actual precondition data`,
+      rule: "observer-params-reference-variables",
+      step: node.label ?? node.id
+    });
+  });
+}
 var RULES = [
   exactTextMatch,
   noHardcodedData,
@@ -636,7 +748,9 @@ var RULES = [
   noAssertions,
   lowAssertionRatio,
   tautologicalPostClickAssert,
-  expectedOutcomeKeywordCoverage
+  expectedOutcomeKeywordCoverage,
+  mutationWithoutObserverCoverage,
+  observerParamsReferenceVariables
 ];
 export {
   DEFAULT_IGNORE_PATHS,