md-cli-test 0.1.0

A helper library for integration testing of CLI apps using markdown files as a source of test cases
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# md-cli-test

This is a helper library for integration testing of CLI applications in Rust using _markdown_ files as a source of test cases.

`Tester` automatically extracts and runs command-line examples from code blocks in `.md` specification files, verifying the correctness of CLI application's output. It is especially useful when following a _doctest_-like approach for CLI examples, helping keep your documentation and tests in sync.

## Features

- Parses H1 headers from markdown file (`# `) as test section titles
- Parses code blocks from markdown file (```` ```sh````, ```` ```shell````) as test cases
- Executes your CLI application and additional commands (`cd`, `ls`, `mkdir`, `rm`, `echo`, `cat`)
- Verifies expected output lines
- Supports Rust-style raw multi-line string arguments for commands

## Example

Markdown file `greeting.md`:

````md
# Greeting

```sh
$ my-cli greet Alice
Hello, Alice!
```
````

Test using this library:

```rust
use md_cli_test::Tester;

#[test]
fn greeting_test_cases() {
    Tester::new("tests/greeting.md").run().unwrap();
}
```

In more complex scenarios, you can also use aliase for binary, pass environment variables, and even use `cd`, `ls`, `mkdir`, `rm`, `echo`, `cat` commands.

For example, markdown file `new_project.md` for `todo-cli` application:

````md
# New project

## New project default

```sh
$ todo new "project A"
    Creating `project A` project
```

```sh
$ ls "./project A"
Project.toml
```

```sh
$ cat "./project A/Project.toml"
id = "project A"
name = "project A"
```

```sh
$ todo new "project A"
    Creating `project A` project
Error: destination `${current_dir_path}/project A` already exists
```
````

Integration test file `new_project.rs`:

```rust
use md_cli_test::Tester;

#[test]
fn new_project_test_cases() {
    Tester::new("tests/new_project.md")
        // Use `todo` alias instead of real package or binary name
        .with_cargo_bin_alias("todo")
        // Alias must be matched to a real binary name `todo-cli`
        // if it does not match the package name
        .with_cargo_bin_name("todo-cli")
        // Pass environment variable
        .with_env("TODO_CONFIG", "./todo.toml")
        .run()
        .unwrap();
}
```

## Usage

Add to your `Cargo.toml`:

```toml
[dev-dependencies]
md-cli-test = "0.1"
```

## Why use this?

- Keeps your documentation in sync with actual CLI behavior
- Avoids duplication between examples and tests
- Makes your documentation _executable_ and verifiable

## License

[MIT](LICENSE)