命令行执行
使用 CLI
TestMax CLI 可在终端、定时任务或 CI 环境中执行自动化用例，与 GUI 共用模型、任务配置、测试用例和输出数据。默认采用无头模式，无需额外子命令。
运行前准备
CLI 与 GUI 使用同一套执行环境。首次运行前请完成以下检查。
- 准备完整程序。使用官方发布包，不要单独移动可执行文件；Windows 绿色包需保留同级的
node-runtime、node_modules和config；Linux 绿色包不含config/，需自行从桌面端拷贝或设置AITESTMAX_DATA。Linux 首次还需安装系统依赖libwebkit2gtk-4.1-0、libgtk-3-0（见下方 Linux 说明）。 - 完成模型与授权配置。先在 GUI 中配置模型 API Key，并确保当前网络环境能够完成授权校验。
-
复制 CLI Token。登录 TestMax 官网控制台，在左侧「账户」中打开「账号设置」，找到 CLI Token 区域，点击「复制 Token」。每次执行任务都需要通过
--token <令牌>传入；请勿分享或提交到代码仓库。
官网控制台 → 账号设置 → CLI Token → 复制 Token - 准备浏览器和用例。确认 Chrome for Testing 可用，将 Excel 用例放入数据目录下的“测试用例”目录，并在 GUI 任务配置中保存默认路径与级别。
Windows / macOS / Linux 调用
Windows
在 CMD 或 PowerShell 中进入完整解压后的软件目录。文件名以实际下载版本为准。
TestMax_版本号.exe --help
TestMax_版本号.exe --headless --token <登录令牌>
macOS
从终端调用 APP 内二进制。建议将数据目录显式设为当前用户可写目录，以便与 GUI 数据统一管理。
export AITESTMAX_DATA="$HOME/Library/Application Support/cn.testmax.ai"
/Applications/TestMax.app/Contents/MacOS/TestMax --help
Linux
解压绿色包后进入 TestMax 目录。包内不含 config/：请拷贝桌面端已调好的 config，或 export AITESTMAX_DATA=... 指向已有数据根。
二进制依赖系统库，Ubuntu / Debian 首次请安装：
sudo apt install -y libwebkit2gtk-4.1-0 libgtk-3-0
cd /path/to/TestMax
./TestMax --help
./TestMax --headless --token <登录令牌>
Windows 默认数据根为绿色包目录（含
config 与用例目录）。Linux 需自备 config 或设置 AITESTMAX_DATA。仅在需要把数据放到别处时覆盖该变量。参数说明
- --headed
- 有头执行，显示浏览器窗口，适合首次联调和排查问题。
- --headless
- 无头执行，不显示浏览器窗口；这是 CLI 的默认模式。
- --paths <列表>
- 覆盖本次执行的用例文件或文件夹。路径相对“测试用例”目录，多个值使用英文逗号分隔，例如
--paths 模块A.xlsx,回归/smoke。 - --levels <列表>
- 覆盖本次执行的级别过滤，多个值使用英文逗号分隔，例如
--levels P0,P1；可使用 GUI 中已有的级别值，如“未设置”。 - --token <令牌>
- 当前账号的登录令牌，执行任务必填。在官网控制台「账号设置」的 CLI Token 区域点击「复制 Token」获取（见上方截图说明）；请勿分享、提交到代码仓库或输出到公开日志。
- -V / --version
- 打印当前版本号后退出；查看版本无需提供 Token。
- -h / --help
- 打印 CLI 用法与参数说明后退出；查看帮助无需提供 Token。
--headed 与 --headless 同时出现时，以命令中最后出现的模式参数为准。CLI 不需要也不提供额外子命令。常用命令示例
以下以 Windows 发布文件名演示；macOS 和 Linux 只需替换命令开头的可执行文件路径。
# 按 GUI 已保存的任务配置执行（默认无头）
TestMax_版本号.exe --token <登录令牌>
# 显示浏览器执行
TestMax_版本号.exe --headed --token <登录令牌>
# 路径沿用 GUI 配置，只执行 P0
TestMax_版本号.exe --levels P0 --token <登录令牌>
# 级别沿用 GUI 配置，只执行指定 Excel
TestMax_版本号.exe --paths 订单模块.xlsx --token <登录令牌>
# 临时指定路径和级别，并显示浏览器
TestMax_版本号.exe --headed --paths 回归/smoke --levels P0,P1 --token <登录令牌>
参数如何覆盖 GUI task_config
CLI 读取数据目录中的 config/task_config.json。命令行参数只覆盖本次执行的对应字段，不会改写 GUI 保存的配置。
| 命令行参数 | 路径来源 | 级别来源 |
|---|---|---|
| 均不传 | task_config.json | task_config.json |
仅 --paths | 命令行 | task_config.json |
仅 --levels | task_config.json | 命令行 |
| 两者都传 | 命令行 | 命令行 |
输出目录与注意事项
执行日志与报告写入数据根目录下的“测试输出”，每次执行使用独立的时间戳子目录；终端会同步打印关键日志与统计。产物与 GUI 执行一致，通常包括网页报告、结果表格及失败截图。
--paths使用相对“测试用例”根目录的路径；过滤后没有可执行用例时，请检查“是否自动化”列及路径、级别条件。- 有头模式需要可用的桌面会话；无桌面的 Linux 服务器或 CI 环境请使用默认的无头模式。
- macOS APP 安装目录通常不可写，CLI 建议设置
AITESTMAX_DATA指向 GUI 的应用数据目录；Windows / Linux 绿色包直接在解压目录读写即可。 - 请妥善保护模型 API Key 和配置目录，不要将其输出到公开日志或提交到代码仓库。
- 进程退出状态用于反映 CLI 启动及执行器结果；请结合终端日志和“测试输出”中的报告判断具体用例结果。