String parser/verifier for well-known formats

[mohamnag]

I'm testing a REST API which returns ISO8601 serialized date and times in JSON using hamcrest matchers combined with JsonPath. Current situation is that if a date has to be verified, it must first be parsed and then the matcher in this library can be used for verification.

If this package provided some matchers which accepted String as input and verified a well-known format and additionally accepted further matchers which operate on specific date and time formats, a far better testing code could be written.

As an example imagine response contains a JSON string that has a ISO 8601 date and time under key timestamp, this could be verified like:

assertThat(response, 
    hasJsonPath("$.timestamp", 
        isIso8601DateAndTime(
            within(1, DAY, ZonedDateTime.now()))))

every piece here is already provided by either hamcrest core, JsonPath or this library but not the Matcher<String> isIso8601DateAndTime.

[stewbis]

Hi, sorry I didn't get around to reading this issue when you first raised in 6 months ago :-(. My initial thought was that the date parsing is not really a core part of this library so may be best implemented as a further add-in. However, I think this could fit in if a new Matcher was added for text dates e.g. TextDateMatchers. It could support parsing of default formats but be configurable to use custom formats e.g. in the example below the TextDateMatchers.after factory method would assume a date format because it's being compared against a LocalDate.

assertThat("2019-09-24", TextDateMatchers.after(LocalDate.now())

A further example but being configured could follow this pattern;

assertThat("2019-09-24", TextDateMatchers.after(LocalDate.now()).fromPattern('yyyy-MM-dd'))

or perhaps;

assertThat("2019-09-24", TextDateMatchers.fromPattern('yyyy-MM-dd').after(LocalDate.now())

At the moment I don't have the spare time to add the TextDateMatcher but I may do at a later date. Feel free to develop it yourself, for a partial implementation and raise a PR for review

[wh81752]

A very useful feature request, making lot of sense.

I really want to ensure that a given string value (via JSON for example) complies first and foremost with a certain agreed time format and only after that, that the time is within a certain range.

Probably not to difficult to implement with a custom Hamcrest matcher. However, looks to my like a logic extension that a given "time" object is not only expected as a java time object (localtime, instant, whatsoever) but that "1970-01-01T00:00:00Z" pretty equally represents a point of time as Instant.EPOCH does.

[darkrymit]

I am not sure if it is appropriate to comment but I solved a similar problem using a few additional classes and I guess a similar approach can be used to integrate the existing functional of the library with parsing of string functionality

TemporalStringMatcher

public class TemporalStringMatcher<T extends Temporal> extends TypeSafeMatcher<String> {

  private final Function<String, T> parser;
  private final Matcher<T> matcher;

  public TemporalStringMatcher(Function<String, T> parser, Matcher<T> matcher) {
    this.parser = parser;
    this.matcher = matcher;
  }

  @Override
  protected boolean matchesSafely(String item) {
    try {
      return this.matcher.matches(this.parser.apply(item));
    } catch (Exception e) {
      return false;
    }
  }

  @Override
  protected void describeMismatchSafely(String item, Description mismatchDescription) {
    T parsedTemporal = null;
    try {
      parsedTemporal = this.parser.apply(item);
    } catch (Exception e) {
      mismatchDescription.appendText("was not a parsable temporal (").appendValue(item)
          .appendText(")").appendText(" because we got an exception: ").appendValue(e);
      if (e.getCause() != null) {
        mismatchDescription.appendText(" and cause: ").appendValue(e.getCause());
      }
      return;
    }

    if (parsedTemporal == null) {
      mismatchDescription.appendText("got null instead of temporal for value (").appendValue(item)
          .appendText(")");
    }
    this.matcher.describeMismatch(parsedTemporal, mismatchDescription);
  }

  @Override
  public void describeTo(Description description) {
    description.appendText("a string representing a temporal that is ")
        .appendDescriptionOf(this.matcher);
  }
}

TemporalStringMatchers

public class TemporalStringMatchers {

  public static TemporalStringMatcher<Instant> instantThat(Matcher<Instant> instantMatcher) {
    return new TemporalStringMatcher<>(Instant::parse, instantMatcher);
  }

  public static TemporalStringMatcher<Instant> instantThat(Matcher<Instant> instantMatcher,
      Function<String, Instant> parser) {
    return new TemporalStringMatcher<>(parser, instantMatcher);
  }

  public static TemporalStringMatcher<Instant> instantComparesEqualTo(Instant instant) {
    return new TemporalStringMatcher<>(Instant::parse, OrderingComparison.comparesEqualTo(instant));
  }

  public static TemporalStringMatcher<Instant> instantComparesEqualTo(Instant instant,
      Function<String, Instant> parser) {
    return new TemporalStringMatcher<>(parser, OrderingComparison.comparesEqualTo(instant));
  }
}

Usage with spring mockMvc

.andExpect(jsonPath("$.createdAt", instantComparesEqualTo(response.getCreatedAt())))