docshtest 0.0.3

快速入门

docshtest是针对shell命令的doctest。这意味着它允许您在文档中集成一些shell代码示例及其预期输出，这些输出实际上是可验证的。

首先请注意，您正在阅读的这些文档行存储在一个README.rst文件中，该文件很快将包含一些如何运行docshtest以及预期结果的示例。

首先想到的例子就是运行docshtest在此文档上

docshtest README.rst

您可以自己检查，这已在CI流程中完成。

让我们向您介绍编写可测试文档的基础知识…

所以这是它的工作方式

$ cat <<'EOF' > mydoc.rst   ## First test file

This is standard RST, we can include runnable test blocks::

    $ echo 'hello world'
    hello world

EOF

请注意，需要缩进，以及在要执行命令之前需要"$ "（美元符号后跟一个空格）。请参阅以下部分以了解docshtest如何确定您的shell代码的结束以及输出的开始。

输出在您的命令结束之后开始，也需要缩进，并将与实际命令输出匹配。如果存在不匹配，测试将失败，并且docshtest将取消任何剩余的测试。如果匹配，则将执行下一个测试块。

要运行我们的测试

$ ./docshtest mydoc.rst
#0001 - success (line          4)

多行命令

多行命令通过一个非常简单但有点脏的方法检测，docshtest将简单地提供确切的代码，仅从第一行开始到shell解释器，如果shell解释器有抱怨，它将尝试再次添加下一行到输出。

这允许记录/测试多行shell代码，如

$ cat <<EOF > mydoc.rst   ## First test file

Multiline commands::

    $ for a in \$(seq 1 3); do
        echo "foo\$a"
      done
    foo1
    foo2
    foo3

EOF
$ ./docshtest mydoc.rst
#0001 - success (lines       4-6)

请注意，for循环体或done的额外缩进是不必要的，但为了阅读而推荐

$ cat <<EOF > mydoc.rst   ## First test file

Multiline commands::

    $ for a in \$(seq 1 3); do
      echo "foo\$a"
    done
    foo1
    foo2
    foo3

EOF
$ ./docshtest mydoc.rst
#0001 - success (lines       4-6)

失败的测试将显示预期输出和当前输出

$ cat <<EOF > mydoc.rst   ## First test file

Multiline commands::

    $ for a in \$(seq 1 3); do
      echo "foo\$a"
    done
    foo1
    foo4
    foo3

EOF
$ ./docshtest mydoc.rst
#0001 - failure (lines       4-6):
  command:
  | for a in $(seq 1 3); do
  |   echo "foo$a"
  | done
  expected:
  | foo1
  | foo4
  | foo3
  |
  output:
  | foo1
  | foo2
  | foo3
  |

但请注意，如果这些输出更大，将打印标准统一差异

$ cat <<EOF > mydoc.rst   ## First test file

Multiline commands::

    $ for a in \$(seq 1 6); do
      echo "foo\$a"
    done
    foo1
    foo3
    foo4
    foo5
    foo6

EOF
$ ./docshtest mydoc.rst
#0001 - failure (lines       4-6):
  command:
  | for a in $(seq 1 6); do
  |   echo "foo$a"
  | done
  expected:
  | foo1
  | foo3
  | foo4
  | foo5
  | foo6
  |
  output:
  | foo1
  | foo2
  | foo3
  | foo4
  | foo5
  | foo6
  |
  diff:
  --- expected
  +++ output
  @@ -1,4 +1,5 @@
   foo1
  +foo2
   foo3
   foo4
   foo5

修改所有执行代码

您可以通过--regex REGEX（或-r REGEX）选项在执行之前转换所有执行的代码

$ cat <<'EOF' > mydoc.rst   ## First test file

Our tested command is 'foo'

    $ foo 'hello world'
    hello world

EOF
$ ./docshtest -r '#\bfoo\b#echo#' mydoc.rst
#0001 - success (line          4)

条件测试

您可能希望有条件测试，仅在特定测试成功时触发。此功能使用元命令，这些命令作为给定块中的shell注释指定

$ cat <<'EOF' > mydoc.rst

Our tested command is 'foo'

    $ echo $ENVVAR       ## docshtest: if-success-set VAR_WAS_SET
    0
    $ echo 'var is set'  ## docshtest: ignore-if VAR_WAS_SET
    SHOULDFAIL
    $ echo 'var is not set'  ## docshtest: ignore-if-not VAR_WAS_SET
    SHOULDFAIL

EOF
$ ENVVAR=0 ./docshtest mydoc.rst
#0001 - ignored (line          4): if-success-set VAR_WAS_SET
#0002 - ignored (line          6): ignore-if VAR_WAS_SET
#0003 - failure (line          8):
  command:
  | echo 'var is not set'  ## docshtest: ignore-if-not VAR_WAS_SET
  expected:
  | SHOULDFAIL
  |
  output:
  | var is not set
  |

编码

docshtest将假设一切是“UTF-8”

$ cat <<'EOF' > mydoc.rst

Our tested command is 'foo'

    $ echo "éà"
    éà
    $ echo "é"
    e

EOF

$ ./docshtest mydoc.rst
#0001 - success (line          4)
#0002 - failure (line          6):
  command:
  | echo "é"
  expected:
  | e
  |
  output:
  | é
  |

命令行

docshtest支持常见的GNU标准--help选项

$ ./docshtest --help

docshtest - parse file and run shell doctests

Usage:

    docshtest (-h|--help)
    docshtest [[-r|--regex REGEX] ...] DOCSHTEST_FILE


Options:

    -r REGEX, --regex REGEX
              Will apply this regex to the lines to be executed. You
              can have more than one patterns by re-using this options
              as many times as wanted. Regexps will be applied one by one
              in the same order than they are provided on the command line.


Examples:

     ## run tests but replace executable on-the-fly for coverage support
     docshtest README.rst -r '/\bdocshtest\b/coverage run docshtest.py/'
<BLANKLINE>
<BLANKLINE>

第一个参数是必要的

$ ./docshtest
Error: please provide a rst filename as argument. (use '--help' option to get usage info)

当然，它应该是文件的路径

$ ./docshtest notexistent
Error: file 'notexistent' not found.

推送请求指南

您可以发送任何代码。我会查看它，并自己将其集成到代码库中，并保留您作为作者。这个过程可能需要时间，并且如果您遵循以下指南，将花费更少的时间

• 尽量保持80列宽。

• 按最小关注点分离您的提交。

• 每个提交都应该通过测试（以便于二分查找）

• 每个功能/错误修复提交应包含代码、测试和文档。

• 欢迎提交包含排版或代码美化的小修改的前次提交。这些提交的提交说明中应使用标签 !minor。

• 提交消息应遵循 gitchangelog 规则（检查 git log 获取示例）

• 如果提交解决了问题或完成了功能的实现，请在摘要中提及。

如果您对此处未解答的指南有任何疑问，请检查当前的 git log，您可能找到以前的提交，它将向您展示如何处理您的问题。

0.0.3 (2020-12-14)

修复

• 支持 utf-8 编码。[Valentin 实验室]

0.0.1 (2019-02-11)

• 首次导入。[Valentin 实验室]