@tui-sandbox/library 12.3.1 → 12.4.0

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "12.3.1",
+  "version": "12.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/mikavilpas/tui-sandbox"
   },
   "license": "MIT",
   "type": "module",
+  "imports": {
+    "#tui-sandbox-template": "./src/server/cypress-support/tui-sandbox-template.ts"
+  },
   "exports": {
     ".": {
       "types": "./dist/src/client/index.d.ts",
@@ -33,12 +36,13 @@
     "tui": "dist/src/scripts/tui.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/server/cypress-support/tui-sandbox-template.ts"
   ],
   "dependencies": {
-    "@catppuccin/palette": "1.7.1",
-    "@trpc/client": "11.11.0",
-    "@trpc/server": "11.11.0",
+    "@catppuccin/palette": "1.8.0",
+    "@trpc/client": "11.16.0",
+    "@trpc/server": "11.16.0",
     "@xterm/addon-clipboard": "0.2.0",
     "@xterm/addon-fit": "0.11.0",
     "@xterm/addon-unicode11": "0.9.0",
@@ -59,12 +63,12 @@
     "@types/command-exists": "1.2.3",
     "@types/cors": "2.8.19",
     "@types/express": "5.0.6",
-    "@types/node": "24.11.0",
-    "cypress": "15.11.0",
+    "@types/node": "24.12.0",
+    "cypress": "15.13.0",
     "nodemon": "3.1.14",
-    "type-fest": "5.4.4",
-    "vite": "8.0.0-beta.16",
-    "vitest": "4.0.18"
+    "type-fest": "5.5.0",
+    "vite": "8.0.3",
+    "vitest": "4.1.2"
   },
   "peerDependencies": {
     "cypress": "^13 || ^14 || ^15",

package/src/server/cypress-support/tui-sandbox-template.ts

@@ -0,0 +1,344 @@
+/// <reference types="cypress" />
+//
+// This file is autogenerated by tui-sandbox. Do not edit it directly.
+//
+import type {
+  BrowserTerminalSettings,
+  GenericNeovimBrowserApi,
+  GenericTerminalBrowserApi,
+} from "@tui-sandbox/library/browser/neovim-client.js"
+import type { MyNeovimConfigModification } from "@tui-sandbox/library/client"
+import { drawTextBox } from "@tui-sandbox/library/client"
+import type {
+  AllKeys,
+  BlockingCommandClientInput,
+  BlockingShellCommandOutput,
+  ExCommandClientInput,
+  LuaCodeClientInput,
+  PollLuaCodeClientInput,
+  RunExCommandOutput,
+  RunLuaCodeOutput,
+  RunLuaFileClientInput,
+  StartNeovimGenericArguments,
+  StartTerminalGenericArguments,
+  TestDirectory,
+} from "@tui-sandbox/library/server"
+import type { OverrideProperties } from "type-fest"
+import type { MyNeovimAppName, MyTestDirectory, MyTestDirectoryFile } from "../../MyTestDirectory"
+
+export type TerminalTestApplicationContext = {
+  /** Types text into the terminal, making the terminal application receive the
+   * keystrokes as input. Requires the application to be running. */
+  typeIntoTerminal(text: string, options?: Partial<Cypress.TypeOptions>): void
+
+  /** Runs a shell command in a blocking manner, waiting for the command to
+   * finish before returning. Requires the terminal to be running. */
+  runBlockingShellCommand(input: MyBlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
+
+  /** The test directory, providing type-safe access to its file and directory structure */
+  dir: TestDirectory<MyTestDirectory>
+
+  /** Access to the clipboard of the terminal */
+  clipboard: {
+    system(): Cypress.Chainable<string>
+    primary(): Cypress.Chainable<string>
+  }
+
+  title: {
+    current(): Cypress.Chainable<string>
+  }
+}
+
+/** 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
+
+  /** Runs a shell command in a blocking manner, waiting for the command to
+   * finish before returning. Requires neovim to be running. */
+  runBlockingShellCommand(input: MyBlockingCommandClientInput): 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>
+
+  /** Runs a Lua file in neovim after it has started. Can be used to keep
+   * complex lua logic in a separate file, still being able to run it after
+   * startup. This way additional tools like lua LSP servers, linters, etc. can
+   * be used to ensure the code is correct.
+   */
+  doFile(input: MyRunLuaFileClientInput): Cypress.Chainable<RunExCommandOutput>
+
+  /**
+   * Like runLuaCode, but waits until the given code (maybe using lua's return
+   * assert()) does not raise an error, and returns the first successful result.
+   *
+   * Useful for waiting until Neovim's internal state has changed in a way that
+   * means the test can continue executing. This can avoid timing issues that are
+   * otherwise hard to catch.
+   */
+  waitForLuaCode(input: PollLuaCodeClientInput): 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>
+
+  /** Access to the clipboard of the terminal */
+  clipboard: {
+    system(): Cypress.Chainable<string>
+    primary(): Cypress.Chainable<string>
+  }
+
+  title: {
+    current(): Cypress.Chainable<string>
+  }
+}
+
+/** Arguments for starting the neovim server. They are built based on your test
+ * environment in a type safe manner. */
+export type MyStartNeovimServerArguments = OverrideProperties<
+  StartNeovimGenericArguments,
+  {
+    NVIM_APPNAME?: MyNeovimAppName
+    filename?: MyTestDirectoryFile | { openInVerticalSplits: MyTestDirectoryFile[] }
+    startupScriptModifications?: Array<MyNeovimConfigModification<MyTestDirectoryFile>>
+  }
+>
+
+export type MyRunLuaFileClientInput = OverrideProperties<RunLuaFileClientInput, { luaFile: MyTestDirectoryFile }>
+
+Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArguments) => {
+  cy.window().then(async win => {
+    const underlyingNeovim: GenericNeovimBrowserApi = await win.startNeovim(
+      startArguments as StartNeovimGenericArguments
+    )
+    testNeovim = underlyingNeovim
+    testEnvironmentPath = underlyingNeovim.dir.testEnvironmentPath
+
+    // 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,
+      nvim_waitForLuaCode: underlyingNeovim.waitForLuaCode,
+      nvim_doFile: underlyingNeovim.doFile,
+    })
+
+    const api: NeovimContext = {
+      runBlockingShellCommand(input) {
+        return cy.nvim_runBlockingShellCommand(input)
+      },
+      runExCommand(input) {
+        return cy.nvim_runExCommand(input)
+      },
+      runLuaCode(input) {
+        return cy.nvim_runLuaCode(input)
+      },
+      doFile(input) {
+        return cy.nvim_doFile(input)
+      },
+      waitForLuaCode(input) {
+        return cy.nvim_waitForLuaCode(input)
+      },
+      typeIntoTerminal(text, options) {
+        cy.typeIntoTerminal(text, options)
+      },
+      dir: underlyingNeovim.dir as TestDirectory<MyTestDirectory>,
+
+      clipboard: {
+        primary() {
+          return cy.then(() => underlyingNeovim.clipboard.primary())
+        },
+        system() {
+          return cy.then(() => underlyingNeovim.clipboard.system())
+        },
+      },
+
+      title: {
+        current: () => cy.then(() => underlyingNeovim.title.get()),
+      },
+    }
+
+    return api
+  })
+})
+
+Cypress.Commands.add("nvim_isRunning", () => {
+  return cy.window().then(async _ => {
+    return !!testNeovim
+  })
+})
+
+Cypress.Commands.add("startTerminalApplication", (args: StartTerminalGenericArguments & BrowserTerminalSettings) => {
+  cy.window().then(async win => {
+    const terminal: GenericTerminalBrowserApi = await win.startTerminalApplication({
+      serverSettings: {
+        commandToRun: args.commandToRun,
+        additionalEnvironmentVariables: args.additionalEnvironmentVariables,
+      } satisfies AllKeys<StartTerminalGenericArguments>,
+      browserSettings: {
+        configureTerminal: args.configureTerminal,
+      } satisfies AllKeys<BrowserTerminalSettings>,
+    })
+
+    testEnvironmentPath = terminal.dir.testEnvironmentPath
+
+    Cypress.Commands.addAll({
+      terminal_runBlockingShellCommand: terminal.runBlockingShellCommand,
+    })
+
+    const api: TerminalTestApplicationContext = {
+      dir: terminal.dir as TestDirectory<MyTestDirectory>,
+      runBlockingShellCommand(input) {
+        return cy.terminal_runBlockingShellCommand(input)
+      },
+      typeIntoTerminal(text, options) {
+        cy.typeIntoTerminal(text, options)
+      },
+      clipboard: {
+        primary: () => cy.then(() => terminal.clipboard.primary()),
+        system: () => cy.then(() => terminal.clipboard.system()),
+      },
+      title: {
+        current: () => cy.then(() => terminal.title.get()),
+      },
+    }
+
+    return api
+  })
+})
+
+Cypress.Commands.add("typeIntoTerminal", (text: string, options?: Partial<Cypress.TypeOptions>) => {
+  // the syntax for keys is described here:
+  // https://docs.cypress.io/api/commands/type
+  cy.get("textarea").focus().type(text, options)
+})
+
+let testNeovim: GenericNeovimBrowserApi | undefined
+let testEnvironmentPath: string | undefined
+
+before(function () {
+  // disable Cypress's default behavior of logging all XMLHttpRequests and
+  // fetches to the Command Log
+  // https://gist.github.com/simenbrekken/3d2248f9e50c1143bf9dbe02e67f5399?permalink_comment_id=4615046#gistcomment-4615046
+  cy.intercept({ resourceType: /xhr|fetch/ }, { log: false })
+})
+
+export type MyBlockingCommandClientInput = OverrideProperties<
+  BlockingCommandClientInput,
+  { cwdRelative?: MyTestDirectoryFile | undefined }
+>
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      startNeovim(args?: MyStartNeovimServerArguments): Chainable<NeovimContext>
+      startTerminalApplication(
+        args: StartTerminalGenericArguments & BrowserTerminalSettings
+      ): Chainable<TerminalTestApplicationContext>
+
+      /** 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>): Chainable<void>
+
+      /** Runs a shell command in a blocking manner, waiting for the command to
+       * finish before returning. Requires neovim to be running. */
+      nvim_runBlockingShellCommand(input: MyBlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
+
+      nvim_runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+      nvim_doFile(input: MyRunLuaFileClientInput): Chainable<RunExCommandOutput>
+      nvim_waitForLuaCode(input: PollLuaCodeClientInput): Chainable<RunLuaCodeOutput>
+
+      /** Run an ex command in neovim.
+       * @example "echo expand('%:.')" current file, relative to the cwd
+       */
+      nvim_runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
+
+      /** Returns true if neovim is running. Useful to conditionally run
+       * afterEach actions based on whether it's running. */
+      nvim_isRunning(): Chainable<boolean>
+
+      terminal_runBlockingShellCommand(input: MyBlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
+    }
+  }
+}
+
+afterEach(function () {
+  testNeovim = undefined
+
+  if (testEnvironmentPath) {
+    const testErr = this.currentTest?.err
+    const terminalContent = getTerminalContent() ?? ""
+
+    const snapshot = {
+      testTitle: this.currentTest?.fullTitle() ?? "unknown",
+      testState: this.currentTest?.state ?? "unknown",
+      terminalContent,
+      error: testErr?.message ?? null,
+      timestamp: new Date().toISOString(),
+    }
+
+    // Write to testdirs/ which is already gitignored for all tui-sandbox consumers.
+    // YAML is used so that multiline terminal content is human/AI-readable
+    // without escape sequences.
+    const snapshotPath = `${testEnvironmentPath}/testdirs/.terminal-snapshot.yaml`
+    const indentedContent = snapshot.terminalContent
+      .split("\n")
+      .map(line => `  ${line}`)
+      .join("\n")
+    const testFile = this.currentTest?.file ?? "unknown"
+    const yaml = [
+      `testTitle: ${JSON.stringify(snapshot.testTitle)}`,
+      `testFile: ${JSON.stringify(testFile)}`,
+      `testState: ${snapshot.testState}`,
+      `error: ${snapshot.error ? JSON.stringify(snapshot.error) : "null"}`,
+      `timestamp: ${JSON.stringify(snapshot.timestamp)}`,
+      `terminalContent: |`,
+      indentedContent,
+    ].join("\n")
+    cy.writeFile(snapshotPath, yaml, { log: false })
+  }
+})
+
+/** Read the current terminal content from the xterm.js DOM. */
+function getTerminalContent(): string | undefined {
+  const rows = Cypress.$("div.xterm-rows > div")
+  if (rows.length === 0) return undefined
+
+  const lines: string[] = []
+  rows.each((_, row) => {
+    lines.push(Cypress.$(row).text())
+  })
+
+  // Trim trailing empty lines for readability
+  while (lines.length > 0 && lines[lines.length - 1]?.trim() === "") {
+    lines.pop()
+  }
+
+  return lines.length > 0 ? lines.join("\n") : undefined
+}
+
+// On test failure in headless mode (cypress run / CI), append the terminal
+// buffer contents to the error message so it appears in logs. In interactive
+// mode (cypress open), the terminal is already visible on screen so this
+// would just add noise.
+//
+// Registered via beforeEach + cy.on (per-test) so that tests can override
+// with their own cy.on('fail') handler to swallow expected errors.
+beforeEach(function () {
+  cy.on("fail", (err: Error) => {
+    if (!Cypress.config("isInteractive")) {
+      const content = getTerminalContent()
+      if (content) {
+        err.message += `\n\n${drawTextBox("Terminal content at failure", content)}`
+      }
+    }
+
+    throw err
+  })
+})