diff --git a/client/src/client/frame-runner.js b/client/src/client/frame-runner.js
index 15db3773ea7..7b0f074c7ea 100644
--- a/client/src/client/frame-runner.js
+++ b/client/src/client/frame-runner.js
@@ -98,9 +98,15 @@ async function initTestFrame(e = { code: {} }) {
         console.error(err);
       }
       // to provide useful debugging information when debugging the tests, we
-      // have to extract the message and stack before returning
+      // have to extract the message, stack and, if they exist, expected and
+      // actual before returning
       return {
-        err: { message: err.message, stack: err.stack }
+        err: {
+          message: err.message,
+          stack: err.stack,
+          expected: err.expected,
+          actual: err.actual
+        }
       };
     }
   };
diff --git a/client/src/templates/Challenges/redux/execute-challenge-saga.js b/client/src/templates/Challenges/redux/execute-challenge-saga.js
index c6161a14ff9..bca2c6c2399 100644
--- a/client/src/templates/Challenges/redux/execute-challenge-saga.js
+++ b/client/src/templates/Challenges/redux/execute-challenge-saga.js
@@ -167,7 +167,11 @@ function* executeTests(testRunner, tests, testTimeout = 5000) {
         throw err;
       }
     } catch (err) {
-      newTest.message = text;
+      const { actual, expected } = err;
+
+      newTest.message = text
+        .replace('--fcc-expected--', expected)
+        .replace('--fcc-actual--', actual);
       if (err === 'timeout') {
         newTest.err = 'Test timed out';
         newTest.message = `${newTest.message} (${newTest.err})`;
diff --git a/docs/how-to-work-on-coding-challenges.md b/docs/how-to-work-on-coding-challenges.md
index c017f351b44..f635f1e3b40 100644
--- a/docs/how-to-work-on-coding-challenges.md
+++ b/docs/how-to-work-on-coding-challenges.md
@@ -64,10 +64,13 @@ Tests to run against user code, in pairs of markdown text and code block test co
 Code for test one
 ```
 
-More instructions in markdown syntax
+If you want dynamic output based on the user's code, --fcc-expected-- and --fcc-actual-- will be replaced with the expected and actual values of the test's assertion:
 
 ```js
-More code
+assert.equal(
+  'this will replace --fcc-actual--',
+  'this will replace --fcc-expected--'
+);
 ```
 
 # --seed--