JourneyStage

Agent-authored journeys. Deterministic tests. Repair-ready evidence.

English · 简体中文

JourneyStage turns structured test journeys written by your coding agent into runnable test interfaces. Run them manually or with Playwright, then use reports and evidence to investigate failures and verify repairs.

Installation & quick start

Current status: v0.1 development preview. This repository currently provides a source-build workflow. An npm package, Homebrew formula, or one-line release installer is not yet documented or verified; the shortest supported setup is below.

Maintainers: see npm release preparation for the checked tarball workflow and manual publishing. Preparing a package does not mean it has been published to npm.

Requires Node.js 22+, pnpm 11.13.0, and Git. CI covers macOS and Linux.

git clone https://github.com/chanshawoh/journey-stage.git
cd journey-stage
pnpm install --frozen-lockfile
pnpm build
pnpm cli ui --port 3000

Open http://127.0.0.1:3000. The command opens your browser automatically; add --no-browser to skip that. Stop the server with Ctrl+C.

For automatic runs, install Playwright Chromium once from the repository directory:

pnpm --filter @journeystage/web exec playwright install chromium

On Linux, use playwright install --with-deps chromium in the same command to install the required system libraries as well.

What you can do

| Capability | What it provides | | --- | --- | | OpenAPI import | Import OpenAPI 3.0/3.1 and validate journeys against API snapshots. | | Reusable test interfaces | Render structured journeys as versioned test UIs. | | Manual & automatic runs | Use the same Journey and UI revisions for manual execution and Playwright runs. | | Reports & evidence | Inspect run reports, screenshots, console/network artifacts, traces, and evidence bundles. | | Run comparison | Compare runs to investigate failures and check repairs. | | Agent integration | Prepare projects, upsert journeys, launch runs, and retrieve evidence through stdio MCP. | | Local storage | Keep versioned records locally, with retention policies, pinning, and cleanup tools. |

Your external agent authors and repairs the Journey Spec. JourneyStage validates it, executes it, and records the result; it does not require a built-in LLM.

Your first workflow

1. Register the application you want to test and import its OpenAPI specification.
2. Have your coding agent write a Journey Spec, then validate and import it.
3. Configure the target environment and any authentication profile.
4. Open the case in the Web UI and run it manually or automatically.
5. Inspect the report and evidence, make a repair, and compare the next run.

Run these commands from the JourneyStage checkout. Replace the example paths and PROJECT_ID with your own values; init prints the project ID.

pnpm cli init --name "My App" --path /absolute/path/to/my-app
pnpm cli openapi import /absolute/path/to/openapi.yaml --project-id PROJECT_ID
pnpm cli journey validate /absolute/path/to/example.journey.yaml --openapi /absolute/path/to/openapi.yaml
pnpm cli journey import /absolute/path/to/example.journey.yaml --project-id PROJECT_ID --openapi /absolute/path/to/openapi.yaml

Use pnpm cli --help to list commands, or pnpm cli <command> --help for options.

MCP integration

After building, configure your MCP client to launch JourneyStage over stdio. For clients that accept mcpServers JSON:

{
  "mcpServers": {
    "journeystage": {
      "command": "node",
      "args": ["/absolute/path/to/journey-stage/packages/cli/dist/bin.js", "mcp"]
    }
  }
}

Replace the checkout path. The client must be able to find Node.js 22+; use an absolute Node executable path if needed.

Available tools: project_prepare, journey_upsert, journey_open, journey_run, run_get, and evidence_get. Resources use the journeystage:// scheme. See the MCP implementation notes for the contract (Chinese).

Data & documentation

Data defaults to ~/.journeystage, shared by the CLI and MCP. Set JOURNEYSTAGE_HOME to use a different data directory, and use the same value in both processes when they should share records.

• Documentation index — requirements and implementation records (Chinese).
• MVP specification — product scope and acceptance criteria (Chinese).
• Development status — dated validation results and known limitations (Chinese).

Development from source

After the setup above, use these commands from the repository root:

pnpm build                                    # Build all packages and the Web UI
pnpm check                                    # Build and run unit/integration tests
pnpm --filter @journeystage/web test:e2e        # Run Web end-to-end tests (requires Chromium)

For Web UI development, keep pnpm cli ui --port 3000 --no-browser running in one terminal and run pnpm --filter @journeystage/web dev in another.

简体中文

Agent 编写测试旅程，确定性执行，用证据验证修复。

JourneyStage 将编程 Agent 编写的结构化测试旅程转换为可运行的测试界面。你可以手动执行，也可以使用 Playwright 自动执行，再通过报告和证据定位失败、验证修复。

安装与快速开始

当前状态：v0.1 开发预览。 仓库目前提供源码构建流程，尚无已记录并验证可用的 npm 包、Homebrew 配方或一行发行安装命令。以下是当前支持的最短启动步骤。

维护者可参考 npm 发布准备，生成并验证 tarball 后手动发布。完成本地打包不代表已发布到 npm。

需要 Node.js 22+、pnpm 11.13.0 和 Git。CI 覆盖 macOS 和 Linux。

git clone https://github.com/chanshawoh/journey-stage.git
cd journey-stage
pnpm install --frozen-lockfile
pnpm build
pnpm cli ui --port 3000

访问 http://127.0.0.1:3000。启动命令会自动打开浏览器；添加 --no-browser 可关闭此行为。按 Ctrl+C 停止服务。

需要使用自动运行时，在仓库目录执行一次 Chromium 安装：

pnpm --filter @journeystage/web exec playwright install chromium

Linux 上可将命令中的 playwright install chromium 替换为 playwright install --with-deps chromium，同时安装浏览器所需的系统依赖。

主要功能

| 能力 | 用途 | | --- | --- | | OpenAPI 导入 | 导入 OpenAPI 3.0/3.1，依据 API 快照校验测试旅程。 | | 可复用测试界面 | 将结构化旅程渲染为版本化的测试 UI。 | | 手动与自动运行 | 手动执行和 Playwright 运行共用 Journey 与 UI Revision。 | | 报告与证据 | 查看运行报告、截图、控制台与网络记录、Trace 和证据包。 | | 运行对比 | 对比多次运行，排查失败并验证修复。 | | Agent 集成 | 通过 stdio MCP 准备项目、写入旅程、启动运行和获取证据。 | | 本地存储 | 保存版本化记录，支持保留策略、固定保留和清理工具。 |

外部 Agent 负责编写和修复 Journey Spec，JourneyStage 负责校验、执行与记录结果，无需内置大模型。

第一个测试流程

1. 注册待测应用，导入它的 OpenAPI 规范。
2. 让编程 Agent 编写 Journey Spec，校验后导入。
3. 配置目标环境和所需的认证资料。
4. 在 Web UI 打开用例，手动或自动执行。
5. 查看报告与证据，修复问题后再次运行并对比结果。

以下命令在 JourneyStage 仓库目录执行。请替换示例路径和 PROJECT_ID；init 会输出项目 ID。

pnpm cli init --name "My App" --path /absolute/path/to/my-app
pnpm cli openapi import /absolute/path/to/openapi.yaml --project-id PROJECT_ID
pnpm cli journey validate /absolute/path/to/example.journey.yaml --openapi /absolute/path/to/openapi.yaml
pnpm cli journey import /absolute/path/to/example.journey.yaml --project-id PROJECT_ID --openapi /absolute/path/to/openapi.yaml

执行 pnpm cli --help 查看命令列表，或使用 pnpm cli <command> --help 查看参数。

接入 MCP

构建完成后，将 MCP 客户端配置为通过 stdio 启动 JourneyStage。支持 mcpServers JSON 的客户端可使用：

{
  "mcpServers": {
    "journeystage": {
      "command": "node",
      "args": ["/absolute/path/to/journey-stage/packages/cli/dist/bin.js", "mcp"]
    }
  }
}

请替换仓库绝对路径，并确保客户端能够找到 Node.js 22+；必要时将 command 改为 Node 可执行文件的绝对路径。

提供六个工具：project_prepare、journey_upsert、journey_open、journey_run、run_get、evidence_get。资源使用 journeystage:// 协议。详细合同见 MCP 实施记录。

数据与文档

数据默认保存在 ~/.journeystage，CLI 与 MCP 共用。设置 JOURNEYSTAGE_HOME 可更换数据目录；需要共享记录时，请让两个进程使用相同的值。

• 文档目录：需求与实施记录。
• MVP 定稿需求：产品范围与验收标准。
• 开发状态：带日期的验证结果与已知限制。

源码开发

完成前面的安装步骤后，在仓库根目录执行：

pnpm build                                    # 构建所有包和 Web UI
pnpm check                                    # 构建并运行单元/集成测试
pnpm --filter @journeystage/web test:e2e        # 运行 Web 端到端测试（需要 Chromium）

开发 Web UI 时，在一个终端运行 pnpm cli ui --port 3000 --no-browser，另一个终端运行 pnpm --filter @journeystage/web dev。