Add mix test --breakpoints

Author: josevalim

lib/elixir/pages/getting-started/debugging.md

@@ -79,7 +79,7 @@ feature #=> %{inspiration: "Rust", name: :dbg}
 Map.put(feature, :in_version, "1.14.0") #=> %{in_version: "1.14.0", inspiration: "Rust", name: :dbg}
 ```
 
-When talking about `IO.inspect/2`, we mentioned its usefulness when placed between steps of `|>` pipelines. `dbg` does it better: it understands Elixir code, so it will print values at *every step of the pipeline*.
+When talking about `IO.inspect/2`, we mentioned its usefulness when placed between steps of `|>` pipelines. `dbg` does it better: it understands Elixir code, so it will print values at _every step of the pipeline_.
 
 ```elixir
 # In dbg_pipes.exs
@@ -102,7 +102,7 @@ __ENV__.file #=> "/home/myuser/dbg_pipes.exs"
 
 While `dbg` provides conveniences around Elixir constructs, you will need `IEx` if you want to execute code and set breakpoints while debugging.
 
-## Breakpoints
+## Pry
 
 When using `IEx`, you may pass `--dbg pry` as an option to "stop" the code execution where the `dbg` call is:
 
@@ -116,22 +116,30 @@ Or to debug inside a of a project:
 $ iex --dbg pry -S mix
 ```
 
-Or during tests (the `--trace` flag on `mix test` prevents tests from timing out):
-
-```console
-$ iex --dbg pry -S mix test --trace
-$ iex --dbg pry -S mix test path/to/file:line --trace
-```
+Now any call to `dbg` will ask if you want to pry the existing code. If you accept, you'll be able to access all variables, as well as imports and aliases from the code, directly from IEx. This is called "prying". While the pry session is running, the code execution stops, until `continue` (or `c`) or `next` (or `n`) are called. Remember you can always run `iex` in the context of a project with `iex -S mix TASK`.
 
-Now a call to `dbg` will ask if you want to pry the existing code. If you accept, you'll be able to access all variables, as well as imports and aliases from the code, directly from IEx. This is called "prying". While the pry session is running, the code execution stops, until `continue` or `next` are called. Remember you can always run `iex` in the context of a project with `iex -S mix TASK`.
+<script id="asciicast-509509" src="https://asciinema.org/a/509509.js" async></script><noscript><p><a href="https://asciinema.org/a/509509">See the example in asciinema</a></p></noscript>
 
-<script id="asciicast-509509" src="https://asciinema.org/a/509509.js" async></script>
+## Breakpoints
 
 `dbg` calls require us to change the code we intend to debug and has limited stepping functionality. Luckily IEx also provides a `IEx.break!/2` function which allows you to set and manage breakpoints on any Elixir code without modifying its source:
 
 <script type="text/javascript" src="https://asciinema.org/a/0h3po0AmTcBAorc5GBNU97nrs.js" id="asciicast-0h3po0AmTcBAorc5GBNU97nrs" async></script><noscript><p><a href="https://asciinema.org/a/0h3po0AmTcBAorc5GBNU97nrs">See the example in asciinema</a></p></noscript>
 
-Similar to `dbg`, once a breakpoint is reached code execution stops until `continue` or `next` are invoked. However, `break!/2` does not have access to aliases and imports from the debugged code as it works on the compiled artifact rather than on source code.
+Similar to `dbg`, once a breakpoint is reached, code execution stops until `continue` (or `c`) or `next` (or `n`) are invoked. Breakpoints can navigate line-by-line by default, however, they do not have access to aliases and imports when breakpoints are set on compiled modules.
+
+The `mix test` task direct integration with breakpoints via the `-b`/`--breakpoints` flag. When the flag is used, a breakpoint is set at the beginning of every test that will run:
+
+<script async id="asciicast-XTZ15jFKFAlr8ZxIZMzaHgL5n" src="https://asciinema.org/a/XTZ15jFKFAlr8ZxIZMzaHgL5n.js"></script><noscript><p><a href="https://asciinema.org/a/XTZ15jFKFAlr8ZxIZMzaHgL5n">See the example in asciinema</a></p></noscript>
+
+Here are some commands you can use in practice:
+
+```console
+# Debug all failed tests
+$ iex -S mix test --breakpoints --failed
+# Debug the test at the given file:line
+$ iex -S mix test -b path/to/file:line
+```
 
 ## Observer
 
@@ -147,15 +155,13 @@ iex> :observer.start()
 > When running `iex` inside a project with `iex -S mix`, `observer` won't be available as a dependency. To do so, you will need to call the following functions before:
 >
 > ```elixir
-> iex> Mix.ensure_application!(:wx)
-> iex> Mix.ensure_application!(:runtime_tools)
+> iex> Mix.ensure_application!(:wx)             # Not necessary on Erlang/OTP 27+
+> iex> Mix.ensure_application!(:runtime_tools)  # Not necessary on Erlang/OTP 27+
 > iex> Mix.ensure_application!(:observer)
 > iex> :observer.start()
 > ```
 >
 > If any of the calls above fail, here is what may have happened: some package managers default to installing a minimized Erlang without WX bindings for GUI support. In some package managers, you may be able to replace the headless Erlang with a more complete package (look for packages named `erlang` vs `erlang-nox` on Debian/Ubuntu/Arch). In others managers, you may need to install a separate `erlang-wx` (or similarly named) package.
->
-> There are conversations to improve this experience in future releases.
 
 The above will open another Graphical User Interface that provides many panes to fully understand and navigate the runtime and your project.
 

lib/ex_unit/lib/ex_unit/case.ex

@@ -366,34 +366,52 @@ defmodule ExUnit.Case do
     end
 
     contents =
-      case contents do
+      case annotate_test(contents, __CALLER__) do
         [do: block] ->
           quote do
             unquote(block)
             :ok
           end
 
-        _ ->
+        contents ->
           quote do
             try(unquote(contents))
             :ok
           end
       end
 
-    var = Macro.escape(var)
-    contents = Macro.escape(contents, unquote: true)
     %{module: mod, file: file, line: line} = __CALLER__
 
-    quote bind_quoted: [
-            var: var,
-            contents: contents,
-            message: message,
-            mod: mod,
-            file: file,
-            line: line
-          ] do
-      name = ExUnit.Case.register_test(mod, file, line, :test, message, [])
-      def unquote(name)(unquote(var)), do: unquote(contents)
+    name =
+      quote do
+        name =
+          ExUnit.Case.register_test(
+            unquote(mod),
+            unquote(file),
+            unquote(line),
+            :test,
+            unquote(message),
+            []
+          )
+      end
+
+    def =
+      {:def, [],
+       [
+         {{:unquote, [], [quote(do: name)]}, [], [var]},
+         [do: contents]
+       ]}
+
+    {:__block__, [], [name, def]}
+  end
+
+  defp annotate_test(contents, caller) do
+    if Application.get_env(:ex_unit, :breakpoints, false) and Keyword.keyword?(contents) do
+      for {key, expr} <- contents do
+        {key, IEx.Pry.annotate_quoted(expr, true, caller)}
+      end
+    else
+      contents
     end
   end
 

lib/iex/lib/iex/pry.ex

@@ -86,7 +86,7 @@ defmodule IEx.Pry do
   end
 
   @doc false
-  def pry_with_next(next?, binding, opts_or_env) when is_boolean(next?) do
+  def __next__(next?, binding, opts_or_env) when is_boolean(next?) do
     next? and pry(binding, opts_or_env) == {:ok, true}
   end
 
@@ -108,6 +108,63 @@ defmodule IEx.Pry do
     []
   end
 
+  @doc """
+  Annotate quoted expression with line-by-line `IEx.Pry` debugging steps.
+
+  It expected the `quoted` expression to annotate, a `condition` that controls
+  if pry should run or not (usually is simply the boolean `true`), and the
+  caller macro environment.
+  """
+  @doc since: "1.17.0"
+  @spec annotate_quoted(Macro.t(), Macro.t(), Macro.Env.t()) :: Macro.t()
+  def annotate_quoted(quoted, condition, caller) do
+    prelude =
+      quote do
+        [
+          env = unquote(Macro.escape(Macro.Env.prune_compile_info(caller))),
+          next? = unquote(condition)
+        ]
+      end
+
+    next_pry =
+      fn line, _version, _binding ->
+        quote do
+          next? = IEx.Pry.__next__(next?, binding(), %{env | line: unquote(line)})
+        end
+      end
+
+    annotate_quoted(quoted, prelude, caller.line, 0, :ok, fn _, _ -> :ok end, next_pry)
+  end
+
+  defp annotate_quoted(maybe_block, prelude, line, version, binding, next_binding, next_pry)
+       when is_list(prelude) do
+    exprs =
+      maybe_block
+      |> unwrap_block()
+      |> annotate_quoted(true, line, version, binding, {next_binding, next_pry})
+
+    {:__block__, [], prelude ++ exprs}
+  end
+
+  defp annotate_quoted([expr | exprs], force?, line, version, binding, funs) do
+    {next_binding, next_pry} = funs
+    new_binding = next_binding.(expr, binding)
+    {min_line, max_line} = line_range(expr, line)
+
+    if force? or min_line > line do
+      [
+        next_pry.(min_line, version, binding),
+        expr | annotate_quoted(exprs, false, max_line, version + 1, new_binding, funs)
+      ]
+    else
+      [expr | annotate_quoted(exprs, false, max_line, version, new_binding, funs)]
+    end
+  end
+
+  defp annotate_quoted([], _force?, _line, _version, _binding, _funs) do
+    []
+  end
+
   @doc """
   Formats the location for `whereami/3` prying.
 
@@ -473,7 +530,6 @@ defmodule IEx.Pry do
 
   defp instrument_clause({meta, args, guards, clause}, ref, case_pattern, opts) do
     arity = length(args)
-    exprs = unwrap_block(clause)
 
     # Have an extra binding per argument for case matching.
     case_vars =
@@ -487,63 +543,49 @@ defmodule IEx.Pry do
     # Generate the take_over condition with the ETS lookup.
     # Remember this is expanded AST, so no aliases allowed,
     # no locals (such as the unary -) and so on.
-    initialize_next =
+    prelude =
       quote do
-        unquote(next_var(arity + 1)) =
-          case unquote(case_head) do
-            unquote(case_pattern) ->
-              :erlang."/="(
-                # :ets.update_counter(table, key, {pos, inc, threshold, reset})
-                :ets.update_counter(unquote(@table), unquote(ref), unquote(update_op)),
-                unquote(-1)
-              )
-
-            _ ->
-              false
-          end
+        [
+          unquote(next_var(arity + 1)) = unquote(opts),
+          unquote(next_var(arity + 2)) =
+            case unquote(case_head) do
+              unquote(case_pattern) ->
+                :erlang."/="(
+                  # :ets.update_counter(table, key, {pos, inc, threshold, reset})
+                  :ets.update_counter(unquote(@table), unquote(ref), unquote(update_op)),
+                  unquote(-1)
+                )
+
+              _ ->
+                false
+            end
+        ]
       end
 
     args =
       case_vars
       |> Enum.zip(args)
       |> Enum.map(fn {var, arg} -> {:=, [], [arg, var]} end)
 
-    # The variable we pass around will start after the arity,
-    # as we use the arity to instrument the clause.
+    version = arity + 2
     binding = match_binding(args, %{})
     line = Keyword.get(meta, :line, 1)
-    exprs = instrument_body(exprs, true, line, arity + 1, binding, opts)
-
-    {meta, args, guards, {:__block__, meta, [initialize_next | exprs]}}
-  end
-
-  defp instrument_body([expr | exprs], force?, line, version, binding, opts) do
-    next_binding = binding(expr, binding)
-    {min_line, max_line} = line_range(expr, line)
-
-    if force? or min_line > line do
-      pry_var = next_var(version)
-      pry_binding = Map.to_list(binding)
-      pry_opts = [line: min_line] ++ opts
-
-      pry =
-        quote do
-          unquote(next_var(version + 1)) =
-            :"Elixir.IEx.Pry".pry_with_next(
-              unquote(pry_var),
-              unquote(pry_binding),
-              unquote(pry_opts)
-            )
-        end
-
-      [pry, expr | instrument_body(exprs, false, max_line, version + 1, next_binding, opts)]
-    else
-      [expr | instrument_body(exprs, false, max_line, version, next_binding, opts)]
-    end
-  end
+    env_var = next_var(arity + 1)
+
+    clause =
+      annotate_quoted(clause, prelude, line, version, binding, &next_binding/2, fn
+        line, version, binding ->
+          quote do
+            unquote(next_var(version + 1)) =
+              :"Elixir.IEx.Pry".__next__(
+                unquote(next_var(version)),
+                unquote(Map.to_list(binding)),
+                [{:line, unquote(line)} | unquote(env_var)]
+              )
+          end
+      end)
 
-  defp instrument_body([], _force?, _line, _version, _binding, _opts) do
-    []
+    {meta, args, guards, clause}
   end
 
   defp line_range(ast, line) do
@@ -567,7 +609,7 @@ defmodule IEx.Pry do
     if min == :infinity, do: {line, max}, else: {min, max}
   end
 
-  defp binding(ast, binding) do
+  defp next_binding(ast, binding) do
     {_, binding} =
       Macro.prewalk(ast, binding, fn
         {:=, _, [left, _right]}, acc ->
@@ -637,7 +679,7 @@ defmodule IEx.Pry do
 
         env = unquote(env_with_line_from_asts(first_ast_chunk))
 
-        next? = IEx.Pry.pry_with_next(true, binding(), env)
+        next? = IEx.Pry.__next__(true, binding(), env)
         value = unquote(pipe_chunk_of_asts(first_ast_chunk))
 
         IEx.Pry.__dbg_pipe_step__(
@@ -656,7 +698,7 @@ defmodule IEx.Pry do
         quote do
           unquote(ast_acc)
           env = unquote(env_with_line_from_asts(asts_chunk))
-          next? = IEx.Pry.pry_with_next(next?, binding(), env)
+          next? = IEx.Pry.__next__(next?, binding(), env)
           value = unquote(piped_asts)
 
           IEx.Pry.__dbg_pipe_step__(