@tui-sandbox/library 7.7.0 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "7.7.0",
+  "version": "8.0.0",
   "license": "MIT",
   "type": "module",
   "bin": {

package/src/browser/neovim-client.ts

@@ -15,36 +15,39 @@ if (!app) {
 
 const client = new TerminalClient(app)
 
+export type GenericNeovimBrowserApi = {
+  runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
+  runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+  runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
+  dir: TestDirectory
+}
+
 /** Entrypoint for the test runner (cypress) */
-window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): Promise<TestDirectory> {
+window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): Promise<GenericNeovimBrowserApi> {
   const testDirectory = await client.startNeovim({
     additionalEnvironmentVariables: startArgs?.additionalEnvironmentVariables,
     filename: startArgs?.filename ?? "initial-file.txt",
     startupScriptModifications: startArgs?.startupScriptModifications ?? [],
   })
 
-  return testDirectory
-}
-
-window.runBlockingShellCommand = async function (
-  input: BlockingCommandClientInput
-): Promise<BlockingShellCommandOutput> {
-  return client.runBlockingShellCommand(input)
-}
-
-window.runLuaCode = async function (input: LuaCodeClientInput): Promise<RunLuaCodeOutput> {
-  return client.runLuaCode(input)
-}
+  const neovimBrowserApi: GenericNeovimBrowserApi = {
+    runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput> {
+      return client.runBlockingShellCommand(input)
+    },
+    runLuaCode(input) {
+      return client.runLuaCode(input)
+    },
+    runExCommand(input) {
+      return client.runExCommand(input)
+    },
+    dir: testDirectory,
+  }
 
-window.runExCommand = async function (input: ExCommandClientInput): Promise<RunExCommandOutput> {
-  return client.runExCommand(input)
+  return neovimBrowserApi
 }
 
 declare global {
   interface Window {
-    startNeovim(startArguments?: StartNeovimGenericArguments): Promise<TestDirectory>
-    runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
-    runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
-    runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
+    startNeovim(startArguments?: StartNeovimGenericArguments): Promise<GenericNeovimBrowserApi>
   }
 }

package/src/server/cypress-support/contents.ts

@@ -23,17 +23,30 @@ import type {
   TestDirectory,
 } from "@tui-sandbox/library/dist/src/server/types"
 import type { OverrideProperties } from "type-fest"
+import type { GenericNeovimBrowserApi } from "../../../library/src/browser/neovim-client.ts"
 import type { MyTestDirectory, MyTestDirectoryFile } from "../../MyTestDirectory"
 
-export type NeovimContext = TestDirectory<MyTestDirectory>
+/** The api that can be used in tests after a Neovim instance has been started. */
+export type NeovimContext = {
+  /** Types text into the terminal, making the terminal application receive
+   * the keystrokes as input. Requires neovim to be running. */
+  typeIntoTerminal(text: string, options?: Partial<Cypress.TypeOptions>): void
 
-declare global {
-  interface Window {
-    startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
-    runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
-    runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
-    runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
-  }
+  /** Runs a shell command in a blocking manner, waiting for the command to
+   * finish before returning. Requires neovim to be running. */
+  runBlockingShellCommand(input: BlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
+
+  /** Runs a shell command in a blocking manner, waiting for the command to
+   * finish before returning. Requires neovim to be running. */
+  runLuaCode(input: LuaCodeClientInput): Cypress.Chainable<RunLuaCodeOutput>
+
+  /** Run an ex command in neovim.
+   * @example "echo expand('%:.')" current file, relative to the cwd
+   */
+  runExCommand(input: ExCommandClientInput): Cypress.Chainable<RunExCommandOutput>
+
+  /** The test directory, providing type-safe access to its file and directory structure */
+  dir: TestDirectory<MyTestDirectory>
 }
 
 /** Arguments for starting the neovim server. They are built based on your test
@@ -42,21 +55,41 @@ type MyStartNeovimServerArguments = OverrideProperties<
   StartNeovimGenericArguments,
   {
     filename?: MyTestDirectoryFile | { openInVerticalSplits: MyTestDirectoryFile[] }
-    // NOTE: right now you need to make sure the config-modifications directory exists in your test directory
     startupScriptModifications?: Array<keyof MyTestDirectory["config-modifications"]["contents"]>
   }
 >
 
 Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArguments) => {
   cy.window().then(async win => {
-    testWindow = win
-    return await win.startNeovim(startArguments)
-  })
-})
+    const underlyingNeovim: GenericNeovimBrowserApi = await win.startNeovim(
+      startArguments as StartNeovimGenericArguments
+    )
+    testNeovim = underlyingNeovim
+
+    // wrap everything so that Cypress can await all the commands
+    Cypress.Commands.addAll({
+      nvim_runBlockingShellCommand: underlyingNeovim.runBlockingShellCommand,
+      nvim_runExCommand: underlyingNeovim.runExCommand,
+      nvim_runLuaCode: underlyingNeovim.runLuaCode,
+    })
+
+    const api: NeovimContext = {
+      runBlockingShellCommand(input) {
+        return cy.nvim_runBlockingShellCommand(input)
+      },
+      runExCommand(input) {
+        return cy.nvim_runExCommand(input)
+      },
+      runLuaCode(input) {
+        return cy.nvim_runLuaCode(input)
+      },
+      typeIntoTerminal(text, options) {
+        cy.typeIntoTerminal(text, options)
+      },
+      dir: underlyingNeovim.dir as TestDirectory<MyTestDirectory>,
+    }
 
-Cypress.Commands.add("runBlockingShellCommand", (input: BlockingCommandClientInput) => {
-  cy.window().then(async win => {
-    return await win.runBlockingShellCommand(input)
+    return api
   })
 })
 
@@ -66,19 +99,7 @@ Cypress.Commands.add("typeIntoTerminal", (text: string, options?: Partial<Cypres
   cy.get("textarea").focus().type(text, options)
 })
 
-Cypress.Commands.add("runLuaCode", (input: LuaCodeClientInput) => {
-  cy.window().then(async win => {
-    return await win.runLuaCode(input)
-  })
-})
-
-Cypress.Commands.add("runExCommand", (input: ExCommandClientInput) => {
-  cy.window().then(async win => {
-    return await win.runExCommand(input)
-  })
-})
-
-let testWindow: Window | undefined
+let testNeovim: GenericNeovimBrowserApi | undefined
 
 before(function () {
   // disable Cypress's default behavior of logging all XMLHttpRequests and
@@ -98,28 +119,34 @@ declare global {
 
       /** Runs a shell command in a blocking manner, waiting for the command to
        * finish before returning. Requires neovim to be running. */
-      runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
+      nvim_runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
-      runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+      nvim_runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
 
       /** Run an ex command in neovim.
        * @example "echo expand('%:.')" current file, relative to the cwd
        */
-      runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
+      nvim_runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
     }
   }
 }
 
 afterEach(async () => {
-  if (!testWindow) return
-  const timeout = new Promise<void>((resolve, reject) =>
-    setTimeout(() => {
-      Cypress.log({ name: "timeout when waiting for :messages to finish. Neovim might be stuck." })
-      reject("timeout when waiting for :messages to finish. Neovim might be stuck.")
+  if (!testNeovim) return
+
+  let timeoutId: NodeJS.Timeout | undefined = undefined
+  const timeout = new Promise<void>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      Cypress.log({ name: "timeout when waiting for :messages to finish. Neovim might be stuck or showing a message." })
+      reject(new Error("timeout when waiting for :messages to finish. Neovim might be stuck or showing a message."))
     }, 5_000)
-  )
+  })
 
-  await Promise.race([timeout, testWindow.runExCommand({ command: "messages" })])
+  try {
+    await Promise.race([timeout, testNeovim.runExCommand({ command: "messages" })])
+  } finally {
+    clearTimeout(timeoutId) // Ensure the timeout is cleared
+  }
 })
 `