Merge pull request #226 from LaurenceWarne/create-match-or-fail-fast

Create matchOrFailFast utility

Author: zainab-ali

docs/features/expectations.md

@@ -112,6 +112,18 @@ val list = List(1)
   } yield expect(y.contains(x))
   ```
 
+- Similarly `matchOrFailFast` can be used assert an expression matches a given pattern, and return it if so
+
+  ```scala mdoc:compile-only
+  for {
+    b <- IO(Some(4))
+    s <- matchOrFailFast[IO](b) {
+      case Some(v) => v.toString    
+    }
+    c <- IO("4")
+  } yield expect.eql(s, c)
+  ```
+
 ## Example suite 
 
 ```scala mdoc
@@ -221,6 +233,19 @@ object ExpectationsSuite extends SimpleIOSuite {
       _ <- expect(clue(h).isEmpty).failFast
     } yield success
   }
+
+  test("Failing fast match") {
+    for {
+      h <- IO.pure(Some(4))
+      x <- matchOrFailFast[IO](h) {
+        case Some(v) => v
+      }
+      g <- IO.pure(Option.empty[Int])
+      y <- matchOrFailFast[IO](g) {
+        case Some(v) => v
+      }
+    } yield expect.eql(x, y)
+  }
 }
 ```
 

modules/core/shared/src/main/scala/weaver/Expectations.scala

@@ -157,6 +157,24 @@ object Expectations {
           ))
     }
 
+  final private[weaver] class PartiallyAppliedMatchOrFailFast[F[_]](
+      val dummy: Boolean = true)
+      extends AnyVal {
+    def apply[A, B](x: A)(
+        pf: PartialFunction[A, B]
+    )(
+        implicit loc: SourceLocation,
+        F: Sync[F],
+        A: Show[A] = Show.fromToString[A]): F[B] =
+      pf.lift(x).fold[F[B]] {
+        Sync[F].raiseError(
+          new ExpectationFailed(
+            "Pattern did not match, got: " + x.show,
+            NonEmptyList.of(loc)
+          ))
+      }(Sync[F].pure)
+  }
+
   trait Helpers extends weaver.internals.ClueHelpers {
 
     /**
@@ -231,6 +249,25 @@ object Expectations {
       else
         failure("Pattern did not match, got: " + x.show)
 
+    /**
+     * Checks that a given expression matches a certain pattern, returning the
+     * result of the partial function <code>pf</code> if so, fails otherwise.
+     *
+     * @example
+     *   {{{
+     *     val x = Some(4)
+     *     val otherSideEffect = IO.pure("4")
+     *     for {
+     *       b <- matchOrFailFast[IO](x) {
+     *         case Some(v) => v.toString
+     *       }
+     *       c <- otherSideEffect
+     *     } yield expect.eql(b, c)
+     *   }}}
+     */
+    def matchOrFailFast[F[_]]: PartiallyAppliedMatchOrFailFast[F] =
+      new PartiallyAppliedMatchOrFailFast[F]
+
     /**
      * Alias for `forEach`
      */

modules/framework-cats/shared/src/test/scala/ExpectationsTests.scala

@@ -2,6 +2,7 @@ package weaver
 package framework
 package test
 
+import cats.effect.IO
 import cats.kernel.Eq
 
 object ExpectationsTests extends SimpleIOSuite {
@@ -61,6 +62,24 @@ object ExpectationsTests extends SimpleIOSuite {
       })
   }
 
+  test("matchOrFailFast (success)") {
+    matchOrFailFast[IO](Some(4)) {
+      case Some(v) => v
+    }.as(success)
+  }
+
+  test("matchOrFailFast (failure)") {
+    matchOrFailFast[IO](Option.empty[Int]) {
+      case Some(v) => v
+    }
+      .attempt
+      .map { either =>
+        matches(either) { case Left(_: ExpectationFailed) =>
+          success
+        }
+      }
+  }
+
   pureTest("expect.eql respects cats.kernel.Eq") {
     implicit val eqInt: Eq[Int] = Eq.allEqual
     expect.eql(0, 1)