---
url: /mod/assert.md
---
# 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

```sh
x assert true [ 1 -eq 1 ]
```

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

```sh
x assert ! false
```

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

```sh
x assert exit-0 noisy_cmd
```

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

```sh
x assert is-int 1 2 3 4 5
```

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

```sh
x assert is-float 3.14 2.718 0.5
```

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

```sh
x assert is-positive 42 100 999
```

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

```sh
x assert is-set HOME PATH USER
```

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

```sh
x assert is-set ^UNDEFINED ^NOTSET ^EMPTY
```

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

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

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

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

测试: 复杂正则匹配

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

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

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

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

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

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

```sh
x assert is-folder /tmp /var /home
```

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

```sh
x assert is-file ^nonexist1 ^nonexist2 ^nonexist3
```

测试: 验证stdout输出(heredoc)

```sh
x assert stdout echo hi <<EOF
hi
EOF

```

测试: 验证stdout输出(pipe)

```sh
echo expected | x assert stdout cat
```

测试: 验证stderr输出

```sh
x assert stderr grep pattern file <<EOF
pattern
EOF

```

测试: 验证自定义退出码

```sh
x assert return-42 mycmd
```

测试: 保存变量快照

```sh
x assert var save
```

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

```sh
x assert var cmp
```

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

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

```

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

```sh
x assert var save
my_func
x assert var cmp +my_func_result

```

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

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

```

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

```sh
x assert exit-42 false
```

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

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

## 使用

```sh
x assert [FLAGS] [SUB_COMMAND]
```

## 指令

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


## 子命令

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