miaoda-game-devkit 0.3.0 → 0.5.0

package/dist/react/testing.mjs

@@ -114,47 +114,123 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
+var MAX_TRACE_VALUE_LENGTH = 180;
+var MAX_TRACE_LENGTH = 720;
+function truncateTraceValue(value, limit) {
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
+function formatReactPlaythroughFailureTrace(trace) {
+  const stages = [
+    ["entered", trace.entered],
+    ["after-primary", trace.afterPrimary],
+    ["last", trace.last]
+  ].filter((stage) => stage[1] !== void 0).map(
+    ([stage, value]) => `${stage}=${truncateTraceValue(value, MAX_TRACE_VALUE_LENGTH)}`
+  );
+  const details = [
+    trace.checkpoints.length > 0 ? `checkpoints=${trace.checkpoints.join(",")}` : "checkpoints=none",
+    trace.step ? `stepUntil=${trace.step.completed ?? "failed"}/${trace.step.bound}` : void 0
+  ].filter((detail) => Boolean(detail));
+  const formatted = `${stages.join(" -> ")}${stages.length ? "; " : ""}${details.join("; ")}`;
+  return truncateTraceValue(formatted, MAX_TRACE_LENGTH);
+}
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
-  if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
-  if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
+  if (evidence.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
-function createMetadata(waiverReason) {
+function createEvidence() {
   return {
-    version: 3,
-    waiverReason,
-    evidence: {
-      domInputEvents: 0,
-      entryInputs: 0,
-      primaryInputs: 0,
-      boundedRuns: 0,
-      assertionsAfterOutcome: 0,
-      checkpoints: [],
-      verified: false
-    }
+    domInputEvents: 0,
+    entryInputs: 0,
+    primaryInputs: 0,
+    boundedRuns: 0,
+    assertionsAfterOutcome: 0,
+    checkpoints: [],
+    verified: false
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function createMetadata(waiverReason) {
+  return { version: 3, waiverReason, evidence: createEvidence() };
+}
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   test("production game completes a bounded playthrough", {
     skip: Boolean(reason),
     meta: { reactPlaythrough: metadata }
-  }, async ({ expect }) => {
+  }, async ({ annotate, expect }) => {
+    metadata.evidence = createEvidence();
+    metadata.trace = void 0;
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
+    let enteredTrace;
+    let afterPrimaryTrace;
+    let outcomeTrace;
+    let stepTrace;
+    const sampleDomTrace = () => JSON.stringify((document.body.textContent ?? "").replace(/\s+/g, " ").trim());
+    const sampleLastTrace = () => {
+      if (!playthroughOptions?.observe) return sampleDomTrace();
+      try {
+        return sampleObservation(playthroughOptions.observe, "outcome").formatted;
+      } catch (error) {
+        return `<observe unavailable: ${String(error)}>`;
+      }
+    };
+    const createFailureTrace = () => formatReactPlaythroughFailureTrace({
+      entered: enteredTrace,
+      afterPrimary: afterPrimaryTrace,
+      last: outcomeTrace ?? sampleLastTrace(),
+      checkpoints: [...evidence.checkpoints],
+      step: stepTrace
+    });
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -192,7 +268,18 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -207,7 +294,16 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+              enteredTrace = enteredObservation.formatted;
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -228,17 +324,43 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const stepBound = stepOptions.maxSteps ?? 120;
+          stepTrace = { bound: stepBound };
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
+          stepTrace = { bound: stepBound, completed: steps };
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
-            throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
             );
+            outcomeTrace = outcomeObservation.formatted;
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else {
+            outcomeTrace = sampleDomTrace();
+            if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+              throw new Error(
+                'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
+              );
+            }
           }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
@@ -273,7 +395,15 @@ function definePlaythrough(element, run, waiverReason) {
         );
       }
       evidence.verified = true;
+    } catch (error) {
+      metadata.trace = createFailureTrace();
+      try {
+        await annotate(metadata.trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
+      } catch {
+      }
+      throw error;
     } finally {
+      metadata.trace ??= createFailureTrace();
       for (const event of INPUT_EVENTS) {
         document.removeEventListener(event, recordInput, true);
       }
@@ -281,9 +411,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -300,7 +437,7 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -309,13 +446,17 @@ function auditReactPlaythroughRun(tests) {
       if (isValid || isWaived) continue;
       if (candidate.state === "skipped") {
         issues.push(
-          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u88AB\u8DF3\u8FC7\uFF0C\u4F46\u6CA1\u6709\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684\u660E\u786E\u7406\u7531\u3002`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }