microsoft / rust_debugger_test

A Rust framework for testing debuggers and their outputs

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:

#[inline(never)]
fn __break() { }

#[debugger_test(
    debugger = "cdb",
    commands = r#"
.nvlist
dv
g"#,
    expected_statements = r#"
pattern:test\.exe .*\.natvis
a = 0n10
    "#)]
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. This crate will try to find the specified debugger, first by testing if it is on the PATH. If the debugger is not found, this crate will search the default installation directory for the debugger. Specifying an exact path for which debugger to use is not currently supported.

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:

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

Using a multiline string is also supported:

#[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:

#[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:

#[test]
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

Based on the debugger specified via the #[debugger_test] attribute, the path used to launch the debugger will be one of the following:

1. If the environment variable, debugger_type _DEBUGGER_DIR is set, i.e. CDB_DEBUGGER_DIR, the proc macro attribute will try to launch the debugger from this directory
2. The default installation directory for the given debugger if it exists at that path
3. Invoking the executable directly, i.e. cdb or cdb.exe depending on the OS

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. For more information see the Code of Conduct FAQ or contact [email protected] 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. 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.