English | Русский | 中文

testblox-runner

TestBlox 的 CLI 与 CI 运行器。 无需桌面应用，即可在终端、GitLab CI 或 GitHub Actions 中运行测试。使用 Playwright 的报告器输出 HTML 与控制台结果。

为什么需要 testblox-runner？

TestBlox 是用于创建和编辑测试的桌面应用。若要在 CI（GitLab、GitHub Actions）或命令行中运行同一套测试，需要无头运行器。testblox-runner 提供：相同的工作区（.testblox/、tests/、pages/）、相同的执行引擎，以及 Playwright 报告器和管道可用的标准 JUnit/JSON。

功能

| 功能 | 说明 | |------|------| | CLI | 运行全部测试或按 ID 运行单个测试；可选并发与工作区路径。 | | Playwright 报告器 | 使用 --reporter=html、list、line 或 dot，获得与 Playwright Test 相同的 HTML 与控制台输出。 | | JUnit / JSON | CI 常用格式；GitLab 与 GitHub 可解析 JUnit 显示测试结果。 | | GitHub Actions | 仓库内提供示例 workflow；安装运行器、Chromium、执行测试、上传报告。 | | GitLab CI | 提供带 JUnit 产物与报告的示例 job。 |

要求

• Node.js 18+
• TestBlox 工作区（包含 .testblox/、tests/、pages/ 的项目目录）

安装

方式一：从 npm 安装（发布后）

npm install -g testblox-runner
# 或作为项目开发依赖：
npm install --save-dev testblox-runner

方式二：从源码安装

git clone https://github.com/arslan-ahmetjanov/testblox-runner.git
cd testblox-runner
npm ci

在与 testblox 同仓库的本地开发中，使用 npm install 以使用依赖 testblox: "file:../testblox"。发布到 npm 前，请在 package.json 中将其改为 "testblox": "^1.0.0"。

快速开始

在 TestBlox 工作区根目录（包含 .testblox/ 和 tests/ 的目录）下运行。运行前，runner 会从工作区根目录加载 .env 文件（若存在），因此可将测试变量与密钥置于其中，或在 CI 中通过环境变量设置。

# 运行全部测试
testblox-runner --all

# Playwright 风格 HTML 报告
testblox-runner --all --reporter html

# CI 用 JUnit
testblox-runner --all --reporter junit --output report.xml

浏览器（browser.json）

可选：在 工作区根目录（与 .testblox/ 同级）放置 browser.json。CLI 与 Playwright 报告模式启动浏览器时会读取该文件。

| 字段 | 说明 | |--------|-------------| | browser | chromium、firefox、webkit 或 custom | | executablePath | 当 browser 为 custom 时，填写浏览器可执行文件的绝对路径。JSON 中 Windows 路径的反斜杠需写成 \\。 |

示例：Yandex 浏览器（Chromium 内核；实际安装路径可能不同）：

{
  "browser": "custom",
  "executablePath": "C:\\Users\\You\\AppData\\Local\\Yandex\\YandexBrowser\\Application\\browser.exe"
}

使用 Playwright 自带的 Chromium（以及 Firefox/WebKit）时需执行 npx playwright install（或只安装所需浏览器）。使用 custom 时则启动您指定的可执行文件，而非 Playwright 下载的浏览器。

选项

| 选项 | 说明 | |--------|-------------| | --workspace <path> | TestBlox 工作区路径（默认：当前目录） | | --test <id> | 按 ID 运行单个测试 | | --all | 运行工作区内全部测试 | | --reporter <name> | default | junit | json | html | list | line | dot（html/list/line/dot 即 Playwright） | | --output <file> | 将报告写入文件（如 report.xml、results.json） | | --concurrency <n> | 最多 n 个测试并行（1–8，默认 1） | | --headless | 无头模式运行浏览器（默认） | | --no-headless | 显示浏览器窗口 | | --screenshot-on-failure | 仅在失败步骤截图 | | --help, -h | 显示帮助 |

退出码： 0 表示全部通过；1 表示有失败或错误（如非工作区、测试未找到）。

GitHub Actions

仓库内示例 workflow：.github/workflows/testblox.yml。可复制到项目的 .github/workflows/。Job 会拉取代码、安装 Node 与 testblox-runner、安装 Playwright Chromium、执行 testblox-runner --all --reporter junit --output testblox-report.xml 并上传产物。

GitLab CI

testblox:
  image: node:20-bookworm
  before_script:
    - npm install -g testblox-runner
    - npx playwright install chromium
  script:
    - testblox-runner --all --reporter junit --output testblox-report.xml
  artifacts:
    when: always
    reports:
      junit: testblox-report.xml
    paths:
      - testblox-report.xml

参与贡献

欢迎提交问题、建议、文档或代码修改。请开 issue 或 pull request。

作者与动机

作者： Arslan Ahmetjanov（Арслан Ахметжанов）——面向手工与自动化测试的 AI 方案开发者。

testblox-runner 属于 TestBlox 生态：同一套测试可在桌面应用、终端或 CI 中运行，共享同一工作区与基于 Playwright 的执行。

许可证

MIT