Bashtestmd

Compiles Markdown files with Bash code blocks into a single Bash script for CI testing purposes.

Basic Usage

The following command parses all code blocks from the input markdown file and generates a script containing all blocks tagged with the specified TAG_NAME

bashtestmd --input {PATH_TO_INPUT_FILE} --output {OUTPUT_FILE_NAME} --tag {TAG_NAME}`.

For example, bashtestmd --input README.md --output demo-readme.sh --tag test-ci will find all code blocks of the form and generate a script which runs them sequentially, enforcing that each command exits with status code 0.

```sh,test-ci
$ echo "This is a demo"
```

Note that bashtestmd only interprets lines beginning with $ as commands. This allows output to be included in snippets without compromising the generated script.

```sh,test-ci
$ echo "This is a demo"
This is a demo
```

Supported tags

bashtestmd supports the following optional tags on code blocks:

1. bashtestmd:compare-output
2. bashtestmd:exit-code-ignore
3. bashtestmd:exit-code="{EXPECTED_CODE}"
4. bashtestmd:long-running
5. bashtestmd:wait-until="{TEXT}"

Compare Output

The tag bashtestmd:compare-output causes the generated script to check that the command output matches the output in the markdown file.

For example, this command will fail if the server returns "goodbye" in response to a query to localhost:80/hello instead of the expected "hello, world"

```sh,test-ci,bashtestmd:compare-output`
$ curl localhost:80/hello
"hello, world"
```

Exit Code Ignore

The tag bashtestmd:exit-code-ignore causes bashtestmd to ignore the exit code of the command rather than enforcing that the code is 0

Exit Code

The tag bashtestmd:exit-code="{CODE}" causes bashtestmd to check that the exit code of the command matches the provided value

```sh,test-ci,bashtestmd:exit-code="1"`
$ rm this_file_does_not_exist.txt
rm: this_file_does_not_exist.txt: No such file or directory
```

Long Running

The tag bashtestmd:long-running causes the command to run in the background and waits 120 seconds for the task to complete. It is strongly recommended to combine long-running with wait-until in order to override this default behavior.

For example, the following commmand compiles to cargo run &; sleep 120

```sh,test-ci,bashtestmd:long-running`
$ cargo run
```

Wait Until

The tag bashtestmd:wait-until={SOME_TEXT} will cause the script to wait for the process to output the expected text before continuing rather than simply sleeping for two minutes. Note that this command requires the long-running tag in order to have an effect.

```sh,test-ci,bashtestmd:long-running,bashtestmd:wait-until="Finished release"`
$ cargo build --release
```

Local Installation

To set up bashtestmd for local development

1. git clone https://github.com/Sovereign-Labs/bashtestmd.git
2. cargo install --path bashtestmd/