tests: expected object support in tests/roundtrip

Add optional support to test the deserialized bytes against an expected
static object. Uses a macro to concisely list modules that contain an
`expected()` function that returns the expected `Request` or `Response`
object.

Existing tests could have expected objects added to improve the error
reporting in case of test failure.

Signed-off-by: Ross Williams <ross@ross-williams.net>

Author: overhacked

tests/roundtrip/expected.rs

@@ -0,0 +1,24 @@
+#[macro_use]
+mod macros;
+
+use ssh_agent_lib::proto::{Request, Response};
+
+// This macro generates a function with the following signature:
+//
+// `fn request(path: impl AsRef<Path>) -> Option<Request>`
+//
+// When called, it will take the filename without extension from the provided path (replacing any
+// dashes with underscores) and compare that string to the list of modules in the bracketed list.
+// If one of the listed modules matches the filename (e.g. `req-example-test.bin`), the function
+// `req_example_test::expected()` will be called, which must have the signature `pub fn expected()
+// -> Request`. (If none of the modules match the filename, `None` will be returned.)
+//
+// The roundtrip test code calls this to enhance `Encode`/`Decode` roundtrip tests with a known
+// static object that must match the deserialized bytes.
+//
+// The macro also declares the listed modules.
+make_expected_fn!(request -> Request, {
+});
+
+make_expected_fn!(response -> Response, {
+});

tests/roundtrip/expected/macros.rs

@@ -0,0 +1,66 @@
+//!
+//! The macro in this file takes 3 arguments:
+//!     1. The name of the function to generate
+//!     2. The return type of the function
+//!     3. A brace-enclosed, comma-separated list of module
+//!        names
+//!
+//!  Each module in (3) should match the basename of a file in `tests/messages` but with dashes
+//!  replaced by underscores to make it a valid Rust identifier. When the generated function is
+//!  called with a filename that matches one of these modules, it will call the `expected()`
+//!  function of that module, which should return an object of the return type specified in the
+//!  macro, which will be returned as Some(expected()). If the generated function is called with a
+//!  filename that does not match any module, it will return `None`.
+//!
+//!  # Example #
+//!
+//!  ## Macro call ##
+//!
+//!  ```ignore
+//!  use ssh_agent_lib::proto::Request;
+//!
+//!  make_expected_fn!(get_expected_request, Request, {
+//!      req_hello
+//!  });
+//!  ```
+//!
+//!  ## Usage of generated function in test code ##
+//!
+//!  ```ignore
+//!  let test_data_path = PathBuf::from("test/messages/req-hello.bin");
+//!  let expected = path::to::get_expected_request(&test_data_path);
+//!  assert_eq!(expected, ...);
+//!  ```
+//!
+//!  ## `path/to/req_hello.rs` ##
+//!
+//!  ```ignore
+//!  pub fn expected() -> Request {
+//!      ...
+//!  }
+//!  ```
+
+macro_rules! make_expected_fn {
+    ($fn_name:ident -> $ty:ty, { $($case:ident),+ } ) => {
+        $( mod $case; )+
+
+        pub fn $fn_name(path: impl ::core::convert::AsRef<::std::path::Path>) -> ::core::option::Option<$ty> {
+            let cases: &[(&str, &dyn ::core::ops::Fn() -> $ty)] = &[
+                $( (::core::stringify!($case), &self::$case::expected,) ),+
+            ];
+
+            let path_case_name = path
+                .as_ref()
+                .file_stem()
+                .expect("test path has no filename")
+                .to_str()
+                .expect("test filename not UTF-8")
+                .replace("-", "_");
+
+            cases
+                .into_iter()
+                .find(|(c, _)| c == &path_case_name)
+                .map(|(_, f)| f())
+        }
+    };
+}

tests/roundtrip.rs renamed to tests/roundtrip/main.rs

@@ -1,18 +1,28 @@
-use std::path::PathBuf;
+mod expected;
+
+use std::path::{Path, PathBuf};
 
 use rstest::rstest;
 use ssh_agent_lib::proto::{Request, Response};
 use ssh_encoding::{Decode, Encode};
 use testresult::TestResult;
 
-fn roundtrip<T: Decode + Encode + std::fmt::Debug>(path: PathBuf) -> TestResult
+fn roundtrip<T>(path: impl AsRef<Path>, expected: Option<T>) -> TestResult
 where
+    T: Decode + Encode + PartialEq + std::fmt::Debug,
     T::Error: std::fmt::Display,
 {
     let serialized = std::fs::read(path)?;
     let mut bytes: &[u8] = &serialized;
     let message = T::decode(&mut bytes)?;
     eprintln!("Message: {message:#?}");
+    if let Some(expected) = expected {
+        eprintln!("Expected: {expected:#?}");
+        assert_eq!(
+            expected, message,
+            "parsed message does not match expected object"
+        );
+    }
     let mut out = vec![];
     message.encode(&mut out)?;
     assert_eq!(
@@ -29,10 +39,10 @@ where
 
 #[rstest]
 fn roundtrip_requests(#[files("tests/messages/req-*.bin")] path: PathBuf) -> TestResult {
-    roundtrip::<Request>(path)
+    roundtrip::<Request>(&path, expected::request(&path))
 }
 
 #[rstest]
 fn roundtrip_responses(#[files("tests/messages/resp-*.bin")] path: PathBuf) -> TestResult {
-    roundtrip::<Response>(path)
+    roundtrip::<Response>(&path, expected::response(&path))
 }