Improve error message in multiline iex doctest (#8462)

The previous indentation error message was of no help
in cases where a doctest had a `iex>` command
with multiline expressions.

2 files changed, 13 insertions, 4 deletions

diff --git a/lib/ex_unit/lib/ex_unit/doc_test.ex b/lib/ex_unit/lib/ex_unit/doc_test.ex
index a12936ebd..47a6de026 100644
--- a/lib/ex_unit/lib/ex_unit/doc_test.ex
+++ b/lib/ex_unit/lib/ex_unit/doc_test.ex
@@ -531,7 +531,16 @@ defmodule ExUnit.DocTest do
         raise Error,
           line: line_no,
           module: module,
-          message: "indentation level mismatch: #{inspect(line)}, should have been #{n_spaces}"
+          message: """
+          indentation level mismatch on doctest line: #{inspect(line)}
+
+          If you are planning to assert on the result of an `iex>` expression, \
+          make sure the result is indented at the beginning of `iex>`, which \
+          in this case is exactly #{n_spaces}.
+
+          If instead you have an `iex>` expression that spans over multiple lines, \
+          please make sure that each line after the first one begins with `...>`.
+          """
     end
 
     adjusted_lines = [{stripped_line, line_no} | adjusted_lines]
diff --git a/lib/ex_unit/test/ex_unit/doc_test_test.exs b/lib/ex_unit/test/ex_unit/doc_test_test.exs
index cfbee75a8..77c526c3a 100644
--- a/lib/ex_unit/test/ex_unit/doc_test_test.exs
+++ b/lib/ex_unit/test/ex_unit/doc_test_test.exs
@@ -641,7 +641,7 @@ defmodule ExUnit.DocTestTest do
 
   test "fails in indentation mismatch" do
     message =
-      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch: "   iex> bar = 2", should have been 2 spaces]
+      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch on doctest line: \"   iex> bar = 2\".*is exactly 2 spaces]s
 
     assert_raise ExUnit.DocTest.Error, message, fn ->
       defmodule NeverCompiled do
@@ -651,7 +651,7 @@ defmodule ExUnit.DocTestTest do
     end
 
     message =
-      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch: "    3", should have been 2 spaces]
+      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch on doctest line: \"    3\".*is exactly 2 spaces]s
 
     assert_raise ExUnit.DocTest.Error, message, fn ->
       defmodule NeverCompiled do
@@ -661,7 +661,7 @@ defmodule ExUnit.DocTestTest do
     end
 
     message =
-      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch: \"  3\", should have been 4 spaces]
+      ~r[test/ex_unit/doc_test_test\.exs:\d+: indentation level mismatch on doctest line: \"  3\".*is exactly 4 spaces]s
 
     assert_raise ExUnit.DocTest.Error, message, fn ->
       defmodule NeverCompiled do