Module ring::test

Testing framework.

Unlike the rest of ring, this testing framework uses panics pretty liberally. It was originally designed for internal use–it drives most of ring’s internal tests, and so it is optimized for getting ring’s tests written quickly at the expense of some usability. The documentation is lacking. The best way to learn it is to look at some examples. The digest tests are the most complicated because they use named sections. Other tests avoid named sections and so are easier to understand.

Examples

Writing Tests

Input files look like this:

HMAC = SHA1
Input = "My test data"
Key = ""
Output = 61afdecb95429ef494d61fdee15990cabf0826fc

HMAC = SHA256
Input = "Sample message for keylen<blocklen"
Key = 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
Output = A28CF43130EE696A98F14A37678B56BCFCBDD9E5CF69717FECF5480F0EBDF790

Test cases are separated with blank lines. Note how the bytes of the Key attribute are specified as a quoted string in the first test case and as hex in the second test case; you can use whichever form is more convenient and you can mix and match within the same file. The empty sequence of bytes can only be represented with the quoted string form ("").

Here’s how you would consume the test data:

use ring::test;

test::run(test::test_file!("hmac_tests.txt"), |section, test_case| {
    assert_eq!(section, ""); // This test doesn't use named sections.

    let digest_alg = test_case.consume_digest_alg("HMAC");
    let input = test_case.consume_bytes("Input");
    let key = test_case.consume_bytes("Key");
    let output = test_case.consume_bytes("Output");

    // Do the actual testing here
});

Note that consume_digest_alg automatically maps the string “SHA1” to a reference to digest::SHA1_FOR_LEGACY_USE_ONLY, “SHA256” to digest::SHA256, etc.

Output When a Test Fails

When a test case fails, the framework automatically prints out the test case. If the test case failed with a panic, then the backtrace of the panic will be printed too. For example, let’s say the failing test case looks like this:

Curve = P-256
a = 2b11cb945c8cf152ffa4c9c2b1c965b019b35d0b7626919ef0ae6cb9d232f8af
b = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
r = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c

If the test fails, this will be printed (if $RUST_BACKTRACE is 1):

src/example_tests.txt: Test panicked.
Curve = P-256
a = 2b11cb945c8cf152ffa4c9c2b1c965b019b35d0b7626919ef0ae6cb9d232f8af
b = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
r = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
thread 'example_test' panicked at 'Test failed.', src\test.rs:206
stack backtrace:
   0:     0x7ff654a05c7c - std::rt::lang_start::h61f4934e780b4dfc
   1:     0x7ff654a04f32 - std::rt::lang_start::h61f4934e780b4dfc
   2:     0x7ff6549f505d - std::panicking::rust_panic_with_hook::hfe203e3083c2b544
   3:     0x7ff654a0825b - rust_begin_unwind
   4:     0x7ff6549f63af - std::panicking::begin_panic_fmt::h484cd47786497f03
   5:     0x7ff654a07e9b - rust_begin_unwind
   6:     0x7ff654a0ae95 - core::panicking::panic_fmt::h257ceb0aa351d801
   7:     0x7ff654a0b190 - core::panicking::panic::h4bb1497076d04ab9
   8:     0x7ff65496dc41 - from_file<closure>
                        at C:\Users\Example\example\<core macros>:4
   9:     0x7ff65496d49c - example_test
                        at C:\Users\Example\example\src\example.rs:652
  10:     0x7ff6549d192a - test::stats::Summary::new::ha139494ed2e4e01f
  11:     0x7ff6549d51a2 - test::stats::Summary::new::ha139494ed2e4e01f
  12:     0x7ff654a0a911 - _rust_maybe_catch_panic
  13:     0x7ff6549d56dd - test::stats::Summary::new::ha139494ed2e4e01f
  14:     0x7ff654a03783 - std::sys::thread::Thread::new::h2b08da6cd2517f79
  15:     0x7ff968518101 - BaseThreadInitThunk

Notice that the output shows the name of the data file (src/example_tests.txt), the test inputs that led to the failure, and the stack trace to the line in the test code that panicked: entry 9 in the stack trace pointing to line 652 of the file example.rs.

Structs

File

A test input file.

TestCase

A test case. A test case consists of a set of named attributes. Every attribute in the test case must be consumed exactly once; this helps catch typos and omissions.

Functions

compile_time_assert_clone

compile_time_assert_clone::<T>(); fails to compile if T doesn’t implement Clone.

compile_time_assert_copy

compile_time_assert_copy::<T>(); fails to compile if T doesn’t implement Copy.

compile_time_assert_send

compile_time_assert_send::<T>(); fails to compile if T doesn’t implement Send.

compile_time_assert_std_error_error

compile_time_assert_std_error_error::<T>(); fails to compile if T doesn’t implement std::error::Error.

compile_time_assert_sync

compile_time_assert_sync::<T>(); fails to compile if T doesn’t implement Sync.

from_hex

Decode an string of hex digits into a sequence of bytes. The input must have an even number of digits.

run

Parses test cases out of the given file, calling f on each vector until f fails or until all the test vectors have been read. f can indicate failure either by returning Err() or by panicking.