mirror of
https://gitlab.redox-os.org/CoffeeCode/redox-ssh.git
synced 2025-12-28 22:32:18 +01:00
254 lines
No EOL
13 KiB
HTML
254 lines
No EOL
13 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `test` mod in crate `ring`.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, test">
|
||
|
||
<title>ring::test - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../../normalize.css">
|
||
<link rel="stylesheet" type="text/css" href="../../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../../main.css">
|
||
|
||
|
||
|
||
|
||
</head>
|
||
<body class="rustdoc mod">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
|
||
<p class='location'>Module test</p><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'><a href='../index.html'>ring</a></p><script>window.sidebarCurrent = {name: 'test', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content">
|
||
<h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>ring</a>::<wbr><a class="mod" href=''>test</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../../src/ring/test.rs.html#15-561' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>Testing framework.</p>
|
||
|
||
<p>Unlike the rest of <em>ring</em>, this testing framework uses panics pretty
|
||
liberally. It was originally designed for internal use--it drives most of
|
||
<em>ring</em>'s internal tests, and so it is optimized for getting <em>ring</em>'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.</p>
|
||
|
||
<h1 id='examples' class='section-header'><a href='#examples'>Examples</a></h1>
|
||
<h2 id='writing-tests' class='section-header'><a href='#writing-tests'>Writing Tests</a></h2>
|
||
<p>Input files look like this:</p>
|
||
|
||
<pre><code class="language-text"># This is a comment.
|
||
|
||
HMAC = SHA1
|
||
Input = "My test data"
|
||
Key = ""
|
||
Output = 61afdecb95429ef494d61fdee15990cabf0826fc
|
||
|
||
HMAC = SHA256
|
||
Input = "Sample message for keylen<blocklen"
|
||
Key = 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
|
||
Output = A28CF43130EE696A98F14A37678B56BCFCBDD9E5CF69717FECF5480F0EBDF790
|
||
</code></pre>
|
||
|
||
<p>Test cases are separated with blank lines. Note how the bytes of the <code>Key</code>
|
||
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 (<code>""</code>).</p>
|
||
|
||
<p>Here's how you would consume the test data:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">use</span> <span class="ident">ring</span>::<span class="ident">test</span>;
|
||
|
||
<span class="ident">test</span>::<span class="ident">from_file</span>(<span class="string">"src/hmac_tests.txt"</span>, <span class="op">|</span><span class="ident">section</span>, <span class="ident">test_case</span><span class="op">|</span> {
|
||
<span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">section</span>, <span class="string">""</span>); <span class="comment">// This test doesn't use named sections.</span>
|
||
|
||
<span class="kw">let</span> <span class="ident">digest_alg</span> <span class="op">=</span> <span class="ident">test_case</span>.<span class="ident">consume_digest_alg</span>(<span class="string">"HMAC"</span>);
|
||
<span class="kw">let</span> <span class="ident">input</span> <span class="op">=</span> <span class="ident">test_case</span>.<span class="ident">consume_bytes</span>(<span class="string">"Input"</span>);
|
||
<span class="kw">let</span> <span class="ident">key</span> <span class="op">=</span> <span class="ident">test_case</span>.<span class="ident">consume_bytes</span>(<span class="string">"Key"</span>);
|
||
<span class="kw">let</span> <span class="ident">output</span> <span class="op">=</span> <span class="ident">test_case</span>.<span class="ident">consume_bytes</span>(<span class="string">"Output"</span>);
|
||
|
||
<span class="comment">// Do the actual testing here</span>
|
||
});</pre>
|
||
|
||
<p>Note that <code>consume_digest_alg</code> automatically maps the string "SHA1" to a
|
||
reference to <code>digest::SHA1</code>, "SHA256" to <code>digest::SHA256</code>, etc.</p>
|
||
|
||
<h2 id='output-when-a-test-fails' class='section-header'><a href='#output-when-a-test-fails'>Output When a Test Fails</a></h2>
|
||
<p>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:</p>
|
||
|
||
<pre><code class="language-text">Curve = P-256
|
||
a = 2b11cb945c8cf152ffa4c9c2b1c965b019b35d0b7626919ef0ae6cb9d232f8af
|
||
b = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
|
||
r = 18905f76a53755c679fb732b7762251075ba95fc5fedb60179e730d418a9143c
|
||
</code></pre>
|
||
|
||
<p>If the test fails, this will be printed (if <code>$RUST_BACKTRACE</code> is <code>1</code>):</p>
|
||
|
||
<pre><code class="language-text">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
|
||
</code></pre>
|
||
|
||
<p>Notice that the output shows the name of the data file
|
||
(<code>src/example_tests.txt</code>), 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 <code>example.rs</code>.</p>
|
||
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="rand/index.html"
|
||
title='mod ring::test::rand'>rand</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Deterministic implementations of <code>ring::rand::SecureRandom</code>.</p>
|
||
</td>
|
||
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.TestCase.html"
|
||
title='struct ring::test::TestCase'>TestCase</a></td>
|
||
<td class='docblock-short'>
|
||
<p>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.</p>
|
||
</td>
|
||
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.from_file.html"
|
||
title='fn ring::test::from_file'>from_file</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Reads test cases out of the file with the path given by
|
||
<code>test_data_relative_file_path</code>, calling <code>f</code> on each vector until <code>f</code> fails
|
||
or until all the test vectors have been read. <code>f</code> can indicate failure
|
||
either by returning <code>Err()</code> or by panicking.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.from_hex.html"
|
||
title='fn ring::test::from_hex'>from_hex</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Decode an string of hex digits into a sequence of bytes. The input must
|
||
have an even number of digits.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="fn" href="fn.ring_src_path.html"
|
||
title='fn ring::test::ring_src_path'>ring_src_path</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Returns the path for <em>ring</em> source code root.</p>
|
||
</td>
|
||
</tr></table></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
<dt>+</dt>
|
||
<dd>Collapse/expand all sections</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../../";
|
||
window.currentCrate = "ring";
|
||
</script>
|
||
<script src="../../jquery.js"></script>
|
||
<script src="../../main.js"></script>
|
||
<script defer src="../../search-index.js"></script>
|
||
</body>
|
||
</html> |