跳转到内容
Wippy

测试

测试

Section titled “测试”

使用 wippy/test 框架为您的 Lua 代码编写和运行测试 — 这是一个 BDD 风格的运行器，提供断言、生命周期钩子和模拟功能，通过 wippy run test 命令执行。

您将构建什么

Section titled “您将构建什么”

一个小型库和覆盖它的测试套件：

  1. 一个包含 add 和 div 函数的 calc 库。
  2. 一个测试入口，用于描述用例、断言行为并跳过一个待定用例。
  3. 通过 wippy run test 进行一次全绿的测试运行。

先决条件

Section titled “先决条件”

  • 一个 Wippy 项目（克隆 app-template，或在空目录中执行 wippy init）。

  • 已安装测试框架和终端宿主：

    Terminal window
    wippy add wippy/test
    wippy add wippy/terminal
    wippy install

    运行器会渲染一个实时的终端 UI，因此 wippy/terminal 必须与 wippy/test 一同安装。

被测代码

Section titled “被测代码”
-- src/calc.lua
local function add(a, b)
    return a + b
end


local function div(a, b)
    if b == 0 then
        return nil, "division by zero"
    end
    return a / b
end


return { add = add, div = div }

测试

Section titled “测试”

测试是一个普通的 function.lua 入口，标记了 meta.type: test。它的方法返回 test.run_cases(...) 产生的值，由运行器调用：

-- src/calc_test.lua
local test = require("test")
local calc = require("calc")


local function define_tests()
    test.describe("calculator", function()
        local started = false


        test.before_all(function()
            started = true
        end)


        test.it("setup ran", function()
            test.is_true(started)
        end)


        test.it("adds numbers", function()
            test.eq(calc.add(2, 3), 5)
        end)


        test.it("returns error on divide by zero", function()
            local result, err = calc.div(1, 0)
            test.has_error(result, err)
            test.contains(err, "division by zero")
        end)


        test.it_skip("not implemented yet", function()
            test.fail("should not run")
        end)
    end)
end


return { run = test.run_cases(define_tests) }

注册这两个入口。发现机制依据 meta.type: test；meta.suite 在输出中将结果分组：

version: "1.0"
namespace: app


entries:
  - name: calc
    kind: library.lua
    source: file://calc.lua


  - name: calc_test
    kind: function.lua
    meta:
      name: Calculator Test
      type: test
      suite: calculator
    source: file://calc_test.lua
    method: run
    imports:
      test: wippy.test:test
      calc: app:calc

imports 映射控制测试内部 require(...) 解析到的内容：test 绑定框架，calc 绑定被测单元。

运行

Section titled “运行”
Terminal window
wippy run test

在迭代时过滤到单个套件（匹配入口 id 或套件名称）：

Terminal window
wippy run test calculator

上述套件的输出：

  calculator (4)  3/4  1 skipped  1ms
    o setup ran
    o adds numbers
    o returns error on divide by zero
    - not implemented yet (skipped)


  PASSED   3 tests   1 skipped   1ms

当每个用例都通过时，wippy run test 退出码为 0，任何失败时为 1，因此可以直接接入 CI。

断言

Section titled “断言”

每个断言在失败时抛出错误；类型守卫还会返回经过验证的值。

断言检查
test.eq(a, b) / test.neq(a, b)相等 / 不相等
test.ok(v) / test.fail(msg)真值 / 强制失败
test.is_nil(v) / test.not_nil(v)Nil / 非 nil
test.is_true(v) / test.is_false(v)布尔值
test.is_string/number/table/function/boolean(v)类型守卫（返回 v）
test.contains(str, sub) / test.matches(str, pattern)子串 / Lua 模式
test.has_key(tbl, key) / test.len(v, n)映射键 / 长度
test.gt/gte/lt/lte(a, b)数值比较
test.throws(fn) / test.has_error(val, err) / test.no_error(val, err)错误处理

它们都接受一个可选的尾随消息参数。

生命周期与模拟

Section titled “生命周期与模拟”

在 describe 块内调用这些：

  • test.before_all / test.after_all — 每个块运行一次。
  • test.before_each / test.after_each — 围绕每个用例运行。
  • test.mock("module.field", fn) — 为当前用例替换一个函数；模拟在每个用例后自动恢复。使用 test.restore_all_mocks() 可提前清除它们。

嵌套的 describe 块继承父级钩子（外层 before_* 优先，内层 after_* 优先）。

下一步

Section titled “下一步”