ptywright 0.1.0

package/schemas/ptywright-script.schema.json

@@ -0,0 +1,297 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ptywright Script",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["launch", "steps"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "name": { "type": "string" },
+    "artifactsDir": { "type": "string" },
+    "launch": { "$ref": "#/$defs/launch" },
+    "trace": { "$ref": "#/$defs/trace" },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/step" }
+    }
+  },
+  "$defs": {
+    "textMaskRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regex"],
+      "properties": {
+        "regex": { "type": "string", "minLength": 1 },
+        "flags": { "type": "string" },
+        "replacement": { "type": "string" },
+        "preserveLength": { "type": "boolean" }
+      }
+    },
+    "launch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "args": { "type": "array", "items": { "type": "string" } },
+        "cwd": { "type": "string" },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "cols": { "type": "integer", "minimum": 1 },
+        "rows": { "type": "integer", "minimum": 1 },
+        "name": { "type": "string" }
+      }
+    },
+    "trace": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "saveCast": { "type": "boolean" },
+        "saveReport": { "type": "boolean" },
+        "castPath": { "type": "string" },
+        "reportPath": { "type": "string" },
+        "reportScope": { "type": "string", "enum": ["visible", "buffer"] },
+        "reportMaxFrames": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "step": {
+      "oneOf": [
+        { "$ref": "#/$defs/stepSendText" },
+        { "$ref": "#/$defs/stepPressKey" },
+        { "$ref": "#/$defs/stepSendMouse" },
+        { "$ref": "#/$defs/stepResize" },
+        { "$ref": "#/$defs/stepMark" },
+        { "$ref": "#/$defs/stepSleep" },
+        { "$ref": "#/$defs/stepWaitForText" },
+        { "$ref": "#/$defs/stepWaitForStableScreen" },
+        { "$ref": "#/$defs/stepWaitForExit" },
+        { "$ref": "#/$defs/stepExpectMeta" },
+        { "$ref": "#/$defs/stepSnapshot" },
+        { "$ref": "#/$defs/stepExpect" },
+        { "$ref": "#/$defs/stepAssert" },
+        { "$ref": "#/$defs/stepAssertSemantic" },
+        { "$ref": "#/$defs/stepExpectGolden" },
+        { "$ref": "#/$defs/stepCustom" }
+      ]
+    },
+    "stepSendText": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "text"],
+      "properties": {
+        "type": { "const": "sendText" },
+        "text": { "type": "string" },
+        "enter": { "type": "boolean" }
+      }
+    },
+    "stepPressKey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "key"],
+      "properties": {
+        "type": { "const": "pressKey" },
+        "key": { "type": "string", "minLength": 1 }
+      }
+    },
+    "stepSendMouse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "action", "x", "y"],
+      "properties": {
+        "type": { "const": "sendMouse" },
+        "action": {
+          "type": "string",
+          "enum": ["down", "up", "move", "click", "scroll_up", "scroll_down"]
+        },
+        "x": { "type": "integer" },
+        "y": { "type": "integer" },
+        "button": { "type": "string", "enum": ["left", "middle", "right"] },
+        "shift": { "type": "boolean" },
+        "alt": { "type": "boolean" },
+        "ctrl": { "type": "boolean" }
+      }
+    },
+    "stepResize": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "cols", "rows"],
+      "properties": {
+        "type": { "const": "resize" },
+        "cols": { "type": "integer", "minimum": 1 },
+        "rows": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "stepMark": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "mark" },
+        "label": { "type": "string" }
+      }
+    },
+    "stepSleep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "ms"],
+      "properties": {
+        "type": { "const": "sleep" },
+        "ms": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "stepWaitForText": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "waitForText" },
+        "scope": { "type": "string", "enum": ["visible", "buffer"] },
+        "text": { "type": "string" },
+        "regex": { "type": "string" },
+        "timeoutMs": { "type": "integer", "minimum": 1 },
+        "intervalMs": { "type": "integer", "minimum": 1 }
+      },
+      "anyOf": [{ "required": ["text"] }, { "required": ["regex"] }]
+    },
+    "stepWaitForStableScreen": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "waitForStableScreen" },
+        "timeoutMs": { "type": "integer", "minimum": 1 },
+        "quietMs": { "type": "integer", "minimum": 1 },
+        "intervalMs": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "stepWaitForExit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "waitForExit" },
+        "timeoutMs": { "type": "integer", "minimum": 1 },
+        "intervalMs": { "type": "integer", "minimum": 1 },
+        "exitCode": { "type": "integer" },
+        "signal": { "oneOf": [{ "type": "integer" }, { "type": "string" }] }
+      }
+    },
+    "stepExpectMeta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "expectMeta" },
+        "bufferType": { "type": "string", "enum": ["normal", "alternate"] },
+        "cols": { "type": "integer", "minimum": 1 },
+        "rows": { "type": "integer", "minimum": 1 },
+        "cursor": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["x", "y"],
+          "properties": {
+            "x": { "type": "integer", "minimum": 1 },
+            "y": { "type": "integer", "minimum": 1 }
+          }
+        }
+      },
+      "anyOf": [
+        { "required": ["bufferType"] },
+        { "required": ["cols"] },
+        { "required": ["rows"] },
+        { "required": ["cursor"] }
+      ]
+    },
+    "stepSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "kind"],
+      "properties": {
+        "type": { "const": "snapshot" },
+        "kind": { "type": "string", "enum": ["text", "view", "ansi", "view_ansi", "grid"] },
+        "scope": { "type": "string", "enum": ["visible", "buffer"] },
+        "trimRight": { "type": "boolean" },
+        "trimBottom": { "type": "boolean" },
+        "maxLines": { "type": "integer", "minimum": 1 },
+        "tailLines": { "type": "integer", "minimum": 1 },
+        "lineNumbers": { "type": "boolean" },
+        "includeStyles": { "type": "boolean" },
+        "mask": { "type": "array", "items": { "$ref": "#/$defs/textMaskRule" } },
+        "saveAs": { "type": "string" },
+        "saveTo": { "type": "string" }
+      },
+      "allOf": [
+        { "not": { "required": ["maxLines", "tailLines"] } },
+        {
+          "if": { "properties": { "kind": { "const": "grid" } } },
+          "then": { "not": { "required": ["mask"] } }
+        }
+      ]
+    },
+    "stepExpect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "expect" },
+        "from": { "type": "string" },
+        "equals": { "type": "string" },
+        "contains": { "type": "array", "items": { "type": "string" } },
+        "notContains": { "type": "array", "items": { "type": "string" } },
+        "regex": { "type": "string" }
+      },
+      "anyOf": [
+        { "required": ["equals"] },
+        { "required": ["contains"] },
+        { "required": ["notContains"] },
+        { "required": ["regex"] }
+      ]
+    },
+    "stepAssert": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "const": "assert" },
+        "scope": { "type": "string", "enum": ["visible", "buffer"] },
+        "text": { "type": "string" },
+        "regex": { "type": "string" },
+        "description": { "type": "string" }
+      },
+      "anyOf": [{ "required": ["text"] }, { "required": ["regex"] }]
+    },
+    "stepAssertSemantic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "prompt"],
+      "properties": {
+        "type": { "const": "assertSemantic" },
+        "prompt": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" }
+      }
+    },
+    "stepExpectGolden": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "path"],
+      "properties": {
+        "type": { "const": "expectGolden" },
+        "from": { "type": "string" },
+        "path": { "type": "string", "minLength": 1 }
+      }
+    },
+    "stepCustom": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "name"],
+      "properties": {
+        "type": { "const": "custom" },
+        "name": { "type": "string", "minLength": 1 },
+        "payload": {}
+      }
+    }
+  }
+}

package/skills/ptywright-testing/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ptywright-testing
+description: Terminal/TUI automation and regression testing using ptywright (PTY + xterm) via CLI or MCP tools. Use when you need to (1) drive a CLI/TUI app (send keys/mouse, wait, snapshot), (2) run scripted regressions (run/run-all) and review the HTML report (index.html + run.summary.json), or (3) record an interactive MCP-driven session into a replayable script with golden checkpoints.
+---
+
+# Ptywright Testing / 使用指南
+
+Use ptywright to run deterministic CLI/TUI regression tests with readable “terminal screenshots” and a Playwright-like HTML report.
+
+## How to run (发布版 vs 仓库内开发)
+
+This CLI is Bun-based (`#!/usr/bin/env bun`). For a released package, prefer `bunx`.
+
+- **Published package (recommended):**
+  - one-off: `bunx ptywright@latest <command>`
+  - pinned: `bunx ptywright@0.1.0 <command>`
+  - global: `bun add -g ptywright` then `ptywright <command>`
+- **Inside this repo (dev):**
+  - `bun run bin/ptywright <command>`
+
+## Choose the interface
+
+- **MCP tools**: best for agent-driven interactive flows (`launch_session`, `wait_for_text`, snapshots, recording).
+- **CLI**: best for local deterministic regressions and reviewing HTML reports.
+
+## Start the MCP server
+
+- stdio (default):
+  - published: `bunx ptywright@latest mcp`
+  - repo: `bun run bin/ptywright mcp`
+- restrict tools to reduce context:
+  - published: `bunx ptywright@latest mcp --caps core`
+  - repo: `bun run bin/ptywright mcp --caps core` (or `PTYWRIGHT_CAPS=core`)
+- Streamable HTTP:
+  - published: `bunx ptywright@latest mcp-http --port 3000`
+  - repo: `bun run bin/ptywright mcp-http --port 3000`
+
+Capabilities (`--caps` / `PTYWRIGHT_CAPS`) match MCP tools:
+
+- `all|core|debug|script|recording` (comma/space separated)
+
+## Run scripts (deterministic regression)
+
+### Run the whole suite (preferred)
+
+- CLI:
+  - published: `bunx ptywright@latest run-all --dir scripts`
+  - repo: `bun run bin/ptywright run-all --dir scripts`
+- Output to focus on:
+  - `reportPath` (open in a browser)
+  - `summaryPath` (`run.summary.json` for agents/CI)
+
+MCP equivalent:
+
+- `run_all_scripts` (defaults: `dir="scripts"`, suite report in `.tmp/run-all/`)
+- Keep MCP output small: `run_all_scripts(includeEntries="failures", maxEntries=20)`
+
+### Run one script
+
+- CLI:
+  - published: `bunx ptywright@latest run <file.json|file.ts> [--artifacts-dir <dir>]`
+  - repo: `bun run bin/ptywright run <file.json|file.ts> [--artifacts-dir <dir>]`
+- MCP: `run_script(scriptPath=...)`
+
+## Debug a failure
+
+Script runner artifacts to check (paths are returned by CLI/MCP):
+
+- `*.report.html` (timeline + snapshots)
+- `*.cast` (full playback)
+- `failure.last.view.txt` / `failure.last.txt` (last screen)
+- `failure.error.txt` (stack trace)
+
+Tip: for flaky waits, prefer `scope="buffer"` when the content may have scrolled into scrollback.
+
+## Record an interactive flow (MCP)
+
+1) `start_script_recording(name=...)`
+2) Drive the app with normal tools:
+   - `launch_session` → `send_text` / `press_key` / `wait_for_text` / `snapshot_*`
+3) Add golden checkpoints: `mark(label=...)`
+4) Export: `stop_script_recording(recordingId=..., writeFiles=true)`
+
+## All-tools smoke (recommended)
+
+To verify ptywright MCP tool coverage without relying on external apps/network, run:
+
+- `bun test tests/mcp_all_tools_smoke.test.ts`
+
+This exercises `core + debug + script + recording` tools end-to-end.
+
+## Determinism tips
+
+- Fix terminal size (`cols/rows`) and `TERM` (`xterm-256color`) in `launch_session`.
+- Use `wait_for_stable_screen` before assertions/snapshots to reduce flake.
+- Use `mask` to redact timestamps, random IDs, spinners, etc.
+- For live LLM apps: assert on stable markers/state transitions, not exact prose.
+
+## Environment knobs
+
+- `TUI_TEST_PTY_BACKEND=auto|bun-terminal|bun-pty`
+  - default `auto`: macOS/Linux prefers `bun-terminal`, Windows uses `bun-pty`