debugger_test 0.1.0

Provides a proc macro for writing tests that launch a debugger and run commands while verifying the output.
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# debugger_test

Provides an easy way of integrating debugger specific tests into a crate.

This crate is responsible for generating the `#[debugger_test]` proc macro attribute.

## Usage

To use, add this crate and the `debugger_test_parser` as a dependency in your `Cargo.toml`.

This crate uses the `debugger_test_parser` to parse the output of the specified debugger
and verify all expected statements were found.

In order to set breakpoints, an `__break()` function will need to be defined and called
at each place the debugger should stop.

For example:

```rust
#[inline(never)]
pub fn __break() { }

#[debugger_test(
    debugger = "cdb",
    commands = r#"
.nvlist
dv
g"#,
    expected_statements = r#"
pattern:test\.exe .*\.natvis
a = 0n10
    "#)]
pub fn test() {
    let a = 10;
    __break();
}
```

The `#[debugger_test]` proc macro attribute has 3 required meta items which all take a string value:

1. debugger
2. commands
3. expected_statements

The `debugger` meta item expects the name of a supported debugger. Currently the only supported debugger is `cdb`.

The `commands` meta item expects a string of a debugger command to run. To run multiple commands, separate each
command by the new line character (`\n`).

The `expected_statements` meta item expects a string of output to verify in the debugger output.
Each statement should be separated by a new line character (`\n`).

For example:

```rust
#[debugger_test(
    debugger = "cdb",
    commands = "command1\ncommand2\ncommand3",
    expected_statements = "statement1\nstatement2\nstatement3")]
```

Using a multiline string is also supported:

```rust
#[debugger_test(
    debugger = "cdb",
    commands = r#"
command1
command2
command3"#,
    expected_statements = r#"
statement1
statement2
statement3"#)]
```

Pattern matching is also supported for a given `expected_statement`. Use the prefix, `pattern:` for the
expected statement. This is useful for ignoring debugger output that contain memory address and/or paths:

```rust
#[debugger_test(
    debugger = "cdb",
    commands = "command3",
    expected_statements = "pattern:abc.*")]
```

The `#[debugger_test]` proc macro attribute will generate a new test function that will be marked
with the `#[test]` attribute. This generated test function will add a suffix to the test name to ensure
the test is unique. In the example above, the proc macro attribute will generate the following function:

```rust
#[test]
pub fn test__cdb() {
    .....
    test();
    .....
}
```

The proc macro attribute will generate a test function that will do the following:

1. Launch the specified debugger
2. Attach the debugger to the current test executable process
3. Set breakpoints at all call sites of the `__break()` function
4. Run the debugger to the first breakpoint specified by the debugger
5. Run all of the user specified commands and exit the debugger
6. Parse the debugger output using the `debugger_test_parser` crate and verify all the `expected_statements` were found

## Contributing

This project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
trademarks or logos is subject to and must follow 
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.