Implement assertGoldenFile and assertGoldenLiteral tests (#394)

lihaoyi · web-flow · commit 674f82dce15a · 2025-07-28T16:39:42.000+08:00
This PR implements `assertGoldenLiteral` and `assertGoldenFile`, which are assertions that not only compare the given values (literal v.s. literal or string v.s. file contents respectively), but can take the `UTEST_UPDATE_GOLDEN_TESTS` environment variable to automatically update the source code and golden files to new values. - `assertGoldenFile` is straightforward: if the contents of the specified file does not match the given string, `UTEST_UPDATE_GOLDEN_TESTS` makes utest over-write that file with the given string. - `assertGoldenLiteral` is more tricky: this takes a new `utest.framework.GoldenFix.Span[T]` implicit conversion similar to `sourcecode.Text`, but instead of just capturing the text contents of the expression it captures the sourcefile and the start/end offset of the literal within it. If the two values do not match, `UTEST_UPDATE_GOLDEN_TESTS` makes utest use `utest.shaded.pprint.apply` to pretty-print the given expression and the sourcefile/start/end metadata to over-write the original source file in-place. Some extra book-keeping is necessary to make sure the offsets line up even when there are multiple edits in the same file, and to ensure the indentation of start of the expression is preserved Inspired by Jane Street's https://blog.janestreet.com/the-joy-of-expect-tests/[What if writing tests was a joyful experience?] blog post
diff --git a/utest/src-2-jvm/utest/framework/GoldenSpanMacros.scala b/utest/src-2-jvm/utest/framework/GoldenSpanMacros.scala
@@ -0,0 +1,36 @@
+package utest.framework
+
+import scala.language.experimental.macros
+import scala.reflect.internal.util.RangePosition
+
+trait GoldenSpanMacros {
+  implicit def generate[T](v: T): GoldenFix.Span[T] = macro GoldenSpanMacros.text[T]
+
+  def apply[T](v: T): GoldenFix.Span[T] = macro GoldenSpanMacros.text[T]
+}
+
+object GoldenSpanMacros {
+  object Compat {
+    type Context = scala.reflect.macros.blackbox.Context
+
+    def enclosingOwner(c: Context) = c.internal.enclosingOwner
+
+    def enclosingParamList(c: Context): List[List[c.Symbol]] = {
+      def nearestEnclosingMethod(owner: c.Symbol): c.Symbol =
+        if (owner.isMethod) owner
+        else if (owner.isClass) owner.asClass.primaryConstructor
+        else nearestEnclosingMethod(owner.owner)
+
+      nearestEnclosingMethod(enclosingOwner(c)).asMethod.paramLists
+    }
+  }
+  def text[T: c.WeakTypeTag](c: Compat.Context)(v: c.Expr[T]): c.Expr[GoldenFix.Span[T]] = {
+    import c.universe._
+    val (start, end) = if (v.tree.pos.isInstanceOf[RangePosition]) {
+      val r = v.tree.pos.asInstanceOf[RangePosition]
+      (r.start, r.end)
+    } else (-1, -1)
+    val tree = q"""${c.prefix}(${v.tree}, ${v.tree.pos.source.path}, $start, $end)"""
+    c.Expr[GoldenFix.Span[T]](tree)
+  }
+}
diff --git a/utest/src-2-jvm/utest/framework/PlatformShims.scala b/utest/src-2-jvm/utest/framework/PlatformShims.scala
@@ -1,7 +1,4 @@
-package utest
-
-import scala.concurrent.{Await, Future}
-import concurrent.duration._
+package utest.framework
 
 /**
  * Platform specific stuff that differs between JVM and JS
diff --git a/utest/src-2/utest/asserts/Asserts.scala b/utest/src-2/utest/asserts/Asserts.scala
@@ -1,7 +1,6 @@
 package utest
 package asserts
 //import acyclic.file
-import utest.framework.StackMarker
 
 import scala.annotation.{StaticAnnotation, tailrec}
 import scala.collection.mutable
@@ -134,12 +133,6 @@ trait AssertsVersionSpecific {
     */
   def assertCompileError(expr: String): CompileError = macro Asserts.assertCompileError
 
-  /**
-   * Forwarder for `Predef.assert`, for when you want to explicitly write the
-   * assert message and don't want or need the fancy smart asserts
-   */
-  def assert(expr: Boolean, msg: => Any) = Predef.assert(expr, msg)
-
   /**
    * Checks that the expression is true; otherwise raises an
    * exception with some debugging info
@@ -175,5 +168,6 @@ trait AssertsVersionSpecific {
     * exception does not appear.
     */
   def assertThrows[T: ClassTag](expr: Unit): T = macro Asserts.assertThrowsProxy[T]
+
 }
 
diff --git a/utest/src-3-jvm/utest/framework/EnableReflectiveInstantiation.java b/utest/src-3-jvm/utest/framework/EnableReflectiveInstantiation.java
@@ -1,4 +1,4 @@
-package utest;
+package utest.framework;
 
 import java.lang.annotation.*;
 
diff --git a/utest/src-3-jvm/utest/framework/GoldenSpanMacros.scala b/utest/src-3-jvm/utest/framework/GoldenSpanMacros.scala
@@ -0,0 +1,24 @@
+package utest.framework
+
+import scala.language.implicitConversions
+import scala.quoted.*
+
+
+trait GoldenSpanMacros {
+  inline implicit def generate[T](v: => T): GoldenFix.Span[T] = ${ GoldenSpanMacros.text('v) }
+  inline def apply[T](v: => T): GoldenFix.Span[T] = ${ GoldenSpanMacros.text('v) }
+}
+object GoldenSpanMacros {
+  def text[T: Type](v: Expr[T])(using quotes: Quotes): Expr[GoldenFix.Span[T]] = {
+    import quotes.reflect.*
+    '{
+      new GoldenFix.Span[T](
+        $v,
+        ${Expr(v.asTerm.pos.sourceFile.path)},
+        ${Expr(v.asTerm.pos.start)},
+        ${Expr(v.asTerm.pos.end)},
+      )
+    }
+  }
+
+}
diff --git a/utest/src-3-jvm/utest/framework/PlatformShims.scala b/utest/src-3-jvm/utest/framework/PlatformShims.scala
@@ -1,14 +1,11 @@
-package utest
-
-import scala.concurrent.{Await, Future}
-import concurrent.duration._
+package utest.framework
 
 /**
  * Platform specific stuff that differs between JVM and JS
  */
 trait PlatformShimsVersionSpecific {
   type EnableReflectiveInstantiation =
-    utest.EnableReflectiveInstantiation
+    utest.framework.EnableReflectiveInstantiation
 
   val Reflect = PortableScalaReflectExcerpts
 }
diff --git a/utest/src-3-jvm/utest/framework/PortableScalaReflectExcerpts.scala b/utest/src-3-jvm/utest/framework/PortableScalaReflectExcerpts.scala
@@ -1,6 +1,6 @@
-package utest
+package utest.framework
 
-import java.lang.reflect._
+import java.lang.reflect.*
 import scala.collection.mutable
 
 /**
diff --git a/utest/src-3/utest/asserts/Asserts.scala b/utest/src-3/utest/asserts/Asserts.scala
@@ -70,12 +70,6 @@ trait AssertsVersionSpecific {
     */
   inline def assertAll(inline expr: Boolean*): Unit = ${Asserts.assertAllProxy('expr)}
 
-  /**
-   * Forwarder for `Predef.assert`, for when you want to explicitly write the
-   * assert message and don't want or need the fancy smart asserts
-   */
-  def assert(expr: Boolean, msg: => Any) = Predef.assert(expr, msg)
-
   /**
     * Checks that one or more expressions all become true within a certain
     * period of time. Polls at a regular interval to check this.
diff --git a/utest/src-js/utest/asserts/AssertsPlatformSpecific.scala b/utest/src-js/utest/asserts/AssertsPlatformSpecific.scala
@@ -0,0 +1,5 @@
+package utest.asserts
+
+trait AssertsPlatformSpecific {
+
+}
diff --git a/utest/src-js/utest/framework/PlatformShims.scala b/utest/src-js/utest/framework/PlatformShims.scala
@@ -1,8 +1,9 @@
-package utest
+package utest.framework
 
-import scala.concurrent.Future
 import org.portablescala.reflect.Reflect
 
+import scala.concurrent.Future
+
 /**
  * Platform specific stuff that differs between JVM, JS and Native
  */
diff --git a/utest/src-js/utest/framework/TestSuitePlatformSpecific.scala b/utest/src-js/utest/framework/TestSuitePlatformSpecific.scala
@@ -0,0 +1,9 @@
+package utest.framework
+
+trait TestSuitePlatformSpecific {
+
+}
+
+object TestSuitePlatformSpecific {
+  def processGolden(allSuites: Seq[utest.TestSuite]): Unit = ()
+}
diff --git a/utest/src-jvm/utest/asserts/AssertsPlatformSpecific.scala b/utest/src-jvm/utest/asserts/AssertsPlatformSpecific.scala
@@ -0,0 +1,56 @@
+package utest.asserts
+
+import utest.framework.{GoldenFix}
+import utest.{AssertionError, TestValue}
+import java.nio.file.{Files, Path}
+trait AssertsPlatformSpecific {
+  def assertGoldenFile(testValue: String, path: Path)(implicit reporter: GoldenFix.Reporter): Unit = {
+    val goldenFileContents = if (Files.exists(path)) Files.readString(path) else ""
+    if (goldenFileContents != testValue) {
+      if (!sys.env.contains("UTEST_UPDATE_GOLDEN_TESTS")) {
+        throw new AssertionError(
+          "Value does not match golden file contents: " + path,
+          Seq(
+            TestValue.Equality(
+              TestValue.Single("goldenFileContents", None, goldenFileContents),
+              TestValue.Single("testValue", None, testValue),
+            )
+          )
+        )
+
+      }
+      else {
+        System.err.println("Value does not match golden file contents: " + path)
+        reporter.apply(GoldenFix(path, testValue, 0, goldenFileContents.length))
+      }
+    }
+  }
+
+  def assertGoldenLiteral(testValue: Any, golden: GoldenFix.Span[Any])
+                         (implicit reporter: GoldenFix.Reporter): Unit = {
+    val goldenValue = golden.value
+    if (testValue != goldenValue) {
+      if (!sys.env.contains("UTEST_UPDATE_GOLDEN_TESTS")) {
+        throw new AssertionError(
+          "Value does not match golden literal contents",
+          Seq(
+            TestValue.Equality(
+              TestValue.Single("testValue", None, testValue),
+              TestValue.Single("goldenValue", None, goldenValue),
+            )
+          )
+        )
+      } else {
+        System.err.println("Value does not match golden literal contents in: " + golden.sourceFile)
+        reporter.apply(
+          GoldenFix(
+            Path.of(golden.sourceFile),
+            utest.shaded.pprint.PPrinter.BlackWhite.apply(golden.value).plainText,
+            golden.startOffset,
+            golden.endOffset
+          )
+        )
+      }
+    }
+  }
+}
diff --git a/utest/src-jvm/utest/framework/GoldenFix.scala b/utest/src-jvm/utest/framework/GoldenFix.scala
@@ -0,0 +1,92 @@
+package utest.framework
+
+import scala.collection.mutable.ArrayBuffer
+
+case class GoldenFix(path: java.nio.file.Path,
+                     contents: String,
+                     startOffset: Int,
+                     endOffset: Int)
+
+object GoldenFix {
+  // vendored from
+  // https://github.com/com-lihaoyi/fastparse/blob/d8f95daef21d6e6f9734624237f993f4cebfa881/fastparse/src/fastparse/internal/Util.scala
+  //
+  def lineNumberLookup(data: String): Array[Int] = {
+    val lineStarts = ArrayBuffer[Int](0)
+    var i = 0
+    var col = 1
+    // Stores the previous char we saw, or -1 if we just saw a \r\n or \n\r pair
+    var state: Int = 0
+    while (i < data.length) {
+      val char = data(i)
+      if (char == '\r' && state == '\n' || char == '\n' && state == '\r') {
+        col += 1
+        state = -1
+      } else if (state == '\r' || state == '\n' || state == -1) {
+        lineStarts.append(i)
+        col = 1
+        state = char
+      } else {
+        col += 1
+        state = char
+      }
+
+      i += 1
+    }
+
+    if (state == '\r' || state == '\n' || state == -1) {
+      lineStarts.append(i)
+    }
+
+    lineStarts.toArray
+  }
+
+  def columnLookup(index: Int, lineNumberLookup: Array[Int]): Int = {
+    val line = lineNumberLookup.indexWhere(_ > index) match {
+      case -1 => lineNumberLookup.length - 1
+      case n => math.max(0, n - 1)
+    }
+    index - lineNumberLookup(line)
+  }
+
+  trait Reporter {
+    def apply(v: GoldenFix): Unit
+  }
+
+  def applyAll(fixes: Seq[GoldenFix]): Unit = {
+    for((path, group) <- fixes.groupBy(_.path)){
+      println(s"Applying ${group.size} golden fixes to file $path")
+
+      val text = java.nio.file.Files.readString(path)
+
+      java.nio.file.Files.writeString(path, applyToText(text, group))
+    }
+  }
+
+  def applyToText(text0: String, fixes: Seq[GoldenFix]): String = {
+    var text = text0
+    val sorted = fixes.map(t => t.startOffset -> t).toMap.map(_._2).toSeq.sortBy(_.startOffset)
+    sorted.sliding(2).collect{ case Seq(prev, next) =>
+      Predef.assert(prev.endOffset <= next.startOffset)
+    }
+
+    val lineNumberLookupTable = lineNumberLookup(text)
+    var lengthOffset = 0
+    for (fix <- sorted) {
+      val col = columnLookup(fix.startOffset, lineNumberLookupTable)
+      val indentedContents = fix.contents.linesWithSeparators.mkString(" " * col)
+      text = text.patch(
+        fix.startOffset + lengthOffset, indentedContents,
+        fix.endOffset - fix.startOffset
+      )
+      lengthOffset = lengthOffset + indentedContents.length - (fix.endOffset - fix.startOffset)
+    }
+
+    text
+  }
+
+  case class Span[+T](value: T, sourceFile: String, startOffset: Int, endOffset: Int)
+
+  object Span extends GoldenSpanMacros
+
+}
diff --git a/utest/src-jvm/utest/framework/PlatformShims.scala b/utest/src-jvm/utest/framework/PlatformShims.scala
@@ -1,7 +1,7 @@
-package utest
+package utest.framework
 
+import scala.concurrent.duration._
 import scala.concurrent.{Await, Future}
-import concurrent.duration._
 
 /**
  * Platform specific stuff that differs between JVM, JS and Native
diff --git a/utest/src-jvm/utest/framework/TestSuitePlatformSpecific.scala b/utest/src-jvm/utest/framework/TestSuitePlatformSpecific.scala
@@ -0,0 +1,22 @@
+package utest.framework
+
+trait TestSuitePlatformSpecific {
+  private[utest] val utestGoldenReports = collection.mutable.Buffer.empty[GoldenFix]
+  protected implicit def utestGoldenReporter: GoldenFix.Reporter = fix => utestGoldenReports.synchronized{
+    utestGoldenReports.append(fix)
+  }
+}
+
+object TestSuitePlatformSpecific {
+  def processGolden(allSuites: Seq[utest.TestSuite]): Unit = {
+    println("TestSuitePlatformSpecific.processGolden: " + allSuites.length)
+    if (sys.env.contains("UTEST_UPDATE_GOLDEN_TESTS")) {
+      val goldenFixes = allSuites.flatMap { suite =>
+        suite.utestGoldenReports.synchronized {
+          suite.utestGoldenReports.toList
+        }
+      }
+      GoldenFix.applyAll(goldenFixes)
+    }
+  }
+}
diff --git a/utest/src-native/utest/asserts/AssertsPlatformSpecific.scala b/utest/src-native/utest/asserts/AssertsPlatformSpecific.scala
@@ -0,0 +1,5 @@
+package utest.asserts
+
+trait AssertsPlatformSpecific {
+
+}
diff --git a/utest/src-native/utest/framework/PlatformShims.scala b/utest/src-native/utest/framework/PlatformShims.scala
@@ -1,9 +1,9 @@
-package utest
+package utest.framework
 
 // Taken from the implementation for JS
 
+import scala.concurrent.duration._
 import scala.concurrent.{Await, Future}
-import concurrent.duration._
 import scala.scalanative.reflect.Reflect
 
 /**
diff --git a/utest/src-native/utest/framework/TestSuitePlatformSpecific.scala b/utest/src-native/utest/framework/TestSuitePlatformSpecific.scala
@@ -0,0 +1,10 @@
+package utest.framework
+
+trait TestSuitePlatformSpecific {
+
+}
+
+
+object TestSuitePlatformSpecific {
+  def processGolden(allSuites: Seq[utest.TestSuite]): Unit = ()
+}
diff --git a/utest/src/utest/TestSuite.scala b/utest/src/utest/TestSuite.scala
diff --git a/utest/src/utest/asserts/Asserts.scala b/utest/src/utest/asserts/Asserts.scala
diff --git a/utest/src/utest/framework/Model.scala b/utest/src/utest/framework/Model.scala
diff --git a/utest/src/utest/runner/BaseRunner.scala b/utest/src/utest/runner/BaseRunner.scala
diff --git a/utest/src/utest/runner/MasterRunner.scala b/utest/src/utest/runner/MasterRunner.scala
diff --git a/utest/src/utest/runner/Task.scala b/utest/src/utest/runner/Task.scala
diff --git a/utest/test/src-jvm/test/utest/GoldenFixTests.scala b/utest/test/src-jvm/test/utest/GoldenFixTests.scala

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package utest;`
	`1`	`+package utest.framework;`
`2`	`2`
`3`	`3`	`import java.lang.annotation.*;`
`4`	`4`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +package utest.asserts
++
 +trait AssertsPlatformSpecific {
++
 +}