Rust unit testing: the not so happy path

Fortunately, Rust developers have less disruptive ways to deal with the undesired or unexpected. And I really like the way this is implemented in Rust. Functions can return Result<T,E>, which is an enum with just two variants. One for when it comes up with the goods (Ok(T)) and another for the moments when you might need a shoulder cry on (Err(E)). The snobby programmer in me wants to point out that this is known as an algebraic data type, but I won't.

Let's change our implementation, using the From trait, to allow it to fail. From doesn't allow conversions to fail, but TryFrom does, so we will use it, instead of From, in our Supervillain.

And while we are at it, we are going to experiment with the ability to skip tests. That is something that you may want to do when you know that a test –well, maybe some– is broken and you want to run the rest without the background noise. Preferably, this would happen in the process of refactoring some code, rather than due to having a test that you can't get to work.

In this case, we are going to add the #[ignore] attribute to the test that checks the implementation of the From trait.

  #[test]
  #[ignore]
  fn from_str_slice_produces_supervillain_full_with_first_and_last_name() {

If we save and run the tests, we will notice that it is not executed. Yet, its name is printed, it comes with a result ("ignored"), and it gets accounted for.

running 5 tests
test supervillain::tests::from_str_slice_produces_supervillain_full_with_first_and_last_name ... ignored
test supervillain::tests::attack_shoots_weapon ... ok
test supervillain::tests::full_name_is_first_name_space_last_name ... ok
test supervillain::tests::set_full_name_sets_first_and_last_names ... ok
test supervillain::tests::set_full_name_panics_with_empty_name - should panic ... ok

test result: ok. 4 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s

Remember that you can re-enable all the ignored tests from the command line using cargo t -- --include-ignored. You will be ignoring the #[ignore], not changing the file, though.

Let's change the implementation of the From trait to TryFrom.

  impl TryFrom<&str> for Supervillain {
     fn try_from(name: &str) -> Result<Self, Self::Error> {

And we take care of the successful case by wrapping the Supervillain in the Ok variant.

  Ok(Supervillain {
      first_name: components[0].to_string(),
      last_name: components[1].to_string(),
  })

If we try to run the tests, we may take notice of two things:

• Even though, we aren't returning any error yet, the implementation of the TryFrom trait doesn't compile because we haven't specified the associated type that we want to use for its errors. We must provide that information to the compiler to let it do its job.
• The test that we marked to be ignored, is still compiled. And it fails, because we don't have an associated function Supervillain::from(&str) anymore. Interestingly enough, if the code is just syntactically correct, cargo build will compile. When I say "syntactically correct", I do it in opposition to semantically correct, i.e. the code "looks correct" (e.g., no missing trailing semicolons), but the associated function Supervillain::from(&str) isn't defined. The takeaway here is that #[ignore] won't help if any of your tests doesn't compile, but commenting tests out or just building the main source while you get the tests again under control, can still do wonders.

We wanted to return an error and this is what we have to do now. But, which kind of error should we return? Well, we have at least, four options:

1. The simplest option is to use String as the associated Error type. This is quite straightforward, but then we will have a harder time when we want to differentiate among distinct error types or use ? for converting errors. This could be a temporary solution, but not one we want to take for building high-quality software.
2. The next option is using anyhow, eyre, or a similar crate. It is a better option that using strings. Out of the box, you get a single error type that can be used anywhere, a macro to produce those errors, automatic conversion from existing errors, and additional information. They are great options when you want to manage the errors at the application level, but not so useful if you want the different errors produced by your (library) code to be handled in different ways.
3. A third and much more sophisticated option is to define our own error types. This allows for a more granular and flexible error handling. However, this is much more tedious than the previous options. We have to define an enum with all the variants for the different error types, describe the associated data for each variant, implement or derive Debug, implement Display, and use the blanket implementation of the Error trait.
4. Finally, we could use the thiserror crate that allows us to define our own error types, while keeping the amount of boilerplate required to the bare minimum. The only valid reason for not using thiserror here would be to reduce the number of external dependencies. Breath easy.

Our evil software deserves its own errors and we don't want to put more effort than necessary. For this reason, we are going to use thiserror to define our error type, which I have decided to call EvilError.

We are going to start by defining the enum for the different variants.

  pub enum EvilError {}

Inside, we define the variants and its associated data. Initially, we are going to use just one: ParseError. And it will contain the purpose of this parsing and a reason. We can add more variants later, when we need them.

  ParseError { purpose: String, reason: String },

Despite of the name, this is not a valid error yet. It doesn't implement the Error trait and its requirements. We are going to add thiserror to take care of that.

  cargo add thiserror

Back in the code, we import thiserror.

  use thiserror::Error;

And we can now derive Error (and Debug) for our type.

  #[derive(Error, Debug)]
  pub enum EvilError {

It is important that for each of the variants, we define the error message that we want to be shown. We do that by adding the #[error(...)] attribute to every variant. For our single variant, this will be:

  #[error("Parse error: purpose='{}', reason='{}'", .purpose, .reason)]

And that is all that's needed to define our custom error.

We tell the compiler that the associated type for the Error in the implementation of TryFrom is our new error.

  type Error = EvilError;

And we can now use it to return an error from our Supervillain::try_from(name: &str) associated function, when we receive a name with less that two words.

  if components.len() < 2 {
      Err(EvilError::ParseError {
          purpose: "full_name".to_string(),
          reason: "Too few arguments".to_string(),
      })
  } else {
      // Existing Ok goes here
  }

cargo b should work fine with this code.¹

Let's go with the existing test now. We have to change it to use TryFrom instead of From. We update its name accordingly and use let-else pattern matching to check that the operation was successful, aborting the test with a panic! otherwise.

  #[test]
  fn try_from_str_slice_produces_supervillain_full_with_first_and_last_name() {
      let result = Supervillain::try_from(test_common::SECONDARY_FULL_NAME);
      let Ok(sut) = result else { panic!("Unexpected error returned by try_from"); };
      assert_eq!(sut.first_name, test_common::SECONDARY_FIRST_NAME);
      assert_eq!(sut.last_name, test_common::SECONDARY_LAST_NAME);
  }

All this code and we haven't tested the not-so-happy path yet! Let's write another test that checks if the expected error is received when TryFrom is invoked with an empty string. It is similar, but easier than the previous one.

  #[test]
  fn try_from_str_slice_produces_error_with_less_than_two_substrings() {
      let result = Supervillain::try_from("");
      let Err(_) = result else { panic!("Unexpected value returned by try_from"); };
  }

Running the tests with cargo will show six shining tests passing. But we would like to go a step beyond. We have put some, admittedly not much, effort into having our custom error type and we would like to check that the right variant –there might be more in the future– with the right associated data is returned.

We only have to make a small change to the current test and capture the error in the less else pattern match.

  let Err(error) = result else { panic!("Unexpected value returned by try_from"); };

Then we can use this value to compare it to our expectations, including the associated data. We can use the matches! macro for that purpose. I have been waiting forever for the assert_matches! macro to be available in the stable Rust version, but at the moment it is a nightly-only feature. Bummer!

  assert!(
      matches!(error, EvilError::ParseError { purpose, reason } if purpose =="full_name" && reason == "Too few arguments")
  )

We run this new version with cargo t and we will have tests that include checking the error that are passing.