Lightweight testing tool for running TestEZ tests in Roblox Cloud and Studio environments with direct API calls, supporting both TypeScript and Lua projects
npm install @rbxts/test-cloud-testezTestService/test-cloud-testez/testez/
→ Failed at: )
.spec 文件
bash
npm install test-cloud-testez
或
pnpm add test-cloud-testez
`
$3
创建 .env.roblox 文件:
`bash
ROBLOX_API_KEY= # Roblox Open Cloud API Key
UNIVERSE_ID= # Universe ID
TEST_PLACE_ID= # Test Place ID
可选：代理配置
HTTPS_PROXY=http://proxy.example.com:8080
`
$3
TestEZ 源码内置在项目中: TestService/test-cloud-testez/testez/
- ✅ 无需 wally install
- ✅ 无需 @rbxts/testez npm 包
- ✅ 包含自定义改进（require() 错误处理）
🚀 快速开始
$3
`bash
npm test
`
$3
`bash
npm test -- StringUtils
`
$3
`bash
npm test -- -V
或更详细
npm test -- -VV
`
$3
`bash
跳过构建步骤
npm test -- --skip-build
自定义超时时间（秒）
npm test -- -t 180
指定测试根路径
npm test -- --roots ServerScriptService/Server
显示帮助信息
npm test -- -h
`
📋 命令选项
| 选项 | 描述 | 默认值 |
|------|------|--------|
| -V, --verbose | 详细输出模式（可多次使用：-VV 最详细） | - |
| -t, --timeout | 任务执行超时时间（秒） | 120 |
| -r, --rbxl | 指定 rbxl 文件路径 | test-place.rbxl |
| --roots | 测试根路径，用 ; 分隔 | ServerScriptService;ReplicatedStorage |
| --glob | 在根路径中匹配测试文件 | - |
| --skip-build | 跳过 Rojo 构建步骤 | false |
| -h, --help | 显示帮助信息 | - |
| -v, --version | 显示版本信息 | - |
📝 测试结果
测试结果保存在 .test-result/ 目录:
- YAML 格式 - 易于人工阅读和 Git diff
- 自动清理 - 保留最近 2 次结果
- 堆栈跟踪过滤 - 自动过滤 TestEZ 内部代码，只显示用户代码
- 捕获输出 - 包含所有 print() 和 warn() 输出（使用 LogService）
$3
`yaml
timestamp: '2025-11-18T04:00:00.000Z'
success: true
totalTests: 58
passed: 58
failed: 0
skipped: 0
errors: []
printMessages:
- message: '🧪 Starting tests...'
type: MessageOutput
timestamp: 1763464834
- message: 'Testing something'
type: MessageOutput
timestamp: 1763464834
- message: 'This is a warning'
type: MessageWarning
timestamp: 1763464834
`
💡 编写测试
$3
`lua
-- MyModule.spec.lua
return function()
local MyModule = require(script.Parent.MyModule)
describe("MyModule", function()
it("should do something", function()
local result = MyModule.doSomething()
expect(result).to.equal(expected)
end)
end)
end
`
$3
在云测试环境中，可以直接使用普通的 print() 和 warn() 函数:
`lua
return function()
print("🧪 Starting tests...") -- ✅ 会被自动捕获
describe("MyModule", function()
it("should work", function()
print("Testing something") -- ✅ 会被自动捕获
warn("This is a warning") -- ✅ warn 也会被捕获
expect(true).to.equal(true)
end)
end)
print("✅ Tests completed")
end
`
捕获机制: 使用 LogService.MessageOut 事件自动捕获所有日志消息。
注意: 调试完成后立即移除 print() 语句，避免影响性能。
$3
TestEZ 只提供 5 个核心匹配器:
1. .to.equal(value) - 检查值是否相等
2. .to.be.near(value, limit?) - 检查数值是否接近（浮点数）
3. .to.throw(msg?) - 检查函数是否抛出错误
4. .to.be.a(type) - 检查值类型
5. .to.be.ok() - 检查值是否为 truthy
数值比较（没有 .greaterThan()）:
`lua
expect(score > 100).to.equal(true) -- ✅ 大于
expect(level < 10).to.equal(true) -- ✅ 小于
expect(value >= 0).to.equal(true) -- ✅ 大于等于
`
🔧 改进的功能
$3
当测试中的 require() 发生错误时，会显示详细的位置信息:
改进前:
`
Requested module experienced an error while loading
ServerScriptService.Server.MyTest.spec:42
`
改进后:
`
Requested module experienced an error while loading
→ Failed at: ServerScriptService.Server.MyTest.spec:42
ServerScriptService.Server.MyTest.spec:42
TaskScript:361
`
详见: TESTEZ_REQUIRE_ERROR_FIX.md
$3
TestEZ 源码内置在 TestService/test-cloud-testez/testez/，带来以下优势:
- ✅ 完全控制 - 可以自由修改 TestEZ 源码
- ✅ 无外部依赖 - 不需要 Wally 或 @rbxts/testez
- ✅ 简化构建 - 一个 npm run build 即可
- ✅ 保留修改 - 包含我们的自定义改进
- ✅ 版本固定 - 不会因包更新而意外破坏
详见: TESTEZ_MIGRATION.md
❓ 常见问题
$3
A: TestEZ 源码内置在 TestService/test-cloud-testez/testez/，无需安装。不需要 Wally 或 @rbxts/testez。
$3
A: 直接使用 print() 和 warn() 即可，输出会被自动捕获（使用 LogService.MessageOut）。调试完成后立即移除。
$3
A: 已修复！现在会显示具体的错误位置，如 → Failed at: ServerScriptService.Server.MyModule:42
$3
A: .test-result/ 目录，YAML 格式，自动保留最近 2 次结果。
$3
A: 使用 --roots 参数：npm test -- --roots ServerScriptService/Server
$3
A: 传递测试名称作为参数：npm test -- MyModule（不区分大小写）
$3
A: 使用 -t 参数增加超时时间：npm test -- -t 300`（300 秒）