tesh [tɛʃ] - TEstable SHell sessions in Markdown

展示如何运行工具的shell交互对于教学和解释很有用。

确保示例在多年后仍然有效是痛苦不堪的。

不再是。

$ tesh demo/
📄 Checking demo/happy.md
  ✨ Running foo  ✅ Passed
  ✨ Running bar  ✅ Passed
📄 Checking demo/sad.md
  ✨ Running foo  ❌ Failed
         Command: echo "foo"

         Expected:
sad panda
         Got:
foo

Taking you into the shell ...

Enter `!!` to rerun the last command.

$

语法

要将代码块标记为可测试的，请将 tesh-session="NAME" 添加到标题行。

您可以使用任何语法高亮指令，如 bash、shell、shell-session、console 或其他。

```console tesh-session="hello"
$ echo "Hello World!"
Hello World!
```

将多个代码块链接到单个shell会话

除了将代码块标记为可测试的之外，tesh-session 是一个唯一的标识符，允许多个代码块共享同一个会话。

```console tesh-session="multiple_blocks"
$ export NAME=Earth

```

```console tesh-session="multiple_blocks"
$ echo "Hello $NAME!"
Hello Earth!
```

忽略输出的一部分

可以使用 ... 忽略内联输出的部分。

```console tesh-session="ignore"
$ echo "Hello from Space!"
Hello ... Space!
```

多行支持

对于多行输出也可以这样做。请注意，每行的尾随空格将被删除。

```console tesh-session="ignore"
$ printf "Hello \nthere \nfrom \nSpace!"
Hello
...
Space!
```

命令可以通过在行前加上 > 来跨多行继续。

```console tesh-session="multiline"
$ echo "Hello from" \
>   "another" \
>   "line!"
Hello from another line!
```

高级指令

您还可以在标题行设置一些其他可选指令

• tesh-exitcodes：在代码块内部执行的命令的退出代码列表，顺序排列，
• tesh-setup：在运行代码块中的命令之前要运行的脚本文件名，
• tesh-ps1：允许除了默认的 $ 之外还有额外的 PS1 提示符，
• tesh-platform：指定在哪些平台上应该测试会话块（linux、darwin、windows），
• tesh-fixture：保存当前片段的文件名，
• tesh-timeout：命令超时前的秒数（默认为 30 秒），
• tesh-long-running：设置为 true 以展示像 docker compose up 这样的长时间运行的命令。

让我们通过一些例子来看看所有这些功能！

测试退出码

tesh-exitcodes 接受一个整数列表，代表代码块中每个命令的退出码。

```console tesh-session="exitcodes" tesh-exitcodes="1 0"
$ false

$ true

```

测试设置

有时在运行代码块中的示例之前，你需要做一些测试设置。将这些内容放入一个文件中，并用 tesh-setup 指令指向它。

```console tesh-session="setup" tesh-setup="readme.sh"
$ echo "Hello $NAME!"
Hello Gaea!
```

自定义提示符

有时你需要进入虚拟环境或类似的 shell，该 shell 会更改提示符。tesh 通过 test-ps1 指令支持此功能。

```console tesh-session="prompt" tesh-ps1="(foo) $"
$ PS1="(foo) $ "


(foo) $ echo "hello"
hello
```

仅在特定平台上运行

某些示例仅应在某些平台上运行，使用 tesh-platform 声明它们。

```console tesh-session="platform" tesh-platform="linux"
$ uname
...Linux...
```

```console tesh-session="platform" tesh-platform="darwin"
$ uname
...Darwin...
```

将文件转储到磁盘

有时你的示例首先显示文件的内容，然后执行使用该文件的命令。这得到了支持，使用 tesh-fixture 指令。

```bash tesh-session="fixture" tesh-fixture="foo.sh"
echo "foo"
```

```console tesh-session="fixture"
$ chmod +x foo.sh

$ ./foo.sh
foo
```

自定义超时

默认情况下，如果示例命令在 30 秒内未完成，tesh 将失败。可以使用 tesh-timeout 指令修改此数字。

```console tesh-session="timeout" tesh-timeout="3"
$ sleep 1

```

长时间运行的过程

有些你想要展示示例的过程是长时间运行的过程，如 docker compose up。它们在 tesh 块中使用 tesh-long-running 指令得到支持。请注意，它们需要是块中的最后一个命令。

```console tesh-session="long-running" tesh-timeout="1" tesh-long-running="true"
$ nmap 1.1.1.1
Starting Nmap ...
```

安装

安装 tesh 的最佳方式是使用你最喜欢的 Python 软件包管理器。

$ pip install tesh

设计决策

• 支持 Linux / macOS。
• 不依赖于特定的 markdown 味道或工具。
• 在 GitHub 上渲染得相当好。

与其他工具的比较

• ✔️：受支持
• C：可能但你需要自己编写一些代码
• 🚧：开发中
• ✖️：不受支持
• ？：我不知道。

开发 tesh

我们为在此项目上工作的人提供两个开发环境，一个基于 Nix，另一个基于 Docker。

对于 Nix，运行 nix develop 进入开发环境，其中一切准备就绪。

对于 Docker，运行 docker build -t tesh . && docker run --rm -v .:/tesh -it tesh 进入开发环境，其中一切准备就绪。

然后你可以运行 make tests 来运行所有测试和检查。

有其他 make 命令可以运行测试或检查的子集。

# run tesh on all Markdown files
$ make tesh

# run flake8 linters on changed files only
$ make lint

# run flake8 linters on all files
$ make lint all=true

# run mypy type checker
$ make types

# run unit tests
$ make unit

# run a subset of unit tests (regex find)
$ make unit filter=foo

多个 Python 版本

默认情况下，开发环境使用最新支持的 Python 版本。这就是如何进入一个使用较旧 Python 的环境。

在 Linux 上

$ nix develop .#devShells.x86_64-linux.default-python39

在 macOS 上

$ nix develop .#devShells.aarch64-darwin.default-python39

在 CI 上，所有支持的 Python 版本都经过测试。