Add support for testing our Talon api; test "phones" and "format" (#1728)

- Fixes #1721

## Checklist

- [ ] I have added
[tests](https://www.cursorless.org/docs/contributing/test-case-recorder/)
- [ ] I have updated the
[docs](https://github.com/cursorless-dev/cursorless/tree/main/docs) and
[cheatsheet](https://github.com/cursorless-dev/cursorless/tree/main/cursorless-talon/src/cheatsheet)
- [ ] I have not broken the cheatsheet

Author: pokey

.vscode/launch.json

@@ -59,6 +59,23 @@
         "!**/node_modules/**"
       ]
     },
+    {
+      "name": "Talon tests subset",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/packages/test-harness/out/scripts/runTalonTests",
+      "env": {
+        "CURSORLESS_TEST": "true",
+        "CURSORLESS_RUN_TEST_SUBSET": "true",
+        "CURSORLESS_REPO_ROOT": "${workspaceFolder}"
+      },
+      "outFiles": ["${workspaceFolder}/**/out/**/*.js"],
+      "preLaunchTask": "${defaultBuildTask}",
+      "resolveSourceMapLocations": [
+        "${workspaceFolder}/**",
+        "!**/node_modules/**"
+      ]
+    },
     {
       "name": "Unit tests only",
       "type": "node",

cursorless-talon-dev/src/cursorless_test.talon

@@ -0,0 +1,15 @@
+mode: user.cursorless_spoken_form_test
+tag: user.cursorless
+-
+
+# For testing our public api
+test api command <user.cursorless_target>:
+    user.cursorless_command("setSelection", cursorless_target)
+test api insert snippet:
+    user.cursorless_insert_snippet("Hello, $foo!  My name is $bar!")
+test api insert snippet by name:
+    user.cursorless_insert_snippet_by_name("functionDeclaration")
+test api wrap with snippet <user.cursorless_target>:
+    user.cursorless_wrap_with_snippet("Hello, $foo!  My name is $bar!", cursorless_target, "foo", "statement")
+test api wrap with snippet by name <user.cursorless_target>:
+    user.cursorless_wrap_with_snippet_by_name("functionDeclaration", "body", cursorless_target)

cursorless-talon-dev/src/spoken_form_test.py

@@ -1,5 +1,5 @@
 import json
-from typing import Any
+from typing import Any, Optional
 
 from talon import Context, Module, actions, scope
 
@@ -31,6 +31,8 @@
 # Keeps a list of commands run over the course of a spoken form test
 commands_run = []
 
+mockedGetValue = ""
+
 
 @ctx.action_class("user")
 class UserActions:
@@ -51,6 +53,7 @@ def private_cursorless_run_rpc_command_get(
         command_id: str, arg1: Any, arg2: Any = None
     ) -> Any:
         commands_run.append(arg1)
+        return mockedGetValue
 
 
 @mod.action_class
@@ -79,10 +82,14 @@ def private_cursorless_spoken_form_test_mode(enable: bool):
                 "Cursorless spoken form tests are done. Talon microphone is re-enabled."
             )
 
-    def private_cursorless_spoken_form_test(phrase: str):
+    def private_cursorless_spoken_form_test(
+        phrase: str, mockedGetValue_: Optional[str]
+    ):
         """Run Cursorless spoken form test"""
-        global commands_run
+        global commands_run, mockedGetValue
         commands_run = []
+        if mockedGetValue_:
+            mockedGetValue = json.loads(mockedGetValue_)
 
         try:
             actions.mimic(phrase)

cursorless-talon/src/actions/get_text.py

@@ -11,13 +11,18 @@ def cursorless_get_text_action(
     ensure_single_target: Optional[bool] = None,
 ) -> list[str]:
     """Get target texts"""
+    options = {}
+
+    if show_decorations is not None:
+        options["showDecorations"] = show_decorations
+
+    if ensure_single_target is not None:
+        options["ensureSingleTarget"] = ensure_single_target
+
     return actions.user.private_cursorless_command_get(
         {
             "name": "getText",
-            "options": {
-                "showDecorations": show_decorations,
-                "ensureSingleTarget": ensure_single_target,
-            },
+            "options": options,
             "target": target,
         }
     )

packages/cursorless-engine/src/test/fixtures/multiAction.fixture.ts

@@ -0,0 +1,55 @@
+import { ActionDescriptor } from "@cursorless/common";
+import { multiActionSpokenFormTest } from "./spokenFormTest";
+
+const getTextAction: ActionDescriptor = {
+  name: "getText",
+  target: {
+    type: "primitive",
+    mark: { type: "cursor" },
+  },
+  options: {
+    showDecorations: false,
+  },
+};
+
+const phonesReplaceAction: ActionDescriptor = {
+  name: "replace",
+  destination: {
+    type: "primitive",
+    insertionMode: "to",
+    target: {
+      type: "primitive",
+      mark: { type: "cursor" },
+    },
+  },
+  replaceWith: ["beet"],
+};
+
+const reformatReplaceAction: ActionDescriptor = {
+  name: "replace",
+  destination: {
+    type: "primitive",
+    insertionMode: "to",
+    target: {
+      type: "primitive",
+      mark: { type: "cursor" },
+    },
+  },
+  replaceWith: ["helloWorld"],
+};
+
+/**
+ * These test actions that are implemented Talon-side using multiple steps
+ */
+export const multiActionFixture = [
+  multiActionSpokenFormTest(
+    "phones this",
+    [getTextAction, phonesReplaceAction],
+    ["beat"],
+  ),
+  multiActionSpokenFormTest(
+    "format camel at this",
+    [getTextAction, reformatReplaceAction],
+    ["hello_world"],
+  ),
+];

packages/cursorless-engine/src/test/fixtures/spokenFormTest.ts

@@ -0,0 +1,54 @@
+import { ActionDescriptor, CommandV6 } from "@cursorless/common";
+
+export interface SpokenFormTest {
+  /**
+   * The spoken form that should be tested.  Will be passed to Talon's
+   * `actions.mimic` action.
+   */
+  spokenForm: string;
+
+  /**
+   * If this is set, we will mock the return value of the
+   * `user.private_cursorless_run_rpc_command_get` action to return the given
+   * value.
+   */
+  mockedGetValue: unknown | undefined;
+
+  /**
+   * The sequence of Cursorless commands that should be executed when
+   * {@link spokenForm} is spoken.
+   */
+  commands: CommandV6[];
+}
+
+export function spokenFormTest(
+  spokenForm: string,
+  action: ActionDescriptor,
+): SpokenFormTest {
+  return {
+    spokenForm,
+    mockedGetValue: undefined,
+    commands: [command(spokenForm, action)],
+  };
+}
+
+export function multiActionSpokenFormTest(
+  spokenForm: string,
+  actions: ActionDescriptor[],
+  mockedGetValue?: unknown,
+): SpokenFormTest {
+  return {
+    spokenForm,
+    mockedGetValue,
+    commands: actions.map((action) => command(spokenForm, action)),
+  };
+}
+
+function command(spokenForm: string, action: ActionDescriptor): CommandV6 {
+  return {
+    version: 6,
+    spokenForm,
+    usePrePhraseSnapshot: true,
+    action,
+  };
+}

packages/cursorless-engine/src/test/fixtures/spokenForms.fixture.ts renamed to packages/cursorless-engine/src/test/fixtures/synonymousSpokenForms.fixture.ts

@@ -1,4 +1,5 @@
-import { ActionDescriptor, CommandV6 } from "@cursorless/common";
+import { ActionDescriptor } from "@cursorless/common";
+import { spokenFormTest } from "./spokenFormTest";
 
 const verticalRangeAction: ActionDescriptor = {
   name: "setSelection",
@@ -41,23 +42,11 @@ const tokenForwardAction: ActionDescriptor = {
  * pick one in our spoken form generator, meaning we can't test the other in our
  * Talon tests by relying on our recorded test fixtures alone.
  */
-export const spokenFormsFixture: Required<CommandV6>[] = [
-  command("take air slice past bat", verticalRangeAction),
-  command("take air slice bat", verticalRangeAction),
+export const synonymousSpokenFormsFixture = [
+  spokenFormTest("take air slice past bat", verticalRangeAction),
+  spokenFormTest("take air slice bat", verticalRangeAction),
 
-  command("take one tokens forward", tokenForwardAction),
-  command("take one tokens", tokenForwardAction),
-  command("take token forward", tokenForwardAction),
+  spokenFormTest("take one tokens forward", tokenForwardAction),
+  spokenFormTest("take one tokens", tokenForwardAction),
+  spokenFormTest("take token forward", tokenForwardAction),
 ];
-
-function command(
-  spokenForm: string,
-  action: ActionDescriptor,
-): Required<CommandV6> {
-  return {
-    version: 6,
-    spokenForm,
-    usePrePhraseSnapshot: true,
-    action,
-  };
-}

packages/cursorless-engine/src/test/fixtures/talonApi.fixture.ts

@@ -0,0 +1,67 @@
+import { ActionDescriptor } from "@cursorless/common";
+import { spokenFormTest } from "./spokenFormTest";
+
+// See cursorless-talon-dev/src/cursorless_test.talon
+const setSelectionAction: ActionDescriptor = {
+  name: "setSelection",
+  target: {
+    type: "primitive",
+    mark: { type: "cursor" },
+  },
+};
+const insertSnippetAction: ActionDescriptor = {
+  name: "insertSnippet",
+  destination: { type: "implicit" },
+  snippetDescription: {
+    type: "custom",
+    body: "Hello, $foo!  My name is $bar!",
+  },
+};
+const insertSnippetByNameAction: ActionDescriptor = {
+  name: "insertSnippet",
+  destination: { type: "implicit" },
+  snippetDescription: {
+    type: "named",
+    name: "functionDeclaration",
+  },
+};
+const wrapWithSnippetAction: ActionDescriptor = {
+  name: "wrapWithSnippet",
+  target: {
+    type: "primitive",
+    mark: { type: "cursor" },
+  },
+  snippetDescription: {
+    type: "custom",
+    body: "Hello, $foo!  My name is $bar!",
+    variableName: "foo",
+    scopeType: { type: "statement" },
+  },
+};
+const wrapWithSnippetByNameAction: ActionDescriptor = {
+  name: "wrapWithSnippet",
+  target: {
+    type: "primitive",
+    mark: { type: "cursor" },
+  },
+  snippetDescription: {
+    type: "named",
+    name: "functionDeclaration",
+    variableName: "body",
+  },
+};
+
+/**
+ * These test our Talon api using dummy spoken forms defined in
+ * cursorless-talon-dev/src/cursorless_test.talon
+ */
+export const talonApiFixture = [
+  spokenFormTest("test api command this", setSelectionAction),
+  spokenFormTest("test api insert snippet", insertSnippetAction),
+  spokenFormTest("test api insert snippet by name", insertSnippetByNameAction),
+  spokenFormTest("test api wrap with snippet this", wrapWithSnippetAction),
+  spokenFormTest(
+    "test api wrap with snippet by name this",
+    wrapWithSnippetByNameAction,
+  ),
+];