@rbxts/test-cloud-testez

Roblox Cloud TestEZ 测试工具

在 Roblox Cloud 环境中运行 TestEZ 测试的轻量级工具 - 内置 TestEZ，无需外部依赖。

🎯 核心特性

✅ 内置 TestEZ - 无需 Wally 或 @rbxts/testez，TestEZ 源码内置在 TestService/test-cloud-testez/testez/ ✅ 改进的错误处理 - require() 错误显示详细的位置信息 (→ Failed at: <location>) ✅ 零外部测试依赖 - 仅使用 Node.js 内置模块 ✅ 快速执行 - ~8-15 秒完整测试流程 ✅ 详细报告 - YAML 格式，易于阅读和版本控制 ✅ 自动测试发现 - 递归扫描 .spec 文件 ✅ 支持双项目 - TypeScript 和 Lua 项目通用

📦 安装

npm install test-cloud-testez
# 或
pnpm add test-cloud-testez

环境配置

创建 .env.roblox 文件:

ROBLOX_API_KEY=<your-api-key>      # Roblox Open Cloud API Key
UNIVERSE_ID=<universe-id>           # Universe ID
TEST_PLACE_ID=<place-id>            # Test Place ID

# 可选：代理配置
HTTPS_PROXY=http://proxy.example.com:8080

TestEZ 位置

TestEZ 源码内置在项目中: TestService/test-cloud-testez/testez/

• ✅ 无需 wally install
• ✅ 无需 @rbxts/testez npm 包
• ✅ 包含自定义改进（require() 错误处理）

🚀 快速开始

运行所有测试

npm test

运行特定测试

npm test -- StringUtils

详细输出模式

npm test -- -V
# 或更详细
npm test -- -VV

自定义选项

# 跳过构建步骤
npm test -- --skip-build

# 自定义超时时间（秒）
npm test -- -t 180

# 指定测试根路径
npm test -- --roots ServerScriptService/Server

# 显示帮助信息
npm test -- -h

📋 命令选项

选项	描述	默认值
-V, --verbose	详细输出模式（可多次使用：-VV 最详细）	-
-t, --timeout <sec>	任务执行超时时间（秒）	120
-r, --rbxl <path>	指定 rbxl 文件路径	test-place.rbxl
--roots <path>	测试根路径，用 ; 分隔	ServerScriptService;ReplicatedStorage
--glob <match>	在根路径中匹配测试文件	-
--skip-build	跳过 Rojo 构建步骤	false
-h, --help	显示帮助信息	-
-v, --version	显示版本信息	-

📝 测试结果

测试结果保存在 .test-result/ 目录:

• YAML 格式 - 易于人工阅读和 Git diff
• 自动清理 - 保留最近 2 次结果
• 堆栈跟踪过滤 - 自动过滤 TestEZ 内部代码，只显示用户代码
• 捕获输出 - 包含所有 print() 和 warn() 输出（使用 LogService）

结果文件结构

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

💡 编写测试

基本测试结构

-- 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

打印输出

在云测试环境中，可以直接使用普通的 print() 和 warn() 函数:

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() 语句，避免影响性能。

TestEZ 可用匹配器

TestEZ 只提供 5 个核心匹配器:

• .to.equal(value) - 检查值是否相等
• .to.be.near(value, limit?) - 检查数值是否接近（浮点数）
• .to.throw(msg?) - 检查函数是否抛出错误
• .to.be.a(type) - 检查值类型
• .to.be.ok() - 检查值是否为 truthy

数值比较（没有 .greaterThan()）:

expect(score > 100).to.equal(true)   -- ✅ 大于
expect(level < 10).to.equal(true)    -- ✅ 小于
expect(value >= 0).to.equal(true)    -- ✅ 大于等于

🔧 改进的功能

1. 改进的 require() 错误处理

当测试中的 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

2. 内置 TestEZ

TestEZ 源码内置在 TestService/test-cloud-testez/testez/，带来以下优势:

• ✅ 完全控制 - 可以自由修改 TestEZ 源码
• ✅ 无外部依赖 - 不需要 Wally 或 @rbxts/testez
• ✅ 简化构建 - 一个 npm run build 即可
• ✅ 保留修改 - 包含我们的自定义改进
• ✅ 版本固定 - 不会因包更新而意外破坏

详见: TESTEZ_MIGRATION.md

❓ 常见问题

Q: TestEZ 在哪里？需要安装吗？

A: TestEZ 源码内置在 TestService/test-cloud-testez/testez/，无需安装。不需要 Wally 或 @rbxts/testez。

Q: 如何在测试中打印调试信息？

A: 直接使用 print() 和 warn() 即可，输出会被自动捕获（使用 LogService.MessageOut）。调试完成后立即移除。

Q: require() 错误信息不够详细？

A: 已修复！现在会显示具体的错误位置，如 → Failed at: ServerScriptService.Server.MyModule:42

Q: 测试结果保存在哪里？

A: .test-result/ 目录，YAML 格式，自动保留最近 2 次结果。

Q: 如何配置测试路径？

A: 使用 --roots 参数：npm test -- --roots ServerScriptService/Server

Q: 如何过滤测试文件？

A: 传递测试名称作为参数：npm test -- MyModule（不区分大小写）

Q: 如何调试超时问题？

A: 使用 -t 参数增加超时时间：npm test -- -t 300（300 秒）

Q: 支持哪些项目类型？

A: 支持 TypeScript（roblox-ts）和 Lua 项目。自动检测项目类型。

📚 文档

• TESTEZ_REQUIRE_ERROR_FIX.md - require() 错误处理改进
• TESTEZ_MIGRATION.md - TestEZ 迁移文档（从 Wally 到内置）
• CLAUDE.md - Claude Code 使用说明

🔗 相关资源

• TestEZ 官方文档
• Luau 语言参考
• Roblox Open Cloud API
• Rojo 文档

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

由 White Dragon 开发 | Version 0.3.6