@ripplo/testing 0.3.2 → 0.3.3

package/README.md

@@ -229,9 +229,13 @@ import { extract, variable } from "@ripplo/testing/control";
 
 const token = variable("token");
 extract(testId("token-value"), token).as("capture token");
-// token can be referenced in subsequent steps
+// pass the token anywhere a string value is accepted:
+fill(role("textbox", "Paste here"), token).as("paste token");
+assert.value(role("textbox", "Paste here"), token).as("assert token");
 ```
 
+Never reference a runtime variable with a literal `"{{vars.name}}"` string — always pass the `Variable` token so TypeScript verifies the reference.
+
 ### Step Labels
 
 Every step **must** have a `.as("description")` label:
@@ -260,6 +264,37 @@ test("delete-project")
 
 **Always destructure and use precondition data.** Never hardcode values that come from preconditions — if a precondition implementation changes, the test should not break.
 
+**Never write `"{{namespace.key}}"` as a string literal.** Pass the destructured proxy value directly. Internally the proxy stringifies to `{{namespace.key}}`, but writing the literal bypasses TypeScript so typos (`{{tabel.name}}`) silently compile and silently fail at runtime. The `no-literal-template-strings` lint rule enforces this.
+
+```typescript
+// ❌ WRONG — literal template string, no type-checking
+.steps(({ table }) => [
+  assert.value(role("textbox", "Table name"), "{{table.name}}").as("name visible"),
+])
+
+// ✅ CORRECT — proxy value, type-checked against requires()
+.steps(({ table }) => [
+  assert.value(role("textbox", "Table name"), table.name).as("name visible"),
+])
+```
+
+Runtime variables (captured via `clipboard`, `extract`, etc.) follow the same rule. Create a token with `variable("name")` and pass it anywhere a value is accepted:
+
+```typescript
+import { variable } from "@ripplo/testing/control";
+
+.steps(() => {
+  const copied = variable("copied");
+  return [
+    click(role("button", "Copy")).as("copy"),
+    clipboard({ action: "read", target: copied, value: undefined }).as("read clipboard"),
+    assert.value(role("button", "Copy"), copied).as("match clipboard"),
+  ];
+})
+```
+
+Never write `"{{vars.copied}}"` as a string literal — use the token.
+
 ## Wiring it together
 
 ### `.ripplo/ripplo.ts` — the definitions funnel

package/dist/actions.d.ts

@@ -1,7 +1,9 @@
+import { Variable, StaticStringRef, VariableRef } from './control.js';
 import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, InputLocator, AnyLocator, SelectLocator } from './locators.js';
 import '@ripplo/spec';
 
+type StringOrVariable = string | Variable<string>;
 declare function navigate(url: string): UnlabeledStep<{
     type: "goto";
     url: {
@@ -24,7 +26,7 @@ declare function click(locator: AnyLocator, options?: StepOptions): UnlabeledSte
     type: "click";
     uiOnly: boolean | undefined;
 }>;
-declare function fill(locator: InputLocator, value: string): UnlabeledStep<{
+declare function fill(locator: InputLocator, value: StringOrVariable): UnlabeledStep<{
     locator: {
         by: "testId";
         value: string;
@@ -34,12 +36,9 @@ declare function fill(locator: InputLocator, value: string): UnlabeledStep<{
         name?: string | undefined;
     };
     type: "fill";
-    value: {
-        type: "static";
-        value: string;
-    };
+    value: StaticStringRef | VariableRef;
 }>;
-declare function select(locator: SelectLocator, value: string): UnlabeledStep<{
+declare function select(locator: SelectLocator, value: StringOrVariable): UnlabeledStep<{
     locator: {
         by: "testId";
         value: string;
@@ -49,10 +48,7 @@ declare function select(locator: SelectLocator, value: string): UnlabeledStep<{
         name?: string | undefined;
     };
     type: "select";
-    value: {
-        type: "static";
-        value: string;
-    };
+    value: StaticStringRef | VariableRef;
 }>;
 declare function check(locator: CheckLocator): UnlabeledStep<{
     locator: {
@@ -137,7 +133,7 @@ declare function clear(locator: InputLocator): UnlabeledStep<{
     };
     type: "clear";
 }>;
-declare function typeText(locator: InputLocator, value: string): UnlabeledStep<{
+declare function typeText(locator: InputLocator, value: StringOrVariable): UnlabeledStep<{
     locator: {
         by: "testId";
         value: string;
@@ -147,10 +143,7 @@ declare function typeText(locator: InputLocator, value: string): UnlabeledStep<{
         name?: string | undefined;
     };
     type: "type";
-    value: {
-        type: "static";
-        value: string;
-    };
+    value: StaticStringRef | VariableRef;
 }>;
 declare function rightClick(locator: AnyLocator): UnlabeledStep<{
     locator: {
@@ -206,16 +199,13 @@ declare function handleDialog({ action, promptText, uiOnly }: HandleDialogOption
 }>;
 interface ClipboardOptions {
     readonly action: "read" | "write";
-    readonly value: string | undefined;
-    readonly variable: string | undefined;
+    readonly target: Variable<string> | undefined;
+    readonly value: StringOrVariable | undefined;
 }
-declare function clipboard({ action, value, variable }: ClipboardOptions): UnlabeledStep<{
+declare function clipboard({ action, target, value }: ClipboardOptions): UnlabeledStep<{
     action: "read" | "write";
     type: "clipboard";
-    value: {
-        type: "static";
-        value: string;
-    } | undefined;
+    value: StaticStringRef | VariableRef | undefined;
     variable: string | undefined;
 }>;
 interface SetPermissionOptions {

package/dist/actions.js

@@ -1,6 +1,8 @@
 import {
-  toSpecLocator
-} from "./chunk-2VUWFRR5.js";
+  readVariable,
+  toSpecLocator,
+  toStringValueRef
+} from "./chunk-P67G7RA7.js";
 import {
   createStep
 } from "./chunk-MGATMMCZ.js";
@@ -21,14 +23,14 @@ function fill(locator, value) {
   return createStep({
     locator: toSpecLocator(locator),
     type: "fill",
-    value: { type: "static", value }
+    value: toStringValueRef(value)
   });
 }
 function select(locator, value) {
   return createStep({
     locator: toSpecLocator(locator),
     type: "select",
-    value: { type: "static", value }
+    value: toStringValueRef(value)
   });
 }
 function check(locator) {
@@ -64,7 +66,7 @@ function typeText(locator, value) {
   return createStep({
     locator: toSpecLocator(locator),
     type: "type",
-    value: { type: "static", value }
+    value: toStringValueRef(value)
   });
 }
 function rightClick(locator) {
@@ -83,12 +85,12 @@ function drag(source, target) {
 function handleDialog({ action, promptText, uiOnly }) {
   return createStep({ action, promptText, type: "handleDialog", uiOnly });
 }
-function clipboard({ action, value, variable }) {
+function clipboard({ action, target, value }) {
   return createStep({
     action,
     type: "clipboard",
-    value: value == null ? void 0 : { type: "static", value },
-    variable
+    value: value == null ? void 0 : toStringValueRef(value),
+    variable: target == null ? void 0 : readVariable(target)
   });
 }
 function setPermission({ permission, state }) {

package/dist/assert.d.ts

@@ -1,9 +1,11 @@
 import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-Degkxs1f.js';
+import { Variable, StaticStringRef, VariableRef } from './control.js';
 import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, AnyLocator } from './locators.js';
 import 'zod';
 import '@ripplo/spec';
 
+type StringOrVariable = string | Variable<string>;
 declare const assert: {
     not: {
         checked(locator: CheckLocator): UnlabeledStep<{
@@ -51,12 +53,9 @@ declare const assert: {
             type: "assertNotVisible";
         }>;
     };
-    attribute(locator: AnyLocator, attribute: string, expected: string): UnlabeledStep<{
+    attribute(locator: AnyLocator, attribute: string, expected: StringOrVariable): UnlabeledStep<{
         attribute: string;
-        expected: {
-            type: "static";
-            value: string;
-        };
+        expected: StaticStringRef | VariableRef;
         locator: {
             by: "testId";
             value: string;
@@ -137,11 +136,8 @@ declare const assert: {
         };
         type: "assertFocused";
     }>;
-    text(locator: AnyLocator, expected: string): UnlabeledStep<{
-        expected: {
-            type: "static";
-            value: string;
-        };
+    text(locator: AnyLocator, expected: StringOrVariable): UnlabeledStep<{
+        expected: StaticStringRef | VariableRef;
         locator: {
             by: "testId";
             value: string;
@@ -153,19 +149,13 @@ declare const assert: {
         operator: "equals";
         type: "assertText";
     }>;
-    url(expected: string): UnlabeledStep<{
-        expected: {
-            type: "static";
-            value: string;
-        };
+    url(expected: StringOrVariable): UnlabeledStep<{
+        expected: StaticStringRef | VariableRef;
         operator: "contains";
         type: "assertUrl";
     }>;
-    value(locator: AnyLocator, expected: string): UnlabeledStep<{
-        expected: {
-            type: "static";
-            value: string;
-        };
+    value(locator: AnyLocator, expected: StringOrVariable): UnlabeledStep<{
+        expected: StaticStringRef | VariableRef;
         locator: {
             by: "testId";
             value: string;

package/dist/assert.js

@@ -1,6 +1,7 @@
 import {
-  toSpecLocator
-} from "./chunk-2VUWFRR5.js";
+  toSpecLocator,
+  toStringValueRef
+} from "./chunk-P67G7RA7.js";
 import {
   readObserverBudget,
   readObserverName
@@ -29,7 +30,7 @@ var assert = {
   attribute(locator, attribute, expected) {
     return createStep({
       attribute,
-      expected: { type: "static", value: expected },
+      expected: toStringValueRef(expected),
       locator: toSpecLocator(locator),
       operator: "equals",
       type: "assertAttribute"
@@ -65,7 +66,7 @@ var assert = {
   },
   text(locator, expected) {
     return createStep({
-      expected: { type: "static", value: expected },
+      expected: toStringValueRef(expected),
       locator: toSpecLocator(locator),
       operator: "equals",
       type: "assertText"
@@ -73,14 +74,14 @@ var assert = {
   },
   url(expected) {
     return createStep({
-      expected: { type: "static", value: expected },
+      expected: toStringValueRef(expected),
       operator: "contains",
       type: "assertUrl"
     });
   },
   value(locator, expected) {
     return createStep({
-      expected: { type: "static", value: expected },
+      expected: toStringValueRef(expected),
       locator: toSpecLocator(locator),
       operator: "equals",
       type: "assertValue"

package/dist/chunk-P67G7RA7.js

@@ -0,0 +1,58 @@
+import {
+  createStep
+} from "./chunk-MGATMMCZ.js";
+import {
+  readLocator
+} from "./chunk-DCJBLS2U.js";
+
+// src/steps/to-spec-locator.ts
+function toSpecLocator(loc) {
+  const spec = readLocator(loc);
+  switch (spec.by) {
+    case "role": {
+      return { by: "role", name: spec.name, role: spec.role };
+    }
+    case "testId": {
+      return { by: "testId", value: spec.value };
+    }
+  }
+}
+
+// src/steps/control.ts
+function variable(name) {
+  return { name };
+}
+function readVariable(v) {
+  return v.name;
+}
+function isVariable(v) {
+  if (typeof v !== "object" || v == null) {
+    return false;
+  }
+  if (!("name" in v)) {
+    return false;
+  }
+  return typeof v.name === "string";
+}
+function toStringValueRef(value) {
+  if (typeof value === "string") {
+    return { type: "static", value };
+  }
+  return { name: readVariable(value), type: "variable" };
+}
+function extract(locator, target) {
+  return createStep({
+    locator: toSpecLocator(locator),
+    type: "extractText",
+    variable: readVariable(target)
+  });
+}
+
+export {
+  toSpecLocator,
+  variable,
+  readVariable,
+  isVariable,
+  toStringValueRef,
+  extract
+};

package/dist/control.d.ts

@@ -8,6 +8,16 @@ interface Variable<_TName extends string> {
 }
 declare function variable<TName extends string>(name: TName): Variable<TName>;
 declare function readVariable(v: Variable<string>): string;
+declare function isVariable(v: unknown): v is Variable<string>;
+interface StaticStringRef {
+    readonly type: "static";
+    readonly value: string;
+}
+interface VariableRef {
+    readonly name: string;
+    readonly type: "variable";
+}
+declare function toStringValueRef(value: string | Variable<string>): StaticStringRef | VariableRef;
 declare function extract(locator: AnyLocator, target: Variable<string>): UnlabeledStep<{
     locator: {
         by: "testId";
@@ -21,4 +31,4 @@ declare function extract(locator: AnyLocator, target: Variable<string>): Unlabel
     variable: string;
 }>;
 
-export { type Variable, extract, readVariable, variable };
+export { type StaticStringRef, type Variable, type VariableRef, extract, isVariable, readVariable, toStringValueRef, variable };

package/dist/control.js

@@ -1,27 +1,16 @@
 import {
-  toSpecLocator
-} from "./chunk-2VUWFRR5.js";
-import {
-  createStep
-} from "./chunk-MGATMMCZ.js";
+  extract,
+  isVariable,
+  readVariable,
+  toStringValueRef,
+  variable
+} from "./chunk-P67G7RA7.js";
+import "./chunk-MGATMMCZ.js";
 import "./chunk-DCJBLS2U.js";
-
-// src/steps/control.ts
-function variable(name) {
-  return { name };
-}
-function readVariable(v) {
-  return v.name;
-}
-function extract(locator, target) {
-  return createStep({
-    locator: toSpecLocator(locator),
-    type: "extractText",
-    variable: readVariable(target)
-  });
-}
 export {
   extract,
+  isVariable,
   readVariable,
+  toStringValueRef,
   variable
 };

package/dist/index.js

@@ -716,9 +716,33 @@ function observerParamsReferenceVariables(nodes, test2, report) {
     });
   });
 }
+function noLiteralTemplateStrings(nodes, test2, report) {
+  const declaredKeys = new Set(Object.keys(test2.spec.variables ?? {}));
+  const pattern = /\{\{([^{}]+?)\}\}/g;
+  nodes.forEach((node) => {
+    const serialized = JSON.stringify(node);
+    const allMatches = [...serialized.matchAll(pattern)];
+    const undeclared = [
+      ...new Set(
+        allMatches.map((m) => m[1]).filter((key) => key != null && !declaredKeys.has(key))
+      )
+    ];
+    if (undeclared.length === 0) {
+      return;
+    }
+    const keyList = undeclared.map((k) => `{{${k}}}`).join(", ");
+    const namespaces = [...new Set(undeclared.map((k) => k.split(".")[0] ?? k))].join(", ");
+    report({
+      message: `"${node.label ?? node.id}" contains literal template string(s) ${keyList} \u2014 destructure the proxy in .steps(({ ${namespaces} }) => \u2026) and pass the proxy value (e.g. \`${undeclared[0] ?? ""}\`) directly. Writing the template as a string bypasses type-checking and silently accepts typos.`,
+      rule: "no-literal-template-strings",
+      step: node.label ?? node.id
+    });
+  });
+}
 var RULES = [
   exactTextMatch,
   noHardcodedData,
+  noLiteralTemplateStrings,
   preferPreconditionData,
   missingLabel,
   noDuplicateLabels,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "files": [
     "dist"

package/dist/chunk-2VUWFRR5.js

@@ -1,20 +0,0 @@
-import {
-  readLocator
-} from "./chunk-DCJBLS2U.js";
-
-// src/steps/to-spec-locator.ts
-function toSpecLocator(loc) {
-  const spec = readLocator(loc);
-  switch (spec.by) {
-    case "role": {
-      return { by: "role", name: spec.name, role: spec.role };
-    }
-    case "testId": {
-      return { by: "testId", value: spec.value };
-    }
-  }
-}
-
-export {
-  toSpecLocator
-};