chore(tests): add pattern-based string matching tests and update method expectations (#107)

Signed-off-by: Erik Olsson <olsson.erik1993@gmail.com>

Author: mangila

lib/src/main/java/io/github/mangila/ensure4j/Ensure.java

@@ -4,6 +4,7 @@
 import java.util.Collection;
 import java.util.Map;
 import java.util.function.Supplier;
+import java.util.regex.Pattern;
 import org.intellij.lang.annotations.RegExp;
 import org.jetbrains.annotations.Contract;
 
@@ -1671,6 +1672,62 @@ public static String matches(
     return EnsureStringOps.matches(string, regex, exceptionSupplier);
   }
 
+  /**
+   * Ensures that the provided string matches the specified pattern.
+   *
+   * @param string the string to check
+   * @param pattern the pattern to match against
+   * @return the provided string if it matches the pattern
+   * @throws EnsureException if the string is {@code null} or does not match the pattern, with the
+   *     message {@code "string must match pattern %s"}
+   * @see #matches(String, Pattern, String)
+   * @see #matches(String, Pattern, Supplier)
+   */
+  @Contract("null, _ -> fail; !null, _ -> param1")
+  public static String matches(String string, Pattern pattern) {
+    return Ensure.matches(
+        string,
+        pattern,
+        EnsureStringOps.STRING_MUST_MATCH_REGEX_FORMAT.formatted(
+            pattern == null ? "null" : pattern.pattern()));
+  }
+
+  /**
+   * Ensures that the provided string matches the specified pattern.
+   *
+   * @param string the string to check
+   * @param pattern the pattern to match against
+   * @param exceptionMessage the message to include in the exception if validation fails
+   * @return the provided string if it matches the pattern
+   * @throws EnsureException if the string is {@code null} or does not match the pattern, with the
+   *     provided message
+   * @see #matches(String, Pattern)
+   * @see #matches(String, Pattern, Supplier)
+   */
+  @Contract("null, _, _ -> fail; !null, _, _ -> param1")
+  public static String matches(String string, Pattern pattern, String exceptionMessage) {
+    return Ensure.matches(string, pattern, () -> EnsureException.from(exceptionMessage));
+  }
+
+  /**
+   * Ensures that the provided string matches the specified pattern.
+   *
+   * @param string the string to check
+   * @param pattern the pattern to match against
+   * @param exceptionSupplier the supplier that provides the exception to be thrown if validation
+   *     fails
+   * @return the provided string if it matches the pattern
+   * @throws RuntimeException if the string is {@code null} or does not match the pattern; the
+   *     thrown exception is provided by {@code exceptionSupplier}
+   * @see #matches(String, Pattern)
+   * @see #matches(String, Pattern, String)
+   */
+  @Contract("null, _, _ -> fail; !null, _, _ -> param1")
+  public static String matches(
+      String string, Pattern pattern, Supplier<? extends RuntimeException> exceptionSupplier) {
+    return EnsurePatternOps.matches(string, pattern, exceptionSupplier);
+  }
+
   /**
    * Ensures that the provided string matches the alphanumeric pattern (including spaces).
    *

lib/src/main/java/io/github/mangila/ensure4j/EnsurePatternOps.java

@@ -14,6 +14,7 @@ final class EnsurePatternOps {
   static final String STRING_MUST_MATCH_EMAIL_MESSAGE = "string must match email pattern";
   static final String STRING_MUST_MATCH_ALPHANUMERIC_MESSAGE =
       "string must match alphanumeric pattern";
+  static final String PATTERN_MUST_NOT_BE_NULL_MESSAGE = "pattern must not be null";
 
   /**
    * While RFC 5322 is notoriously complex, this is a highly reliable, performant pattern for 99.9%
@@ -29,6 +30,17 @@ private EnsurePatternOps() {
     throw new AssertionError("No Ensure4j for you!");
   }
 
+  static String matches(
+      String string, Pattern pattern, Supplier<? extends RuntimeException> exceptionSupplier) {
+    if (pattern == null) {
+      throw EnsureException.from(PATTERN_MUST_NOT_BE_NULL_MESSAGE);
+    }
+    if (!EnsureUtils.matches(string, pattern)) {
+      throw getSupplierOrThrow(exceptionSupplier);
+    }
+    return string;
+  }
+
   /**
    * Ensures that the provided string matches the alphanumeric pattern (including spaces).
    *
@@ -41,7 +53,7 @@ private EnsurePatternOps() {
    */
   static String matchesAlphanumeric(
       String string, Supplier<? extends RuntimeException> exceptionSupplier) {
-    if (!EnsureUtils.isAlphanumeric(string)) {
+    if (!EnsureUtils.matches(string, ALPHANUMERIC_PATTERN)) {
       throw getSupplierOrThrow(exceptionSupplier);
     }
 
@@ -60,7 +72,7 @@ static String matchesAlphanumeric(
    */
   static String matchesEmail(
       String string, Supplier<? extends RuntimeException> exceptionSupplier) {
-    if (!EnsureUtils.isEmail(string)) {
+    if (!EnsureUtils.matches(string, EMAIL_PATTERN)) {
       throw getSupplierOrThrow(exceptionSupplier);
     }
 

lib/src/main/java/io/github/mangila/ensure4j/EnsureUtils.java

@@ -5,6 +5,7 @@
 import java.util.Collection;
 import java.util.Map;
 import java.util.function.Supplier;
+import java.util.regex.Pattern;
 import org.intellij.lang.annotations.RegExp;
 
 final class EnsureUtils {
@@ -104,11 +105,7 @@ static boolean isNegativeWithZero(long value) {
     return value <= 0;
   }
 
-  static boolean isAlphanumeric(String string) {
-    return string != null && EnsurePatternOps.ALPHANUMERIC_PATTERN.matcher(string).matches();
-  }
-
-  public static boolean isEmail(String string) {
-    return string != null && EnsurePatternOps.EMAIL_PATTERN.matcher(string).matches();
+  static boolean matches(String string, Pattern pattern) {
+    return string != null && pattern.matcher(string).matches();
   }
 }

lib/src/test/java/io/github/mangila/ensure4j/EnsureArchitectureTest.java

@@ -74,7 +74,7 @@ void shouldVerifyEnsure() {
               @Override
               public void check(JavaClass item, ConditionEvents events) {
                 final long count = getMethodCount(item);
-                final long expectedMethodCount = 102;
+                final long expectedMethodCount = 105;
                 assertThat(count)
                     .as(
                         "Expected methods: %s - %s"

lib/src/test/java/io/github/mangila/ensure4j/EnsurePatternOpsTest.java

@@ -3,6 +3,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
+import java.util.regex.Pattern;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 
@@ -15,7 +16,51 @@ public Class<EnsurePatternOps> clazz() {
 
   @Override
   public long expectedMethodCount() {
-    return 2;
+    return 3;
+  }
+
+  @Test
+  @DisplayName("matches should return string when it matches pattern")
+  void matchesShouldReturnStringWhenItMatchesPattern() {
+    String value = "test";
+    Pattern pattern = Pattern.compile("^t.*t$");
+    assertThat(Ensure.matches(value, pattern)).isEqualTo(value);
+  }
+
+  @Test
+  @DisplayName("matches should throw exception when it does not match pattern")
+  void matchesShouldThrowExceptionWhenItDoesNotMatchPattern() {
+    Pattern pattern = Pattern.compile("^abc$");
+    assertThatThrownBy(() -> Ensure.matches("test", pattern))
+        .isInstanceOf(EnsureException.class)
+        .hasMessage("string must match regex: ^abc$");
+  }
+
+  @Test
+  @DisplayName("matches should throw exception with custom message")
+  void matchesShouldThrowExceptionWithCustomMessage() {
+    Pattern pattern = Pattern.compile("^abc$");
+    assertThatThrownBy(() -> Ensure.matches("test", pattern, "custom message"))
+        .isInstanceOf(EnsureException.class)
+        .hasMessage("custom message");
+  }
+
+  @Test
+  @DisplayName("matches should throw custom exception")
+  void matchesShouldThrowCustomException() {
+    Pattern pattern = Pattern.compile("^abc$");
+    assertThatThrownBy(
+            () -> Ensure.matches("test", pattern, () -> new IllegalArgumentException("custom")))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessage("custom");
+  }
+
+  @Test
+  @DisplayName("matches should throw exception when pattern is null")
+  void matchesShouldThrowExceptionWhenPatternIsNull() {
+    assertThatThrownBy(() -> Ensure.matches("test", (Pattern) null))
+        .isInstanceOf(EnsureException.class)
+        .hasMessage("pattern must not be null");
   }
 
   @Test

lib/src/test/java/io/github/mangila/ensure4j/EnsureStringOpsTest.java

@@ -252,7 +252,7 @@ void matchesShouldThrowCustomException() {
   @Test
   @DisplayName("matches should throw exception when regex is null")
   void matchesShouldThrowExceptionWhenRegexIsNull() {
-    assertThatThrownBy(() -> Ensure.matches("test", null))
+    assertThatThrownBy(() -> Ensure.matches("test", (String) null))
         .isInstanceOf(EnsureException.class)
         .hasMessage("regex must not be null");
   }