Big improvement to VCR error messages.

Author: nedtwigg

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/Mode.kt

@@ -47,14 +47,15 @@ enum class Mode {
       msg("Snapshot " + SnapshotNotEqualErrorMsg.forUnequalStrings(expected, actual))
   internal fun msgSnapshotMismatchBinary(expected: ByteArray, actual: ByteArray) =
       msgSnapshotMismatch(expected.toQuotedPrintable(), actual.toQuotedPrintable())
-  internal fun msgVcrSnapshotNotFound() = msg("VCR snapshot not found")
-  internal fun msgVcrMismatch(key: String, expected: String, actual: String) =
-      msg("VCR frame $key " + SnapshotNotEqualErrorMsg.forUnequalStrings(expected, actual))
-  internal fun msgVcrUnread(expected: Int, actual: Int) =
-      msg("VCR frames unread - only $actual were read out of $expected")
-  internal fun msgVcrUnderflow(expected: Int) =
-      msg(
-          "VCR frames exhausted - only $expected are available but you tried to read ${expected + 1}")
+  internal fun msgVcrSnapshotNotFound(call: CallStack) = msgVcr("VCR snapshot not found", call)
+  internal fun msgVcrMismatch(key: String, expected: String, actual: String, call: CallStack) =
+      msgVcr("VCR frame $key " + SnapshotNotEqualErrorMsg.forUnequalStrings(expected, actual), call)
+  internal fun msgVcrUnread(expected: Int, actual: Int, call: CallStack) =
+      msgVcr("VCR frames unread - only $actual were read out of $expected", call)
+  internal fun msgVcrUnderflow(expected: Int, call: CallStack) =
+      msgVcr(
+          "VCR frames exhausted - only $expected are available but you tried to read ${expected + 1}",
+          call)
   private fun ByteArray.toQuotedPrintable(): String {
     val sb = StringBuilder()
     for (byte in this) {
@@ -71,12 +72,18 @@ enum class Mode {
       when (this) {
         interactive ->
             "$headline\n" +
-                (if (headline.startsWith("Snapshot "))
-                    "‣ update this snapshot by adding `_TODO` to the function name\n" +
-                        "‣ update all snapshots in this file by adding `//selfieonce` or `//SELFIEWRITE`"
-                else
-                    "‣ update all snapshots in this file by adding `//selfieonce` or `//SELFIEWRITE`\n" +
-                        "‣ if that doesn't work remember to put your test rule into the `selfie` package")
+                "‣ update this snapshot by adding `_TODO` to the function name\n" +
+                "‣ update all snapshots in this file by adding `//selfieonce` or `//SELFIEWRITE`"
+        readonly -> headline
+        overwrite -> "$headline\n(didn't expect this to ever happen in overwrite mode)"
+      }
+  private fun msgVcr(headline: String, call: CallStack) =
+      when (this) {
+        interactive ->
+            "$headline\n" +
+                "‣ update all snapshots in this file by adding `//selfieonce` or `//SELFIEWRITE`\n" +
+                "‣ could not find control comment in ${call.location.ideLink(Selfie.system.layout)}\n" +
+                "‣ remember to call `Selfie.vcrTestLocator()` in the test itself, or put the file above into the `selfie` package to mark that it is not the test file"
         readonly -> headline
         overwrite -> "$headline\n(didn't expect this to ever happen in overwrite mode)"
       }

jvm/selfie-lib/src/commonMain/kotlin/com/diffplug/selfie/VcrSelfie.kt

@@ -31,6 +31,7 @@ internal constructor(
     private val call: CallStack,
     private val disk: DiskStorage,
 ) : AutoCloseable {
+  /** Creates VCRs who store their data based on where this TestLocator was created. */
   class TestLocator internal constructor(private val sub: String, private val disk: DiskStorage) {
     private val call = recordCall(false)
     fun createVcr() = VcrSelfie(sub, call, disk)
@@ -73,7 +74,8 @@ internal constructor(
     } else {
       val snapshot =
           disk.readDisk(sub, call)
-              ?: throw Selfie.system.fs.assertFailed(Selfie.system.mode.msgVcrSnapshotNotFound())
+              ?: throw Selfie.system.fs.assertFailed(
+                  Selfie.system.mode.msgVcrSnapshotNotFound(call))
       var idx = 1
       val frames = mutableListOf<Pair<String, SnapshotValue>>()
       for ((key, value) in snapshot.facets) {
@@ -93,7 +95,7 @@ internal constructor(
     if (state is State.Read) {
       if (state.frames.size != state.framesReadSoFar()) {
         throw Selfie.system.fs.assertFailed(
-            Selfie.system.mode.msgVcrUnread(state.frames.size, state.framesReadSoFar()))
+            Selfie.system.mode.msgVcrUnread(state.frames.size, state.framesReadSoFar(), call))
       }
     } else {
       disk.writeDisk((state as State.Write).closeAndGetSnapshot(), sub, call)
@@ -104,12 +106,12 @@ internal constructor(
     val fs = Selfie.system.fs
     val currentFrame = state.currentFrameThenAdvance()
     if (state.frames.size <= currentFrame) {
-      throw fs.assertFailed(mode.msgVcrUnderflow(state.frames.size))
+      throw fs.assertFailed(mode.msgVcrUnderflow(state.frames.size, call), call)
     }
     val expected = state.frames[currentFrame]
     if (expected.first != key) {
       throw fs.assertFailed(
-          mode.msgVcrMismatch("$sub[$OPEN${currentFrame}$CLOSE]", expected.first, key),
+          mode.msgVcrMismatch("$sub[$OPEN${currentFrame}$CLOSE]", expected.first, key, call),
           expected.first,
           key)
     }