x assert

测试断言工具，用于验证测试结果是否符合预期。

所有断言失败时返回非0退出码。
项目地址：https://github.com/x-bash/assert

TIP

测试最佳实践：

1. 命令成功用 'x assert -- [ test ]'
2. 预期失败用 'x assert ! cmd'
3. 变量加引号: 'x assert === "$a" "$b"'
4. 否定检查用 ^: 'x assert is-file ^nonexist'
5. 变量泄漏检测: 'x assert var save' → 调用函数 → 'x assert var cmp'

例子

测试: 验证命令成功返回0

x assert true [ 1 -eq 1 ]

测试: 验证命令失败返回非0

x assert ! false

测试: 忽略stderr，验证命令成功

x assert exit-0 noisy_cmd

测试: 批量验证多个值都是整数

x assert is-int 1 2 3 4 5

测试: 批量验证多个浮点数

x assert is-float 3.14 2.718 0.5

测试: 批量验证多个正整数(>0)

x assert is-positive 42 100 999

测试: 批量验证多个变量已设置

x assert is-set HOME PATH USER

测试: 批量验证多个变量未设置(^否定)

x assert is-set ^UNDEFINED ^NOTSET ^EMPTY

测试: 验证多值全等(3个及以上)

x assert === "$a" "$b" "$c" "$d"

测试: 验证值在多个选项中(多候选)

x assert == "$status" pending running completed failed

测试: 复杂正则匹配

x assert =~ "$str" "^[a-zA-Z0-9_]+$"

测试: glob匹配多pattern(4个及以上)

x assert =- "$file" "*.yml" "*.yaml" "*.json" "*.toml"

测试: 批量验证多个文件存在

x assert is-file /etc/passwd /etc/hosts /etc/resolv.conf

测试: 批量验证多个目录存在

x assert is-folder /tmp /var /home

测试: 批量验证多个文件不存在(^否定)

x assert is-file ^nonexist1 ^nonexist2 ^nonexist3

测试: 验证stdout输出(heredoc)

x assert stdout echo hi <<EOF
hi
EOF

测试: 验证stdout输出(pipe)

echo expected | x assert stdout cat

测试: 验证stderr输出

x assert stderr grep pattern file <<EOF
pattern
EOF

测试: 验证自定义退出码

x assert return-42 mycmd

测试: 保存变量快照

x assert var save

测试: 对比快照(检测变量泄漏)

x assert var cmp

测试: 检测函数是否意外修改全局变量

myfunc() { local x=1; y=2; }
x assert var save
myfunc
x assert var cmp

测试: 允许新增my_func_result变量(+声明)

x assert var save
my_func
x assert var cmp +my_func_result

测试: 允许修改count和status变量(:声明)

x assert var save
process_data
x assert var cmp :count :status

测试: 验证命令以特定退出码失败

x assert exit-42 false

测试: 组合多个断言进行复杂验证

x assert is-file /etc/passwd /etc/hosts && x assert is-folder /tmp /var

使用

x assert [FLAGS] [SUB_COMMAND]

指令

名称, 名称简写	描述
--, true	期待命令执行成功(返回0)。示例: x assert -- [ -f file ]

子命令

名称	描述
x assert is-nonempty	期待文件非空(大小>0)
x assert is-int	期待是整数。支持多值检查
x assert is-float	期待是浮点数
x assert is-positive	期待是正整数(>0)。注意: 0不是正数
x assert is-eq	期待两个值相等
x assert is-set	期待变量已设置。用^var检查未设置
x assert is-file	期待是普通文件
x assert is-folder	期待是文件夹
x assert is-pipe	期待是命名管道(FIFO)
x assert is-socket	期待是socket文件
x assert is-link	期待是符号链接
x assert is-readable	期待文件可读
x assert is-writable	期待文件可写
x assert is-executable	期待文件可执行
x assert is-exsited	期待文件/文件夹存在
x assert ===	期待所有值相等
x assert ==	期待第一个值匹配后续列表中的某一项
x assert =-	期待值匹配case模式(glob语法)
x assert ==-	期待生成的值包含在所提供的值中(大小写不敏感)
x assert stdout	期待命令stdout等于stdin提供的内容（heredoc方式）
x assert stderr	期待命令stderr等于stdin提供的内容
x assert ypart	期待yml内容包含或等于预期内容
x assert var	变量快照：save保存快照, cmp对比变化(+新增/-删除/:修改), print打印快照
x assert set-errexit	开启错误退出模式：断言失败时直接退出脚本
x assert unset-errexit	关闭错误退出模式

TIP

在交互式终端中（如 zsh, bash ...），可以使用 Tab 获取补全信息

运行 CMD SUBCOMMAND --help 可以获取命令的更多信息