qa-e2e-tests-reporting

Testomat.io 报告器设置

在自动化项目中安装并配置 Testomat.io 报告器，然后将测试结果推送到 Testomat.io TMS。

步骤 1：检测语言和框架

• 从项目清单文件（package.json、pyproject.toml/requirements.txt、pom.xml/build.gradle、*.csproj、composer.json、Gemfile）检测语言。
• 从其配置文件检测框架：playwright.config.*、codecept.conf.js、wdio.conf.*、jest.config.*、.mocharc.*、pytest.ini/conftest.py、*.robot/robot.toml、testng.xml/pom.xml 中的 JUnit 依赖。
• 如果技术栈没有原生报告器（C#、PHP、Ruby、Go 等），请使用 JUnit XML 导入（步骤 4）。

步骤 2：配置凭据

• 检查 .env 中是否有 TESTOMATIO API 密钥。如果存在，请使用该密钥。
• 如果缺少，请在 .env 中添加占位行：

TESTOMATIO=tstmt_xxxxx

• 请用户自行将占位内容替换为其“Project Reporting API key”——绝不要要求用户在聊天中粘贴密钥。

给用户的消息：

✅ Added `TESTOMATIO=tstmt_xxxxx` placeholder to .env

To activate reporting:
1. Go to Testomat.io → your project → Settings → Project
   (https://app.testomat.io/projects/<project-id>/settings/project)
2. Copy "Project Reporting API key"
3. Replace `tstmt_xxxxx` in .env with your actual key
4. Run tests: TESTOMATIO=tstmt_xxxxx npx <test-command>

步骤 3：安装并配置报告器

选择与检测到的语言和框架对应的部分。

JavaScript / TypeScript

使用 @testomatio/reporter：

npm install @testomatio/reporter --save-dev

Playwright — playwright.config.ts 或 playwright.config.js：

reporter: [
  ['@testomatio/reporter/playwright'],
  // other reporters...
],

CodeceptJS — codecept.conf.js 或 codecept.config.js：

plugins: {
  testomatio: {
    enabled: true,
    require: '@testomatio/reporter/codecept',
  }
}

WebdriverIO — wdio.conf.js：

import testomatio from '@testomatio/reporter/webdriver';

exports.config = {
  // ...
  reporters: [
    [testomatio, { apiKey: process.env.TESTOMATIO }],
  ],
};

Jest — jest.config.js 或 jest.config.ts：

module.exports = {
  reporters: ['default', ['@testomatio/reporter/jest', { apiKey: process.env.TESTOMATIO }]],
};

Mocha — 使用 CLI 标志运行：

mocha --reporter @testomatio/reporter/mocha --reporter-options apiKey=tstmt_xxx

• 运行命令和更多配置选项：./references/TESTOMATIO_REPORTERS_CONFIG.md
• 文档：Testomat.io NodeJS Frameworks

Python

pytest 使用 pytestomatio，Robot Framework 使用 robot-framework-reporter。

• 如果 Python 2.x 和 3.x 共存，请使用 pip3。

pytest：

pip install pytestomatio

# Run and report tests
pytest --testomatio report

Robot Framework：

pip install robot-framework-reporter

# Run and report tests
robot --listener Testomatio.Report path/to/tests

文档：Testomat.io Python Reporting

Java（JUnit、TestNG、Cucumber、Karate）

使用 io.testomat Java 报告器。

• 请用户在运行测试前设置 API 密钥，然后确认密钥已设置且以 tstmt_ 开头：

export TESTOMATIO=<tstmt_api_key>

• 添加所用框架对应的依赖：

<dependency>
  <groupId>io.testomat</groupId>
  <artifactId>java-reporter-junit</artifactId>
  <version>{LATEST_STABLE_VERSION}</version>
</dependency>

Artifact ID：java-reporter-junit、java-reporter-testng、java-reporter-cucumber、java-reporter-karate。

• 运行测试：

mvn clean test

• 在输出中查找运行 ID。如果找到，请显示链接：

View results: https://app.testomat.io/projects/{project-id}/runs/{run-id}

文档：Testomat.io Java/JUnit Reporting

步骤 4：将自动化测试导入 Testomat.io TMS

将测试源代码导入 Testomat.io，以查看测试结构并启用代码库与 TMS 的同步。

文档：Testomat.io Import Overview

JavaScript / TypeScript

使用 check-tests CLI：

npx check-tests@latest <framework> "<glob-pattern>" [options]

框架	示例
Playwright	npx check-tests@latest Playwright "tests/**/*.spec.js"
CodeceptJS	npx check-tests@latest CodeceptJS "tests/**_test.js"
Cypress	npx check-tests@latest cypress "cypress/e2e/**/*.js"
Jest	npx check-tests@latest Jest "tests/**/*.test.js"
Mocha	npx check-tests@latest mocha "test/**/*_test.js"
WebdriverIO	npx check-tests@latest webdriverio "test/**/*.js"

选项：

• --typescript — 用于 TypeScript 项目：npx check-tests@latest Playwright "tests/**/*.spec.ts" --typescript
• --update-ids — 同步并在源代码中自动分配测试 ID：npx check-tests@latest CodeceptJS "tests/**_test.js" --update-ids

Python

pytest — 将测试与 Testomat.io 同步：

pytest --testomatio sync

Robot Framework — 导入测试：

robot --listener Testomatio.Import path/to/tests

Java（JUnit、TestNG）

使用 testomatio.jar CLI。每次执行测试后都要重新运行。

• 仅从项目根目录运行：

cd <project-root>

export TESTOMATIO=tstmt_xxxxx && \
curl -L -O https://github.com/testomatio/java-check-tests/releases/latest/download/testomatio.jar && \
java -jar testomatio.jar sync

命令：

• import — 将测试代码导入 Testomat.io（无需 API 密钥即可试运行）。
• clean-ids — 导入不含系统 ID 的测试。
• sync — 导入测试并将 ID 写入源代码（别名：update-ids）。

JUnit XML（C#、PHP、Ruby、Go 等）

对于没有原生报告器的技术栈，请生成 JUnit XML 报告，然后导入。

• NUnit（C#）：dotnet test --logger:"trx;LogFileName=results.xml" — 如有需要，转换为 JUnit XML。
• PHPUnit（PHP）：./vendor/bin/phpunit --log-junit=results.xml
• RSpec（Ruby）：rspec --format json --out results.json — 然后转换为 JUnit XML。

导入到 Testomat.io：

npx check-tests@latest junit "path/to/results.xml"

# Multiple XML files
npx check-tests@latest junit "results/*.xml"

步骤 5：验证设置

启用报告器后运行测试：

TESTOMATIO=tstmt_xxxxx npx <your-test-command>

通过 Testomat.io MCP（首选，若已启用）

• 运行后，通过 MCP 获取最新运行记录，确认已收到数据。
• 成功指标：日志中出现新的运行 ID；运行状态显示符合预期的通过/失败结果；可通过其 ID 检索到该运行记录。
• 可通过 MCP 获取新的运行记录后，即表示设置完成。
• MCP 工具：Testomat.io MCP 运行管理

调试模式（备选）

• 在本地捕获报告器输出，仅运行 1-2 个测试，以便在发送前验证是否正确生成数据：

DEBUG=@testomatio/reporter:pipe:testomatio npx <your-test-command>

• 查看执行日志，确认报告器已启用并完成配置。
• 文档：Testomat.io 调试日志

步骤 6：配置制品（仅在明确要求时）

将截图、视频、跟踪记录和日志存储在与测试结果配套的 S3 兼容存储中。

• 仅当用户明确要求配置制品（或提到保存截图、视频、跟踪记录、日志）时，才执行此步骤。
• 前提条件：已成功执行第一份测试报告。
• 检查 .env 中是否已有 S3 凭据（S3_ACCESS_KEY_ID、S3_BUCKET、S3_REGION）。如果有，跳至验证。

创建 S3 存储桶（如有需要）

• 建议：每个项目使用一个存储桶。
• 根据官方文档，引导用户使用其服务提供商：

提供商	链接
AWS S3	https://s3.console.aws.amazon.com/s3
DigitalOcean	https://cloud.digitalocean.com/spaces
Google Cloud Storage	https://console.cloud.google.com/storage
Cloudflare R2	https://dash.cloudflare.com/
Minio	自托管或云实例

• 用户从服务提供商处获取 Access Key ID 和 Secret Access Key。

选项 A：Testomat.io UI（推荐）

• Agent 无法访问 Testomat.io 项目设置，用户需手动配置：
  1. 打开 https://app.testomat.io/projects/<project-id>/settings/artifacts
  2. 启用“Share credentials”开关。
  3. 输入 Access Key ID、Secret Access Key、存储桶名称、区域和端点（仅非 AWS 服务提供商需要填写端点）。

选项 B：环境变量

将 S3 凭据添加到 .env 或 CI 流水线中：

# Required for all providers
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_BUCKET=your_bucket_name
S3_REGION=us-west-1

# Optional: for non-AWS providers (DigitalOcean, Minio, Cloudflare R2, GCS)
S3_ENDPOINT=https://your-endpoint-url

# Optional: private access mode (recommended)
TESTOMATIO_PRIVATE_ARTIFACTS=1

Cloudflare R2 示例：

S3_ACCESS_KEY_ID=xxx
S3_SECRET_ACCESS_KEY=xxx
S3_BUCKET=testomatio-artifacts
S3_REGION=auto
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_FORCE_PATH_STYLE=true

• 禁用上传：TESTOMATIO_DISABLE_ARTIFACTS=1
• 服务提供商示例（AWS、DigitalOcean、Minio、GCS）：./references/TESTOMATIO_ARTIFACTS.md
• 更多选项：Testomat.io 制品

验证制品

• 运行会生成截图、视频或跟踪记录的测试：TESTOMATIO=tstmt_xxxxx npx <your-test-command>
• 请用户打开 https://app.testomat.io/projects/<project-id>/runs，并点击一个带有制品的测试（失败的测试通常会有截图）。
• 成功标志：制品会显示在测试结果中（“Artifacts”部分或附件图标），且可点击；Playwright 跟踪记录可在跟踪查看器中打开。

References

Description	Link
Getting started	https://docs.testomat.io/getting-started/
Reporter configuration	https://docs.testomat.io/test-reporting/frameworks/
Framework config snippets	./references/TESTOMATIO_REPORTERS_CONFIG.md
Python test reporting	https://docs.testomat.io/test-reporting/python/
Python Robot Framework	https://github.com/testomatio/robot-framework-reporter/blob/master/README.md
Java/JUnit reporting	https://docs.testomat.io/test-reporting/junit/
HTML pipe	./references/TESTOMATIO_HTML_REPORT.md
Debug pipe	TESTOMATIO_DEBUG=1 <test-command>
Artifacts (S3)	./references/TESTOMATIO_ARTIFACTS.md