scan-automation-project

扫描自动化项目

扫描项目并返回面向 QA 的清单：项目类型、语言、框架、现有测试，以及可用的 Testomat.io 访问权限。

仅进行浅层扫描。 不进行完整导入解析、不逐行解析，也不读取完整的测试实现。仅查看高层结构。

第 1 步：定位源代码

• 如果项目根目录中有非空的源代码文件夹或文件，请转到第 2 步。
• 如果未找到源代码文件，请停止并询问用户：

❓ No application source code detected (folder may be empty or missing).
Where is the source code?
1. Use local project from another folder (I will create a symlink)
2. Clone from Git repo
3. I don't know yet (stop here)

• 等待用户回复。
• 如果用户提供 Git 仓库或其他文件夹，请将其克隆或符号链接到 .testeiya/<name>/（使用源路径的基本名称；如果名称已被占用，则加上 extra- 前缀）。如果目标位置已存在，则不执行任何操作。

.testeiya/ 文件夹

所有持久化 QA 元数据都存放在项目根目录下的 .testeiya/ 中。

• <name>/：链接或克隆的外部项目，以其源名称命名。只读参考。
• requirements/：用户故事和验收标准（PDF、文档、图片）。
• docs/：功能说明、测试规划和策略文件。供人阅读的文字，绝不能是数据转储。
• manual-tests/：从 Testomat.io 获取的 Markdown 测试用例。
• auto-tests/：相关自动化（e2e）测试的引用。
• exploratory/：explorbot 设置。
• project-info.json：Testomat.io 报告的项目设置（如有缓存）。

规则：

• 这是一个点文件夹。文件搜索工具默认会跳过它：请使用 hidden:true 或显式的 .testeiya/ 路径前缀搜索。链接文件夹是符号链接；通配符搜索不会深入其中，因此请使用其自身的 .testeiya/<name>/ 前缀搜索。
• 它会从 Git 中排除自身：创建 .testeiya/ 时，也要创建 .testeiya/.gitignore，其中只包含一行 *。绝不要将 .testeiya/ 添加到仓库自身的 .gitignore 中：仓库级条目会使搜索工具看不到该文件夹，导致下一次扫描报告“没有手动测试”，而测试用例明明就在其中。

拉取数据的规则

需要将外部数据（手动测试用例、应用代码、来自其他仓库的 e2e 测试）拉取到此项目时：

此项目包含	将拉取的数据存放在
源代码（src/ 文件夹）或大型项目	.testeiya/…
仅有测试基础设施（如 tests/、playwright/、cypress/ 等 e2e 目录，但没有 src/）	已跟踪的文件夹（manual-tests/、e2e-tests/）
空项目／仅有手动测试	manual-tests/

检测逻辑：

1. 有 src/ 文件夹或属于单体仓库？→ 使用 .testeiya/
2. 有 e2e 测试目录（tests/、playwright/、cypress/、e2e/）？→ 使用已跟踪的文件夹（manual-tests/、e2e-tests/）
3. 否则 → 默认使用 manual-tests/

• 此规则仅适用于拉取的数据。技能生成且用户需要的输出（例如 coverage.*.yml、新建的 *.test.md 文件）应像往常一样放在仓库中。
• 对于没有手动测试的源代码仓库，此技能不会更改任何已跟踪文件：它只会创建自身被忽略的 .testeiya/ 目录。
• 只操作 .testeiya/ 和已跟踪的文件夹，绝不要将缓存放错位置而污染仓库。

步骤 2：项目分析

仅收集源文件路径。不要读取文件内容。

包括：

• 应用源文件。
• 视图／模板文件：.html/.htm、.vue、.svelte、.hbs/.handlebars、.ejs、.pug/.jade、.mustache、.liquid、.erb、.haml、.slim、.blade.php、.twig、.j2/.jinja/.jinja2、.cshtml/.razor、.jsp。它们属于应用源文件——覆盖率技能会通过这些文件映射 UI 变更。

排除：

• 依赖项、构建输出、覆盖率、报告、缓存、配置、锁定文件和环境文件。
• .gitignore 忽略的路径——但不包括 .testeiya/<name>/。在手动测试仓库中，应用代码位于其中；应将其作为源文件扫描。
• Testeiya 内部文件（例如 session-factory.ts、system-prompt.ts）。
• 如有疑问，就排除。

根据文件列表：

• 将项目类型归类为以下一种：
  • source：应用源代码。绝不要更改；将其用于项目发现。
  • e2e：测试自动化项目（e2e 目录、测试框架配置，应用源代码很少或没有）。可以为其编写测试。
  • manual：空项目，或主要由 *.test.md 文件组成。测试用例应放在项目本身中。
• 检测语言和框架。收集一个包含所有应用及测试框架的 frameworks 列表。
• 从项目配置文件（package.json、Cargo.toml、pom.xml 等）提取项目名称；若找不到，则使用根目录名称。
• 根据源文件数量评估复杂度：

文件数量	复杂度
1-30	small
31-150	moderate
151-500	large
500+	very-large

步骤 3：测试清单

检测现有测试，包括自动化测试和手动测试。保持浅层扫描。

手动测试

*.test.md 文件是一个测试套件。文件中的每个测试都是一个 `` 块，后面跟着一个 #/## 标题（测试名称）。块中的 type: 字段表示测试类型：

• type: manual：手动测试用例，以 Markdown 编写并在此维护。
• type: automated：自动化测试的引用（见下文）。
• 完全没有 type: 行：视为手动测试。这种情况很常见，因此绝不要通过搜索 type: manual 来统计手动测试数量；这样会导致统计结果偏低。

在回答任何有关项目范围、覆盖率或进度的问题之前，先确认测试数量。直接从文件中读取数量；这与 Testomat.io 的解析方式一致。find . 也会扫描 .testeiya/manual-tests/，因此拉取后重新运行时会找到缓存用例，而不是报告“没有手动测试”：

# one line per suite or test: SUITE <title>, or <type> <title>
find . -name "*.test.md" -exec awk '
  /^/ { in_block=0; expect=1; next }
  expect && /^#+[[:space:]]+/ {
    title=$0; sub(/^#+[[:space:]]+/, "", title)
    if (kind == "SUITE") printf "SUITE: %s\n", title
    else                 printf "|- [%s] %s\n", kind, title
    expect=0
  }
' {} +

将输出通过管道传给 grep -c '\[manual\]' 或 grep -c '\[automated\]'，即可统计相应类型的数量。

• 如果所有 .test.md 文件都位于 .testeiya/manual-tests/ 下，请在清单中说明：这些文件来自 Testomat.io，而非此仓库。
• 如果源码检出中没有 *.test.md 文件，则没有可统计的内容。请如实说明，不要估算。

自动化测试

• 根据配置文件（jest.config.*、playwright.config.*、vitest.config.*、pytest.ini、pom.xml 等）、项目依赖项和测试文件模式（*.test.*、*.spec.*、*_test.*）检测测试框架。
• 对每个框架：确定其测试文件模式，并统计匹配的文件数量。
• 单元测试和集成测试属于清单范围，不属于 QA 范围：请记录它们，但注明 e2e 和验收测试套件才是 QA 工作的目标。

自动化引用

*.test.md 中的 type: automated 条目是引用，不是可运行的代码。它们由 check-tests pull --export-automated 导入，该命令会将 Testomat.io 记录的自动化测试导出为 Markdown。实际实现位于另一个仓库，即自动化项目；通常不是当前仓库。

• 不要因为在这里找到了自动化测试的引用，就声称自己运行过该测试。这里的内容无法执行。
• 不要编辑引用的 Markdown 来更改测试行为。代码位于其他地方，编辑会在下次拉取时被覆盖，推送还可能覆盖 TMS 数据。请改为在自动化仓库中找到实际测试。
• 要实际运行这些测试，请使用 CI 配置（步骤 4）：如果项目配置了 CI 配置文件，可以通过 Testomat.io 触发运行。
• 它们仍然是很有价值的背景信息：可以告诉你哪些内容已经自动化、哪些仍需手动测试，而这正是识别覆盖率缺口和自动化候选项所需的信息。

步骤 4：Testomat.io 访问方式

记录如何在当前会话中访问 Testomat.io。请检查，不要想当然：

• **令牌：**环境变量（或 .env）中的 TESTOMATIO。有了它，npx check-tests 就可以拉取和推送测试用例，REST API 也会在 $TESTOMATIO_URL/api/v2 下响应。
• **MCP：**存在 Testomat.io MCP 工具（前缀为 testomatio- 的工具、tests_list 和 runs_list 等直接工具，或一个可搜索并调用操作的 mcp 工具）。MCP 除令牌外还需要 TESTOMATIO_PROJECT_ID；仅有令牌无法识别项目。设置方法见 testomatio-mcp 技能。
• **项目设置：**如果存在 .testeiya/project-info.json，其中包含框架、语言、环境、标签、标记和 CI 配置文件（可通过这些配置文件触发运行）。

如果已配置 Testomat.io 令牌，绝不要向用户索要。被测应用所需的密钥是另一回事；缺少这类密钥会阻止测试运行。

不同问题应查询的来源

问题涉及	首要操作
测试内容：步骤、Gherkin、描述、文件路径、标记	在项目中使用 read、find、grep
测试套件层级、结构、文件清单	使用 ls、find
单个测试的元数据：优先级、状态标志、标签	查看文件；如果没有，从 Testomat.io 获取测试
测试运行、测试运行实例、计划、标签、问题、分析	使用 Testomat.io（MCP 或 REST）；这些内容不在文件中
创建或更新测试或测试套件	编辑 Markdown 文件，然后运行 npx check-tests push（参见 sync-test-cases-with-tms）
在 CI 上启动自动化或混合运行	npx -y @testomatio/reporter@latest run --remote <profile>；如果未配置 CI 配置文件，则报错
在本地运行自动化测试	使用本地测试运行器，并附加 Testomat.io reporter

Testomat.io 中的状态和计数是实时的。运行可随时改变这些数据，因此，最新的查询结果优先于对话中较早出现的数字。

第 5 步：输出

直接返回一份结构化的 Markdown 结果。不要保存到文件。

# Project Overview

- **Project Name:** acme-web-app
- **Description:** A React-based customer dashboard with an Express API.
- **Project Type:** source
- **Languages:** TypeScript, SQL
- **Frameworks:** React, Express, Jest, Playwright
- **Complexity:** small (12 files)

## Test Inventory

- **Automated Tests:** 10 files (Playwright)
- **Manual Tests:** 37 cases (`.testeiya/manual-tests/`, pulled from Testomat.io)
- **Automated References:** 12 (implementation lives in another repository)

### Manual Tests (20 of 37 shown)

- SUITE: Authentication
  |- User can login
  |- User can reset password
- SUITE: Billing
  |- User can view invoice
  ...and 17 more

### Automated Tests (10 of 10 shown)

- home.page.spec.ts
...

## Testomat.io

- **Token:** set (`TESTOMATIO`)
- **MCP:** available (`testomatio-*` tools)
- **Project settings:** `.testeiya/project-info.json`, framework playwright, CI profiles: "e2e" (github)

字段规则：

• **描述：**仅根据检测到的源代码和文件夹结构撰写 1-2 句话（如果合适，请包含所属领域）。
• **项目类型：**填写 source、e2e 或 manual。
• **复杂度：**填写 small、moderate、large 或 very-large，并附上文件数量。
• **手动测试：**以纯文本字符串保留层级结构——SUITE 项目作为父级项目符号，测试标题（|-）作为嵌套子项。说明测试所在位置。
• **自动化测试：**列出检测到的测试文件。
• **Testomat.io：**每种访问路径单独占一行，标注 available 或 not available；仅在没有任何访问路径时省略此部分，并说明项目未连接。
• 所有值都必须来自可观察到的文件和工具。不要猜测缺失数据，也不要添加上述字段之外的字段。

部分规则：

• 如果步骤 3 未发现测试，则省略 ## Test Inventory，并注明项目不包含测试；# Project Overview 部分仍可用于后续步骤。
• 如果缺少一种测试类型，请用引用块注明，例如：> 项目中未找到手动测试（`.test.md`）。

测试列表截断规则：

• 每个列表最多显示前 20 项，按原文件顺序排列。
• 在标题中标明截断情况（（已显示 20 项，共 37 项）），并注明 ...and N more。
• 不要输出超出此数量的完整测试列表。