Phoenix.LiveView.Debug (#3776)

* wip: Phoenix.LiveView.Debug

* don't rely on :sys.get_state

* list_liveviews and return more details

Author: SteffenDE

lib/phoenix_live_view/channel.ex

@@ -408,6 +408,25 @@ defmodule Phoenix.LiveView.Channel do
     {:noreply, register_entry_upload(state, from, info)}
   end
 
+  # Phoenix.LiveView.Debug.socket/1
+  def handle_call({@prefix, :debug_get_socket}, _from, state) do
+    {:reply, {:ok, state.socket}, state}
+  end
+
+  # Phoenix.LiveView.Debug.live_components/1
+  def handle_call(
+        {@prefix, :debug_live_components},
+        _from,
+        %{components: {components, _, _}} = state
+      ) do
+    component_info =
+      Enum.map(components, fn {cid, {mod, id, assigns, private, _prints}} ->
+        %{id: id, cid: cid, module: mod, assigns: assigns, children_cids: private.children_cids}
+      end)
+
+    {:reply, {:ok, component_info}, state}
+  end
+
   def handle_call(msg, from, %{socket: socket} = state) do
     case socket.view.handle_call(msg, from, socket) do
       {:reply, reply, %Socket{} = new_socket} ->
@@ -1089,6 +1108,10 @@ defmodule Phoenix.LiveView.Channel do
             with {:ok, %Session{view: view} = new_verified, route, url} <-
                    authorize_session(verified, endpoint, params),
                  {:ok, config} <- load_live_view(view) do
+              # TODO: replace with Process.put_label/2 when we require Elixir 1.17
+              Process.put(:"$process_label", {Phoenix.LiveView, view, phx_socket.topic})
+              Process.put(:"$phx_transport_pid", phx_socket.transport_pid)
+
               verified_mount(
                 new_verified,
                 config,

lib/phoenix_live_view/debug.ex

@@ -0,0 +1,139 @@
+defmodule Phoenix.LiveView.Debug do
+  @moduledoc """
+  Functions for runtime introspection and debugging of LiveViews.
+
+  This module provides utilities for inspecting and debugging LiveView processes
+  at runtime. It allows you to:
+
+    * List all currently connected LiveViews
+    * Check if a process is a LiveView
+    * Get the socket of a LiveView process
+    * Inspect LiveComponents rendered in a LiveView
+
+  ## Examples
+
+      # List all LiveViews
+      iex> Phoenix.LiveView.Debug.list_liveviews()
+      [%{pid: #PID<0.123.0>, view: MyAppWeb.PostLive.Index, topic: "lv:12345678", transport_pid: #PID<0.122.0>}]
+
+      # Check if a process is a LiveView
+      iex> Phoenix.LiveView.Debug.liveview_process?(pid(0,123,0))
+      true
+
+      # Get the socket of a LiveView process
+      iex> Phoenix.LiveView.Debug.socket(pid(0,123,0))
+      {:ok, %Phoenix.LiveView.Socket{...}}
+
+      # Get information about LiveComponents
+      iex> Phoenix.LiveView.Debug.live_components(pid(0,123,0))
+      {:ok, [%{id: "component-1", module: MyAppWeb.PostLive.Index.Component1, ...}]}
+
+  """
+
+  @doc """
+  Returns a list of all currently connected LiveView processes (on the current node).
+
+  Each entry is a map with the following keys:
+
+    - `pid`: The PID of the LiveView process.
+    - `view`: The module of the LiveView.
+    - `topic`: The topic of the LiveView's channel.
+    - `transport_pid`: The PID of the transport process.
+
+  The `transport_pid` can be used to group LiveViews on the same page.
+
+  ## Examples
+
+      iex> list_liveviews()
+      [%{pid: #PID<0.123.0>, view: MyAppWeb.PostLive.Index, topic: "lv:12345678", transport_pid: #PID<0.122.0>}]
+
+  """
+  def list_liveviews do
+    for pid <- Process.list(), dict = lv_process_dict(pid), not is_nil(dict) do
+      {Phoenix.LiveView, view, topic} = keyfind(dict, :"$process_label")
+      %{pid: pid, view: view, topic: topic, transport_pid: keyfind(dict, :"$phx_transport_pid")}
+    end
+  end
+
+  defp keyfind(list, key) do
+    case List.keyfind(list, key, 0) do
+      {^key, value} -> value
+      _ -> nil
+    end
+  end
+
+  defp lv_process_dict(pid) do
+    # LiveViews set the "$process_label" to {Phoenix.LiveView, view, topic}
+    with info when is_list(info) <- Process.info(pid, [:dictionary]),
+         dictionary when not is_nil(dictionary) <- keyfind(info, :dictionary),
+         label when not is_nil(label) <- keyfind(dictionary, :"$process_label"),
+         {Phoenix.LiveView, view, topic} when is_atom(view) and is_binary(topic) <- label do
+      dictionary
+    else
+      _ -> nil
+    end
+  end
+
+  @doc """
+  Checks if the given pid is a LiveView process.
+
+  ## Examples
+
+      iex> list_liveviews() |> Enum.at(0) |> Map.fetch!(:pid) |> liveview_process?()
+      true
+
+      iex> liveview_process?(pid(0,456,0))
+      false
+
+  """
+  def liveview_process?(pid) do
+    not is_nil(lv_process_dict(pid))
+  end
+
+  @doc """
+  Returns the socket of the LiveView process.
+
+  ## Examples
+
+      iex> list_liveviews() |> Enum.at(0) |> Map.fetch!(:pid) |> socket()
+      {:ok, %Phoenix.LiveView.Socket{...}}
+
+      iex> socket(pid(0,123,0))
+      {:error, :not_alive_or_not_a_liveview}
+
+  """
+  def socket(liveview_pid) do
+    GenServer.call(liveview_pid, {:phoenix, :debug_get_socket})
+  catch
+    :exit, _ -> {:error, :not_alive_or_not_a_liveview}
+  end
+
+  @doc """
+  Returns a list with information about all LiveComponents rendered in the LiveView.
+
+  ## Examples
+
+      iex> live_components(pid)
+      {:ok,
+       [
+         %{
+           id: "component-1",
+           module: MyAppWeb.PostLive.Index.Component1,
+           cid: 1,
+           assigns: %{
+             id: "component-1",
+             __changed__: %{},
+             flash: %{},
+             myself: %Phoenix.LiveComponent.CID{cid: 1},
+             ...
+           }
+         }
+       ]}
+
+  """
+  def live_components(liveview_pid) do
+    GenServer.call(liveview_pid, {:phoenix, :debug_live_components})
+  rescue
+    _ -> {:error, :not_alive_or_not_a_liveview}
+  end
+end

test/phoenix_live_view/debug_test.exs

@@ -0,0 +1,93 @@
+defmodule Phoenix.LiveView.DebugTest do
+  use ExUnit.Case, async: true
+
+  alias Phoenix.LiveView.Debug
+  import Phoenix.LiveViewTest
+
+  @endpoint Phoenix.LiveViewTest.Support.Endpoint
+
+  defmodule TestLV do
+    use Phoenix.LiveView
+
+    defmodule Component do
+      use Phoenix.LiveComponent
+
+      def render(assigns) do
+        ~H"""
+        <p>Hello</p>
+        """
+      end
+    end
+
+    def mount(_params, _session, socket) do
+      {:ok, assign(socket, :hello, :world)}
+    end
+
+    def render(assigns) do
+      ~H"""
+      <div>
+        <p>Hello</p>
+        <.live_component id="component-1" module={Component} />
+      </div>
+      """
+    end
+  end
+
+  describe "list_liveviews/0" do
+    test "returns a list of all currently connected LiveView processes" do
+      conn = Plug.Test.conn(:get, "/")
+      {:ok, view, _} = live_isolated(conn, TestLV)
+      live_views = Debug.list_liveviews()
+
+      assert is_list(live_views)
+      assert lv = Enum.find(live_views, fn lv -> lv.pid == view.pid end)
+      assert lv.view == TestLV
+      assert lv.transport_pid
+      assert lv.topic
+    end
+  end
+
+  describe "liveview_process?/1" do
+    test "returns true if the given pid is a LiveView process" do
+      conn = Plug.Test.conn(:get, "/")
+      {:ok, view, _} = live_isolated(conn, TestLV)
+      assert Debug.liveview_process?(view.pid)
+    end
+  end
+
+  describe "socket/1" do
+    test "returns the socket of the given LiveView process" do
+      conn = Plug.Test.conn(:get, "/")
+      {:ok, view, _} = live_isolated(conn, TestLV)
+      assert {:ok, socket} = Debug.socket(view.pid)
+      assert socket.assigns.hello == :world
+    end
+
+    test "returns an error if the given pid is not a LiveView process" do
+      defmodule NotALiveView do
+        use GenServer
+
+        def start_link(opts) do
+          GenServer.start_link(__MODULE__, opts)
+        end
+
+        def init(opts) do
+          {:ok, opts}
+        end
+      end
+
+      pid = start_supervised!(NotALiveView)
+      assert {:error, :not_alive_or_not_a_liveview} = Debug.socket(pid)
+    end
+  end
+
+  describe "live_components/1" do
+    test "returns a list of all LiveComponents rendered in the given LiveView" do
+      conn = Plug.Test.conn(:get, "/")
+      {:ok, view, _} = live_isolated(conn, TestLV)
+
+      assert {:ok, [%{id: "component-1", module: TestLV.Component}]} =
+               Debug.live_components(view.pid)
+    end
+  end
+end