# Testcopilot

> Use this skill when the user asks Codex to work with TestCopilot or run a TestCopilot MCP closed-loop workflow from a requirement document or requirement text: configure MCP token/server/runtime paths, query/select a TestCopilot project, generate functional cases, validate generated cases against the requirement, save cases, create or use the MCP-created module/test plan, trigger AI execution, poll logs, collect structured defects, and optionally repair code and rerun regression. Triggers include "$testcopilot", "TestCopilot 闭环", "初始化 TestCopilot MCP", "配置 TestCopilot token", "配置执行环境", "用 MCP 跑需求", "完整跑一遍流程", "只执行第一个测试用例", "生成用例并触发 AI 执行", or similar Chinese/English requests.

- Skill: `roclv/testcopilot` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add roclv/testcopilot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/roclv/testcopilot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: rocLv (https://skillmd.com/u/roclv)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/roclv/testcopilot

---


# TestCopilot Closed Loop

Use TestCopilot MCP tools to drive this workflow:

```text
requirement -> project selection -> case generation -> case validation
-> case save/module creation -> test plan creation/binding
-> AI execution -> log polling -> result/defect summary
-> code repair -> regression rerun
```

Do not print or store user tokens. Use the MCP server already configured in Codex, or the server URL and headers the user explicitly provides.

## Init Command

Use this mode when the user says "初始化", "配置", "设置 token", "设置安装路径", "prepare TestCopilot MCP", or when required configuration is missing.

Initialization should collect and validate:

- MCP server URL, defaulting to `https://tgeek.cn/prod-api/sse` unless the user provides another URL.
- Personal access token, accepted as `Authorization: Bearer <token>` or `X-AUTH-TOKEN: <token>`.
- TestCopilot local bundled Python runtime readiness when local execution is required.

Never write the token into Skill files, docs, git-tracked files, or final responses. If Codex has an MCP config mechanism available, update that config with the token only when the user explicitly asks Codex to configure it. Otherwise tell the user exactly which MCP config fields to set.

### Initialization Workflow

1. Check whether a TestCopilot MCP server is already configured and reachable.
   - Connect to the SSE URL.
   - Run `tools/list`.
   - Confirm the core tools are present.

2. If authentication fails or no token is configured:
   - Ask the user to provide a personal access token generated from TestCopilot.
   - Use only token auth. Do not use accessKey, secretKey, or signature.
   - After receiving the token, validate it by calling `testcopilot_list_projects` with a small page size.

3. Resolve local bundled Python runtime paths.
   - Remote MCP servers cannot see the user's local filesystem. Do not ask a remote MCP server to validate local install paths.
   - macOS default install dir: `/Applications/TestCopilot.app`
   - macOS default Python project dir: `/Applications/TestCopilot.app/Contents/Resources/PythonEnv/deepseek_chat_package_v2`
   - macOS bundled uv candidates:
     - `/Applications/TestCopilot.app/Contents/Resources/PythonEnv/uv-runtime/darwin-arm64/uv`
     - `/Applications/TestCopilot.app/Contents/Resources/PythonEnv/uv-runtime/darwin-x64/uv`
   - Linux packaged/server candidates:
     - `/opt/TestCopilot/resources/PythonEnv/deepseek_chat_package_v2`
     - `/opt/testcopilot/resources/PythonEnv/deepseek_chat_package_v2`
     - `/metersphere/static/python-env/deepseek_chat_package_v2`
     - `/metersphere/static/python-env/uv-runtime/linux-x64/uv`
   - Windows has no reliable universal default. Ask the user for the TestCopilot installation directory, then derive:
     - `<install_dir>\\resources\\PythonEnv\\deepseek_chat_package_v2`
     - `<install_dir>\\PythonEnv\\deepseek_chat_package_v2`
     - `<install_dir>\\resources\\PythonEnv\\uv-runtime\\win-x64\\uv.exe`
     - `<install_dir>\\PythonEnv\\uv-runtime\\win-x64\\uv.exe`

4. Validate local runner readiness.
   - For a remote MCP server, execution should be run by Codex on the user's machine using the local TestCopilot bundled Python runtime.
   - For a local MCP server running on the same machine as the installed app, runtime validation may use `configure_execution_runtime`.
   - Treat `waiting_local_runner` as the normal remote-MCP execution state after task creation.

5. Report the initialized state.
   - Say whether MCP auth works.
   - Say which server URL is configured.
   - Say whether Codex can locate the local bundled Python runtime or still needs the user to provide the install directory.
   - Show install/runtime paths only when they refer to the user's local machine and the user provided or confirmed them. Never show the token.

Example initialization prompts the user may use:

```text
用 $testcopilot 初始化 TestCopilot MCP，服务器是 https://tgeek.cn/prod-api/sse，我会提供 token。
```

```text
用 $testcopilot 配置执行环境。我的 Windows 安装目录是 C:\Users\me\AppData\Local\Programs\TestCopilot
```

## Preflight Before Every Run

Before every closed-loop run, perform a lightweight preflight. Do this even when the user did not explicitly ask for initialization.

1. Check MCP connectivity.
   - Try the configured TestCopilot MCP server first.
   - If no configured server is discoverable but the user provided a URL, use that URL.
   - If neither exists, stop and show this configuration shape:

```json
{
  "mcpServers": {
    "testcopilot": {
      "url": "https://tgeek.cn/prod-api/sse",
      "headers": {
        "Authorization": "Bearer <your_testcopilot_token>"
      }
    }
  }
}
```

2. Validate token authentication.
   - Connect to `/sse`.
   - Run `tools/list`.
   - Call `testcopilot_list_projects` with `pageSize = 1`.
   - If auth fails, ask only for a TestCopilot personal access token. Do not ask for accessKey, secretKey, or signature.

3. Confirm core tools are available.
   - Required before generation/save: `testcopilot_list_projects`, `generate_function_cases`, `push_cases_to_testcopilot`.
   - Required before execution: `trigger_ai_execution`.
   - Required for logs/results: `get_execution_logs`, `get_execution_result`.
   - If tools are missing, stop and report exactly which tools are unavailable.

4. Check local runner expectations.
   - For remote MCP (`https://.../sse`), do not check remote server paths for the user's local Python runtime.
   - Expect `trigger_ai_execution` to create execution records and return `waiting_local_runner`.
   - After task creation, Codex should directly invoke the local bundled Python executor; do not ask the user to start a separate Agent.
   - On macOS, try `/Applications/TestCopilot.app` and the repository `electron-frontend/PythonEnv` before asking.
   - On Windows, ask the user for the TestCopilot install directory unless already provided.

5. Continue according to what is missing.
   - If MCP/token/tools are missing, stop before generating cases.
   - If only local bundled Python runtime is missing, generate/save cases and create execution tasks, then ask for the install directory before starting local execution.
   - Ask for the smallest missing piece of configuration, not a full setup form.

## Required Inputs

- Requirement source: a `.docx` path, text, Markdown, or other readable file.
- Project name or project id.
- Execution scope: first case only, selected cases, or all cases. If unspecified, ask only when executing all cases could be expensive; otherwise default to first case for demos.

Optional inputs:

- `repo_path`
- `environment`
- `template_id`
- `install_dir` for local bundled Python runtime setup
- `python_project_dir` for local MCP only
- `uv_bin` for local MCP only

## MCP Tools

Core tools:

- `testcopilot_list_projects`
- `testcopilot_get_project`
- `testcopilot_search_functional_cases`
- `generate_function_cases`
- `push_cases_to_testcopilot`
- `trigger_ai_execution`
- `get_execution_logs`
- `get_execution_result`

Optional/runtime tool:

- `configure_execution_runtime`

## Workflow

0. Run the preflight above.
   - Do not skip this step.
   - If preflight stops, do not attempt later workflow steps.

1. Read the requirement.
   - For `.docx`, extract visible paragraph text.
   - Preserve URLs, credentials, feature names, acceptance criteria, and expected behavior.
   - Summarize the requirement before running MCP.

2. Query the project.
   - Call `testcopilot_list_projects` with the provided project name.
   - Prefer exact name match over keyword match.
   - If multiple plausible projects remain, ask the user to choose.
   - Record `project_id`, project name, and platform.

3. Resolve the functional case template.
   - If the user supplied `template_id`, use it.
   - Otherwise call `testcopilot_search_functional_cases` for the selected project and infer a reusable `template_id` from existing functional cases.
   - If no template can be inferred, stop and report that a project functional case template is needed.

4. Generate cases.
   - Call `generate_function_cases(requirement, project_id, template_id)`.
   - Check whether the generated cases match the actual requirement topic and inputs.
   - For login requirements, verify that generated steps mention the right login method, target URL, account fields, credentials, and success/failure behavior.
   - If generated cases are clearly wrong, report the mismatch as a TestCopilot MCP generation issue.

5. Select cases for execution.
   - If the user says "只执行第一个测试用例", save and execute exactly one case.
   - Prefer a generated case that actually matches the requirement.
   - If no generated case matches but the user asked to continue the validation, construct a minimal first-case JSON from the requirement and clearly state that it is a fallback for validating the save/execute chain.

6. Save cases.
   - Call `push_cases_to_testcopilot`.
   - Use the requirement title as-is; do not add any MCP-related marker, prefix, or suffix.
   - Let the MCP tool create the module and test plan when supported.
   - Record `case_set_id`, `module_id`, `case_ids`, `test_plan_id`, `test_plan_case_ids`, and `case_version`.

7. Trigger execution.
   - Call `trigger_ai_execution(case_set_id, repo_path, test_plan_id, environment, install_dir?, python_project_dir?, uv_bin?)`.
   - If the user did not provide `repo_path`, use the current workspace path when relevant.
   - If the requirement includes a test endpoint, pass it as `environment`.
   - For remote MCP, expect the tool to create execution records and return `waiting_local_runner`, not to launch Python on the server.

8. Run the local bundled Python executor.
   - If `trigger_ai_execution` returns `status = waiting_local_runner`, Codex should locate the local Python project and run `main.py` directly.
   - Prefer using `scripts/run-local-python.js` from this skill. Create a temporary runner input JSON outside git with `repoPath`, optional `installDir` / `pythonProjectDir` / `uvBin`, and `params`.
   - Build a base64-encoded JSON payload for each execution context.
   - Include at minimum: `serverUrl`, `token`, `executionId`, `testPlanId`, `testPlanCaseId`, `caseId`, `caseName`, `projectId`, `projectPlatform`, `task`, `isBatchMode`, `clientVersion`, `osInfo`.
   - `task` should be a MeterSphere-style JSON string: `{ "data": { "name", "moduleName", "functionalPriority", "prerequisite", "steps" } }`.
   - Use the case JSON already selected/saved in the workflow to construct `task`.
   - Prefer bundled uv when present:
     - macOS arm64: `PythonEnv/uv-runtime/darwin-arm64/uv`
     - macOS x64: `PythonEnv/uv-runtime/darwin-x64/uv`
     - Windows x64: `PythonEnv/uv-runtime/win-x64/uv.exe`
   - Otherwise use the bundled venv python under `PythonEnv/deepseek_chat_package_v2/.venv*`.
   - Run with cwd set to `PythonEnv/deepseek_chat_package_v2`.
   - Stream stdout/stderr into the Codex response updates when useful.
   - Continue polling logs/results when `task_id` exists; the local Python script should upload logs and results as it executes.
   - If `trigger_ai_execution` returns `status = configuration_required`, treat it as a legacy/local-MCP runtime setup response. Report the missing field and ask only for that field.
   - Do not interpret remote Linux paths as the user's local install path.

9. Poll logs and results.
   - If `task_id` exists, call `get_execution_logs(task_id, cursor)` every few seconds.
   - Keep and advance `next_cursor`.
   - Call `get_execution_result(task_id)` after each log poll.
   - Stop polling when status is no longer `running`, or after a reasonable timeout with a clear "still running" summary.

10. Defects and repair.
    - If defects are returned, summarize `defect_id`, `title`, `expected`, `actual`, `likely_cause`, and `suggested_fix_area`.
    - For repo code defects, inspect the suggested areas and make the smallest necessary fix.
    - Run local validation where possible.
    - Rerun `trigger_ai_execution` as regression and continue until passed or blocked.

## Reporting

Final response should include:

- Requirement source and concise requirement summary.
- Selected project name/id.
- Whether generated cases matched the requirement.
- Saved asset ids: `case_set_id`, `module_id`, `case_ids`, `test_plan_id`, `test_plan_case_ids`.
- Execution ids/status if created.
- Log/result/defect summary, or the exact runtime configuration blocker.

Never include a personal access token in the response.

## Codex Local Runner Pattern

For remote MCP servers, the expected `trigger_ai_execution` result is:

```text
status: waiting_local_runner
local_runner_required: true
next_action: run_local_testcopilot_python
```

Codex should then run the local TestCopilot bundled Python executor directly:

```bash
node ./skills/testcopilot/scripts/run-local-python.js /tmp/testcopilot-runner-input.json
```

Then poll:

```text
get_execution_logs(task_id, cursor)
get_execution_result(task_id)
```