From 5a6eba33ce8c183a0add56b5e035526370b1c344 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Thu, 31 Aug 2017 19:32:17 +0200 Subject: [PATCH 1/6] Add law testing guide --- build.sbt | 2 +- docs/src/main/tut/typeclasses/lawtesting.md | 146 ++++++++++++++++++++ 2 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 docs/src/main/tut/typeclasses/lawtesting.md diff --git a/build.sbt b/build.sbt index c0b5f657f9..5e5e324db5 100644 --- a/build.sbt +++ b/build.sbt @@ -181,7 +181,7 @@ lazy val docs = project .settings(noPublishSettings) .settings(docSettings) .settings(commonJvmSettings) - .dependsOn(coreJVM, freeJVM) + .dependsOn(coreJVM, freeJVM, kernelLawsJVM, lawsJVM, testkitJVM) lazy val cats = project.in(file(".")) .settings(moduleName := "root") diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md new file mode 100644 index 0000000000..67e195f266 --- /dev/null +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -0,0 +1,146 @@ +# Law testing + +Laws are an important part of cats. +They help us enforce constraints that we usually assume to be true and give us guarantees that our code does what we think it does. +Manually testing each data type to adhere to each of its type class instances can be quite cumbersome. +Thankfully cats comes with the `cats-testkit`, which makes it a lot easier to write tests for type class instances using laws. + + +## Getting started + +First up, you will need to specify dependencies on `cats-laws` and `cats-testkit` in your `build.sbt` file. +To make things easier, we'll also include the `scalacheck-shapeless` library in this tutorial, so we don't have to manually write instances for ScalaCheck's `Arbitrary`. + +```scala +libraryDependencies ++= Seq( + "org.typelevel" %% "cats-laws" % "1.0.0-MF" % Test, + "org.typelevel" %% "cats-testkit" % "1.0.0-MF"% Test, + "com.github.alexarchambault" %% "scalacheck-shapeless_1.13" % "1.1.5" % Test +) +``` + +## Example: Testing a Functor instance + +We'll begin by creating a data type and its Functor instance. +```tut:book +import cats._ + +sealed trait Tree[+A] +case object Leaf extends Tree[Nothing] +case class Node[A](p: A, left: Tree[A], right: Tree[A]) extends Tree[A] + +object Tree { + implicit val functorTree: Functor[Tree] = new Functor[Tree] { + def map[A, B](tree: Tree[A])(f: A => B) = tree match { + case Leaf => Leaf + case Node(p, left, right) => Node(f(p), map(left)(f), map(right)(f)) + } + } +} +``` +We will also need to create an `Eq` instance, as most laws will need to compare values of a type to properly test for correctness. +For simplicity we'll just use `Eq.fromUniversalEquals`: + +```tut:book +implicit def eqTree[A: Eq]: Eq[Tree[A]] = Eq.fromUniversalEquals +``` + +Then we can begin to write our law tests. Start by creating a new class in your `test` folder and inheriting from `cats.tests.CatsSuite`. +`CatsSuite` extends the standard ScalaTest `FunSuite` as well as `Matchers`. +Furthermore it also pulls in all of cats instances and syntax, so there's no need to import from `cats.implicits._`. + +```tut:book +import cats.tests.CatsSuite + +class TreeLawTests extends CatsSuite { + +} +``` + +The key to testing laws is the `checkAll` function, which takes a name for your test and a Discipline ruleset. +Cats has defined rulesets for all type class laws in `cats.laws.discipline.*`. + +So for our example we will want to import `cats.laws.discipline.FunctorTests` and call `checkAll` with it. +Before we do so, however, +we will have to bring our instances into scope as well as the derived `Arbitrary` instances from `scalacheck-shapeless`: + + +```tut:silent +import Tree._ +``` +```scala +import org.scalacheck.Shapeless._ +``` + +```tut:invisible +import org.scalacheck.{Arbitrary, Gen} +implicit def arbFoo[A: Arbitrary]: Arbitrary[Tree[A]] = + Arbitrary(Gen.oneOf(Gen.const(Leaf), (for { + e <- Arbitrary.arbitrary[A] + } yield Node(e, Leaf, Leaf).asInstanceOf[Tree[A]])) + ) +``` + +```tut:book +import cats.laws.discipline.FunctorTests + +class TreeLawTests extends CatsSuite { + checkAll("Tree.FunctorLaws", FunctorTests[Tree].functor[Int, Int, String]) +} +``` + +Now when we run `test` in our sbt console, ScalaCheck will test if the `Functor` laws hold for our `Tree` type. +You should see something like this: + +``` +[info] TreeLawTests: +[info] - Tree.FunctorLaws.functor.covariant composition +[info] - Tree.FunctorLaws.functor.covariant identity +[info] - Tree.FunctorLaws.functor.invariant composition +[info] - Tree.FunctorLaws.functor.invariant identity +[info] ScalaTest +[info] Run completed in 537 milliseconds. +[info] Total number of tests run: 4 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 4, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[info] Passed: Total 4, Failed 0, Errors 0, Passed 4 +[success] Total time: 1 s, completed Aug 31, 2017 2:19:22 PM +``` + +And voila, you've successfully proven that your data type upholds the Functor laws! + +### Testing cats.kernel instances + +For most of the type classes included in cats, the above will work great. +However, the law tests for the type classes inside `cats.kernel` are structured a bit differently. +These include `Semigroup`, `Monoid`, `Group` and `Semilattice`. +Instead of importing the laws from `cats.laws.discipline.*`, we have to import `cats.kernel.laws.GroupLaws` +and then call the corresponding method, e.g. `GroupLaws[Foo].monoid`, or `GroupLaws[Foo].semigroup`. + +Let's test it out, by defining a `Semigroup` instance for our `Tree` type. + +```tut:book +import cats.implicits._ + +implicit def semigroupTree[A: Semigroup]: Semigroup[Tree[A]] = new Semigroup[Tree[A]] { + def combine(x: Tree[A], y: Tree[A]) = (x, y) match { + case (Leaf, _) => Leaf + case (_, Leaf) => Leaf + case (Node(xp, xLeft, xRight), Node(yp, yLeft, yRight)) => + Node(xp |+| yp, xLeft |+| yLeft, xRight |+| yRight) + } +} +``` + +Then we can again test the instance inside our class extending `CatsSuite`: + +```tut:book +import cats.laws.discipline.FunctorTests +import cats.kernel.laws.GroupLaws + +class TreeLawTests extends CatsSuite { + checkAll("Tree[Int].MonoidLaws", GroupLaws[Tree[Int]].semigroup) + checkAll("Tree.FunctorLaws", FunctorTests[Tree].functor[Int, Int, String]) +} +``` From 49096d440a927200569b5af76b6f05b023f8c5fa Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 1 Sep 2017 15:37:34 +0200 Subject: [PATCH 2/6] Link to typeclasses law section --- docs/src/main/tut/typeclasses/lawtesting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md index 67e195f266..5958ac7783 100644 --- a/docs/src/main/tut/typeclasses/lawtesting.md +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -1,6 +1,6 @@ # Law testing -Laws are an important part of cats. +[Laws](https://typelevel.org/cats/typeclasses.html#laws) are an important part of cats. They help us enforce constraints that we usually assume to be true and give us guarantees that our code does what we think it does. Manually testing each data type to adhere to each of its type class instances can be quite cumbersome. Thankfully cats comes with the `cats-testkit`, which makes it a lot easier to write tests for type class instances using laws. From 1036a4c87be3badfd071d38aed285be38cffa155 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 1 Sep 2017 16:56:10 +0200 Subject: [PATCH 3/6] Simplify begining --- docs/src/main/tut/typeclasses/lawtesting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md index 5958ac7783..4b05fbf69d 100644 --- a/docs/src/main/tut/typeclasses/lawtesting.md +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -1,9 +1,8 @@ # Law testing [Laws](https://typelevel.org/cats/typeclasses.html#laws) are an important part of cats. -They help us enforce constraints that we usually assume to be true and give us guarantees that our code does what we think it does. -Manually testing each data type to adhere to each of its type class instances can be quite cumbersome. -Thankfully cats comes with the `cats-testkit`, which makes it a lot easier to write tests for type class instances using laws. +Cats uses `catalysts` and `discipline` to help test instances with laws. +To make things easier, cats ships with `cats-testkit`, which makes use of `catalysts` and `discipline` and exposes `CatsSuite` based on ScalaTest. ## Getting started From c0eba6cd9aeb046166d15130a441ae047ce88979 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 1 Sep 2017 16:58:50 +0200 Subject: [PATCH 4/6] Add scalacheck-shapeless as local dependency for law testing --- build.sbt | 1 + docs/src/main/tut/typeclasses/lawtesting.md | 16 ++-------------- 2 files changed, 3 insertions(+), 14 deletions(-) diff --git a/build.sbt b/build.sbt index 5e5e324db5..23ca33318b 100644 --- a/build.sbt +++ b/build.sbt @@ -181,6 +181,7 @@ lazy val docs = project .settings(noPublishSettings) .settings(docSettings) .settings(commonJvmSettings) + .settings(libraryDependencies += "com.github.alexarchambault" %% "scalacheck-shapeless_1.13" % "1.1.5" % Compile) .dependsOn(coreJVM, freeJVM, kernelLawsJVM, lawsJVM, testkitJVM) lazy val cats = project.in(file(".")) diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md index 4b05fbf69d..413dcb5eb5 100644 --- a/docs/src/main/tut/typeclasses/lawtesting.md +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -64,23 +64,11 @@ Before we do so, however, we will have to bring our instances into scope as well as the derived `Arbitrary` instances from `scalacheck-shapeless`: -```tut:silent +```tut:book import Tree._ -``` -```scala -import org.scalacheck.Shapeless._ -``` -```tut:invisible -import org.scalacheck.{Arbitrary, Gen} -implicit def arbFoo[A: Arbitrary]: Arbitrary[Tree[A]] = - Arbitrary(Gen.oneOf(Gen.const(Leaf), (for { - e <- Arbitrary.arbitrary[A] - } yield Node(e, Leaf, Leaf).asInstanceOf[Tree[A]])) - ) -``` +import org.scalacheck.Shapeless._ -```tut:book import cats.laws.discipline.FunctorTests class TreeLawTests extends CatsSuite { From bb783770d69944a1d4803590f72b37457a751fb2 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Mon, 4 Sep 2017 15:14:33 +0200 Subject: [PATCH 5/6] Revert "Add scalacheck-shapeless as local dependency for law testing" This reverts commit c0eba6cd9aeb046166d15130a441ae047ce88979. --- build.sbt | 1 - docs/src/main/tut/typeclasses/lawtesting.md | 16 ++++++++++++++-- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/build.sbt b/build.sbt index 23ca33318b..5e5e324db5 100644 --- a/build.sbt +++ b/build.sbt @@ -181,7 +181,6 @@ lazy val docs = project .settings(noPublishSettings) .settings(docSettings) .settings(commonJvmSettings) - .settings(libraryDependencies += "com.github.alexarchambault" %% "scalacheck-shapeless_1.13" % "1.1.5" % Compile) .dependsOn(coreJVM, freeJVM, kernelLawsJVM, lawsJVM, testkitJVM) lazy val cats = project.in(file(".")) diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md index 413dcb5eb5..4b05fbf69d 100644 --- a/docs/src/main/tut/typeclasses/lawtesting.md +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -64,11 +64,23 @@ Before we do so, however, we will have to bring our instances into scope as well as the derived `Arbitrary` instances from `scalacheck-shapeless`: -```tut:book +```tut:silent import Tree._ - +``` +```scala import org.scalacheck.Shapeless._ +``` + +```tut:invisible +import org.scalacheck.{Arbitrary, Gen} +implicit def arbFoo[A: Arbitrary]: Arbitrary[Tree[A]] = + Arbitrary(Gen.oneOf(Gen.const(Leaf), (for { + e <- Arbitrary.arbitrary[A] + } yield Node(e, Leaf, Leaf).asInstanceOf[Tree[A]])) + ) +``` +```tut:book import cats.laws.discipline.FunctorTests class TreeLawTests extends CatsSuite { From c8c4328b0354456dcec357da35c520e1cf8b588e Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Mon, 4 Sep 2017 15:26:21 +0200 Subject: [PATCH 6/6] Make Tree arbitrary instance visible --- docs/src/main/tut/typeclasses/lawtesting.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/src/main/tut/typeclasses/lawtesting.md b/docs/src/main/tut/typeclasses/lawtesting.md index 4b05fbf69d..b8f1e4c490 100644 --- a/docs/src/main/tut/typeclasses/lawtesting.md +++ b/docs/src/main/tut/typeclasses/lawtesting.md @@ -61,26 +61,25 @@ Cats has defined rulesets for all type class laws in `cats.laws.discipline.*`. So for our example we will want to import `cats.laws.discipline.FunctorTests` and call `checkAll` with it. Before we do so, however, -we will have to bring our instances into scope as well as the derived `Arbitrary` instances from `scalacheck-shapeless`: +we will have to bring our instances into scope as well as the derived `Arbitrary` instances from `scalacheck-shapeless` +(We have defined an Arbitrary instance for `Tree` here, but you won't need it if you import `org.scalacheck.Shapeless._`). + ```tut:silent -import Tree._ -``` -```scala -import org.scalacheck.Shapeless._ -``` -```tut:invisible import org.scalacheck.{Arbitrary, Gen} + implicit def arbFoo[A: Arbitrary]: Arbitrary[Tree[A]] = Arbitrary(Gen.oneOf(Gen.const(Leaf), (for { e <- Arbitrary.arbitrary[A] - } yield Node(e, Leaf, Leaf).asInstanceOf[Tree[A]])) + } yield Node(e, Leaf, Leaf))) ) ``` ```tut:book +import Tree._ + import cats.laws.discipline.FunctorTests class TreeLawTests extends CatsSuite {