defmodule Cerberus do
  @moduledoc """
  Session-first test API for non-browser Phoenix mode and browser execution.

  Architecture contract (ADR-0001 + ADR-0002):
  - The public API is driver-agnostic and session-first.
  - All public operations take a `Cerberus.Session` and return a `Cerberus.Session`.
  - `locator` is the first argument after `session` for locator-based operations.
  - Browser unwrap payloads are exposed as `Cerberus.Browser.Native` handles, not raw internals.
  - v0 does not expose a public located-element pipeline type.

  Slice 1 provides one-shot operations over deterministic adapters.

  Locator sigil quick look:

      ~l"Save"          # text
      ~l"Save"e         # exact text
      ~l"Save"i         # inexact text
      ~l"button:Save"r  # role form (ROLE:NAME)
      ~l"#save"c        # css
      ~l"save-btn"t     # testid (defaults exact: true)

  Locator composition quick look:

      button("Run Search") |> testid("submit-secondary-button")     # AND (same element)
      or_(css("#primary"), css("#secondary"))                       # OR (union)
      button("Run Search") |> has(testid("submit-secondary-marker")) # nesting (descendant)
  """

  alias Cerberus.Assertions
  alias Cerberus.Browser.Native, as: BrowserNative
  alias Cerberus.Driver.Browser, as: BrowserSession
  alias Cerberus.Driver.Live, as: LiveSession
  alias Cerberus.Driver.Static, as: StaticSession
  alias Cerberus.Html
  alias Cerberus.Locator
  alias Cerberus.OpenBrowser
  alias Cerberus.Options
  alias Cerberus.Path
  alias Cerberus.Phoenix.Conn, as: DriverConn
  alias Cerberus.Phoenix.LiveViewTimeout
  alias Cerberus.Session
  alias Ecto.Adapters.SQL.Sandbox, as: EctoSandbox
  alias ExUnit.AssertionError
  alias Phoenix.Ecto.SQL.Sandbox, as: PhoenixSandbox
  alias Phoenix.LiveViewTest.View

  @type driver_kind :: Session.driver_kind()
  @type locator_input :: Locator.input()
  @type scope_locator_input :: Locator.input()
  @locator_kind_keys [:text, :label, :link, :button, :placeholder, :title, :alt, :role, :css, :testid, :and, :or]
  @locator_kind_string_keys Enum.map(@locator_kind_keys, &Atom.to_string/1)

  @spec session() :: Session.t()
  def session, do: session([])

  @spec session(Options.session_common_opts()) :: Session.t()
  def session(opts) when is_list(opts) do
    opts
    |> Options.validate_session_common!()
    |> StaticSession.new_session()
  end

  @spec session(Plug.Conn.t()) :: Session.t()
  def session(%Plug.Conn{} = conn), do: session(conn: conn)

  @spec session(:phoenix) :: Session.t()
  def session(:phoenix), do: session([])

  @spec session(:browser) :: Session.t()
  def session(:browser), do: session(:browser, [])

  @spec session(:chrome) :: Session.t()
  def session(:chrome), do: session(:chrome, [])

  @spec session(:firefox) :: Session.t()
  def session(:firefox), do: session(:firefox, [])

  def session(driver) when is_atom(driver) do
    raise ArgumentError,
          "unsupported public driver #{inspect(driver)}; use session()/session(:phoenix) for non-browser and session(:browser|:chrome|:firefox) for browser"
  end

  @spec session(:phoenix, Options.session_common_opts()) :: Session.t()
  def session(:phoenix, opts) when is_list(opts), do: session(opts)

  @doc """
  Starts a browser session.

  Browser context defaults can be configured globally via `config :cerberus, :browser`
  and overridden per session with:

  - `user_agent: "..."`
  - `browser: [viewport: [width: ..., height: ...] | {w, h}]`
  - `browser: [user_agent: "..."]`
  - `browser: [popup_mode: :allow | :same_tab]` to control `window.open` behavior
    (`:same_tab` is currently unsupported on Firefox)
  - `browser: [init_script: "..."]` or `browser: [init_scripts: ["...", ...]]`
  - `webdriver_url: "http://remote-webdriver:4444"` to use a remote WebDriver endpoint
    without local browser/chromedriver launch.
  """
  @spec session(:browser, Options.session_browser_opts()) :: Session.t()
  def session(:browser, opts) when is_list(opts) do
    opts
    |> Options.validate_session_browser!()
    |> BrowserSession.new_session()
  end

  @spec session(:chrome, Options.session_browser_opts()) :: Session.t()
  def session(:chrome, opts) when is_list(opts) do
    opts
    |> Options.validate_session_browser!()
    |> Keyword.put(:browser_name, :chrome)
    |> BrowserSession.new_session()
  end

  @spec session(:firefox, Options.session_browser_opts()) :: Session.t()
  def session(:firefox, opts) when is_list(opts) do
    opts
    |> Options.validate_session_browser!()
    |> Keyword.put(:browser_name, :firefox)
    |> BrowserSession.new_session()
  end

  def session(driver, opts) when is_atom(driver) and is_list(opts) do
    raise ArgumentError,
          "unsupported public driver #{inspect(driver)}; use session()/session(:phoenix) for non-browser and session(:browser|:chrome|:firefox) for browser"
  end

  @doc """
  Returns the encoded SQL sandbox user-agent marker for an ExUnit test context.

  This helper is intended for browser-session sandbox wiring:

      metadata = Cerberus.sql_sandbox_user_agent(MyApp.Repo, context)
      session(:browser, user_agent: metadata)

  The returned value can also be used for raw conn headers:

      conn
      |> Plug.Conn.delete_req_header("user-agent")
      |> Plug.Conn.put_req_header("user-agent", metadata)
  """
  @spec sql_sandbox_user_agent(module() | [module()], map()) :: String.t()
  def sql_sandbox_user_agent(repo, context) when (is_atom(repo) or is_list(repo)) and is_map(context) do
    checkout_ecto_repos(repo, context)
  end

  @doc """
  Returns the encoded SQL sandbox user-agent marker for the first configured Ecto repo.
  """
  @spec sql_sandbox_user_agent(map()) :: String.t()
  def sql_sandbox_user_agent(context) when is_map(context) do
    if repos = Application.get_env(:cerberus, :ecto_repos) do
      sql_sandbox_user_agent(repos, context)
    else
      raise ArgumentError,
            "sql_sandbox_user_agent/1 requires :cerberus, :ecto_repos to include at least one repo; use sql_sandbox_user_agent/2 to pass an explicit repo"
    end
  end

  @spec open_tab(arg) :: arg when arg: var
  def open_tab(%BrowserSession{} = session), do: BrowserSession.open_tab(session)
  def open_tab(%StaticSession{} = session), do: StaticSession.open_tab(session)
  def open_tab(%LiveSession{} = session), do: LiveSession.open_tab(session)

  @spec switch_tab(Session.t(), Session.t()) :: Session.t()
  def switch_tab(%BrowserSession{} = session, %BrowserSession{} = target_session) do
    BrowserSession.switch_tab(session, target_session)
  end

  def switch_tab(%BrowserSession{}, _target_session) do
    raise ArgumentError, "cannot switch browser tab to a non-browser session"
  end

  def switch_tab(%StaticSession{} = session, %StaticSession{} = target_session) do
    ensure_same_endpoint!(session, target_session)
    StaticSession.switch_tab(session, target_session)
  end

  def switch_tab(%StaticSession{} = session, %LiveSession{} = target_session) do
    ensure_same_endpoint!(session, target_session)
    StaticSession.switch_tab(session, target_session)
  end

  def switch_tab(%LiveSession{} = session, %StaticSession{} = target_session) do
    ensure_same_endpoint!(session, target_session)
    LiveSession.switch_tab(session, target_session)
  end

  def switch_tab(%LiveSession{} = session, %LiveSession{} = target_session) do
    ensure_same_endpoint!(session, target_session)
    LiveSession.switch_tab(session, target_session)
  end

  @spec close_tab(arg) :: arg when arg: var
  def close_tab(%BrowserSession{} = session), do: BrowserSession.close_tab(session)
  def close_tab(%StaticSession{} = session), do: StaticSession.close_tab(session)
  def close_tab(%LiveSession{} = session), do: LiveSession.close_tab(session)

  @doc """
  Executes a callback with driver-native escape-hatch data.

  Browser sessions receive a constrained `Cerberus.Browser.Native` handle.
  Prefer public Cerberus operations and `Cerberus.Browser.*` helpers for stable flows.
  """
  @spec unwrap(arg, (term() -> term())) :: arg when arg: var
  def unwrap(_session, fun) when not is_function(fun, 1) do
    raise ArgumentError, "unwrap/2 expects a callback with arity 1"
  end

  def unwrap(%StaticSession{} = session, fun) do
    session.conn
    |> DriverConn.ensure_conn()
    |> fun.()
    |> unwrap_conn_result(session, :static)
  end

  def unwrap(%LiveSession{view: nil}, _fun) do
    raise ArgumentError, "unwrap/2 requires an active LiveView; visit a live route first"
  end

  def unwrap(%LiveSession{} = session, fun) do
    session.view
    |> fun.()
    |> unwrap_live_result(session)
  end

  def unwrap(%BrowserSession{} = session, fun) do
    _ =
      fun.(%BrowserNative{
        user_context_pid: session.user_context_pid,
        tab_id: session.tab_id
      })

    session
  end

  @spec open_browser(arg) :: arg when arg: var
  def open_browser(session), do: open_browser(session, &OpenBrowser.open_with_system_cmd/1)

  @doc false
  @spec open_browser(arg, (String.t() -> term())) :: arg when arg: var
  def open_browser(session, open_fun) when is_function(open_fun, 1) do
    driver_module_for_session!(session).open_browser(session, open_fun)
  end

  def open_browser(_session, _open_fun) do
    raise ArgumentError, "open_browser/2 expects a callback with arity 1"
  end

  @spec text(String.t() | Regex.t()) :: Locator.t()
  def text(value) when is_binary(value) or is_struct(value, Regex), do: text(value, [])

  @spec text(String.t() | Regex.t(), keyword()) :: Locator.t()
  def text(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:text, value, opts)
  end

  @spec text(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def text(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, text(value))
  end

  @spec text(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def text(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, text(value, opts))
  end

  @spec link(String.t() | Regex.t()) :: Locator.t()
  def link(value) when is_binary(value) or is_struct(value, Regex), do: link(value, [])

  @spec link(String.t() | Regex.t(), keyword()) :: Locator.t()
  def link(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:link, value, opts)
  end

  @spec link(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def link(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, link(value))
  end

  @spec link(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def link(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, link(value, opts))
  end

  @spec button(String.t() | Regex.t()) :: Locator.t()
  def button(value) when is_binary(value) or is_struct(value, Regex), do: button(value, [])

  @spec button(String.t() | Regex.t(), keyword()) :: Locator.t()
  def button(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:button, value, opts)
  end

  @spec button(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def button(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, button(value))
  end

  @spec button(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def button(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, button(value, opts))
  end

  @spec label(String.t() | Regex.t()) :: Locator.t()
  def label(value) when is_binary(value) or is_struct(value, Regex), do: label(value, [])

  @spec label(String.t() | Regex.t(), keyword()) :: Locator.t()
  def label(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:label, value, opts)
  end

  @spec label(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def label(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, label(value))
  end

  @spec label(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def label(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, label(value, opts))
  end

  @spec placeholder(String.t() | Regex.t()) :: Locator.t()
  def placeholder(value) when is_binary(value) or is_struct(value, Regex), do: placeholder(value, [])

  @spec placeholder(String.t() | Regex.t(), keyword()) :: Locator.t()
  def placeholder(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:placeholder, value, opts)
  end

  @spec placeholder(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def placeholder(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, placeholder(value))
  end

  @spec placeholder(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def placeholder(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, placeholder(value, opts))
  end

  @spec title(String.t() | Regex.t()) :: Locator.t()
  def title(value) when is_binary(value) or is_struct(value, Regex), do: title(value, [])

  @spec title(String.t() | Regex.t(), keyword()) :: Locator.t()
  def title(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:title, value, opts)
  end

  @spec title(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def title(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, title(value))
  end

  @spec title(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def title(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, title(value, opts))
  end

  @spec alt(String.t() | Regex.t()) :: Locator.t()
  def alt(value) when is_binary(value) or is_struct(value, Regex), do: alt(value, [])

  @spec alt(String.t() | Regex.t(), keyword()) :: Locator.t()
  def alt(value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    Locator.leaf(:alt, value, opts)
  end

  @spec alt(locator_input(), String.t() | Regex.t()) :: Locator.t()
  def alt(locator, value) when is_binary(value) or is_struct(value, Regex) do
    and_(locator, alt(value))
  end

  @spec alt(locator_input(), String.t() | Regex.t(), keyword()) :: Locator.t()
  def alt(locator, value, opts) when (is_binary(value) or is_struct(value, Regex)) and is_list(opts) do
    and_(locator, alt(value, opts))
  end

  @spec css(String.t()) :: Locator.t()
  def css(value) when is_binary(value), do: css(value, [])

  @spec css(String.t(), keyword()) :: Locator.t()
  def css(value, opts) when is_binary(value) and is_list(opts) do
    Locator.leaf(:css, value, opts)
  end

  @spec css(locator_input(), String.t()) :: Locator.t()
  def css(locator, value) when is_binary(value) do
    and_(locator, css(value))
  end

  @spec css(locator_input(), String.t(), keyword()) :: Locator.t()
  def css(locator, value, opts) when is_binary(value) and is_list(opts) do
    and_(locator, css(value, opts))
  end

  @spec role(String.t() | atom()) :: Locator.t()
  def role(role_name) when is_binary(role_name) or is_atom(role_name), do: role(role_name, [])

  @spec role(String.t() | atom(), keyword()) :: Locator.t()
  def role(role, opts) when (is_binary(role) or is_atom(role)) and is_list(opts) do
    [role: role, name: Keyword.get(opts, :name)]
    |> maybe_put_locator_opt(opts, :exact)
    |> maybe_put_locator_opt(opts, :selector)
    |> maybe_put_locator_opt(opts, :has)
    |> Locator.normalize()
  end

  @spec role(locator_input(), String.t() | atom()) :: Locator.t()
  def role(locator, role_name) when is_binary(role_name) or is_atom(role_name) do
    and_(locator, role(role_name))
  end

  @spec role(locator_input(), String.t() | atom(), keyword()) :: Locator.t()
  def role(locator, role_name, opts) when (is_binary(role_name) or is_atom(role_name)) and is_list(opts) do
    and_(locator, role(role_name, opts))
  end

  @spec testid(String.t()) :: Locator.t()
  def testid(value) when is_binary(value), do: testid(value, [])

  @spec testid(String.t(), keyword()) :: Locator.t()
  def testid(value, opts) when is_binary(value) and is_list(opts) do
    Locator.leaf(:testid, value, opts)
  end

  @spec testid(locator_input(), String.t()) :: Locator.t()
  def testid(locator, value) when is_binary(value) do
    and_(locator, testid(value))
  end

  @spec testid(locator_input(), String.t(), keyword()) :: Locator.t()
  def testid(locator, value, opts) when is_binary(value) and is_list(opts) do
    and_(locator, testid(value, opts))
  end

  @spec and_(locator_input(), locator_input()) :: Locator.t()
  @doc """
  Composes two locators with logical AND (same-element intersection).

  Both sides must match the same DOM node.
  """
  def and_(left, right), do: Locator.compose_and(left, right)

  @spec or_(locator_input(), locator_input()) :: Locator.t()
  @doc """
  Composes two locators with logical OR (union).

  Action operations still require a unique final target at execution time.
  """
  def or_(left, right), do: Locator.compose_or(left, right)

  @spec has(locator_input(), locator_input()) :: Locator.t()
  @doc """
  Adds a descendant locator constraint (`:has`) to a locator.

  Example:

      button("Apply") |> has(testid("apply-secondary-marker"))
  """
  def has(locator, nested_locator), do: Locator.put_has(locator, nested_locator)

  @doc """
  Composes a locator that matches the closest ancestor of a nested `from` locator.

  Example:

      within(session, closest(~l".fieldset"c, from: ~l"textbox:Email"r), &assert_has(&1, ~l"can't be blank"))
  """
  @spec closest(locator_input(), keyword()) :: Locator.t()
  def closest(locator, opts) when is_list(opts) do
    from_locator_input =
      case Keyword.fetch(opts, :from) do
        {:ok, value} -> value
        :error -> raise ArgumentError, "closest/2 expects :from locator option"
      end

    case Keyword.keys(opts) -- [:from] do
      [] ->
        :ok

      extra ->
        raise ArgumentError, "closest/2 supports only :from option, got: #{inspect(extra)}"
    end

    from_locator = Locator.normalize(from_locator_input)

    if Keyword.has_key?(from_locator.opts, :from) do
      raise ArgumentError, "closest/2 does not support nested :from locators"
    end

    Locator.put_from(locator, from_locator)
  end

  def closest(_locator, _opts) do
    raise ArgumentError, "closest/2 expects keyword options"
  end

  @doc """
  Builds a locator using `~l`.

  Supported forms:
  - `~l"text"` text locator
  - `~l"text"e` exact text
  - `~l"text"i` inexact text
  - `~l"ROLE:NAME"r` role locator form
  - `~l"selector"c` CSS locator form
  - `~l"test-id"t` testid locator form (defaults to exact matching)

  Rules:
  - use at most one locator-kind modifier (`r`, `c`, or `t`)
  - `e` and `i` are mutually exclusive
  - `r` requires `ROLE:NAME` input
  """
  @spec sigil_l(String.t(), charlist()) :: Locator.t()
  def sigil_l(value, modifiers) when is_list(modifiers), do: Locator.sigil(value, modifiers)

  @spec visit(arg, String.t(), keyword()) :: arg when arg: var
  def visit(session, path, opts \\ []) when is_binary(path) do
    driver_module_for_session!(session).visit(session, path, opts)
  end

  @spec reload_page(arg, keyword()) :: arg when arg: var
  def reload_page(session, opts \\ []) do
    visit(session, current_path(session) || "/", opts)
  end

  @spec current_path(Session.t()) :: String.t() | nil
  def current_path(session) do
    session
    |> Session.current_path()
    |> Path.normalize()
  end

  @doc """
  Executes `callback` within a narrowed scope.

  `scope` must be a locator input (for example, `~l"#secondary-panel"c`).
  Use `closest/2` when scope should resolve to the nearest matching ancestor
  around a nested element (for example, a field wrapper around a label).

  For one-shot assertions, you can also use scoped assertion overloads:

      session
      |> assert_has(closest(~l".fieldset"c, from: ~l"textbox:Email"r), ~l"can't be blank")

  Browser note: when locator-based `within/3` matches an `<iframe>`, Cerberus switches
  the query root to that iframe document. Only same-origin iframes are supported.
  """
  @spec within(arg, scope_locator_input(), (arg -> arg)) :: arg when arg: var
  def within(_session, scope, _callback) when is_binary(scope) do
    raise ArgumentError, ~s{within/3 no longer accepts CSS selector strings; use ~l"..."c or css("...")}
  end

  def within(%LiveSession{} = session, locator, callback) when not is_binary(locator) and is_function(callback, 1) do
    normalized_locator = Locator.normalize(locator)
    previous_scope = Session.scope(session)
    resolved_scope = resolve_within_scope!(session, normalized_locator, previous_scope)
    live_child_scope = live_child_scope_candidate(normalized_locator, previous_scope, resolved_scope)

    case live_child_view_for_scope(session, live_child_scope) do
      {:ok, child_view} ->
        child_session =
          session
          |> Map.put(:view, child_view)
          |> Map.put(:html, Phoenix.LiveViewTest.render(child_view))
          |> Session.with_scope(nil)

        callback_result = callback.(child_session)
        restore_live_child_scope(callback_result, session, previous_scope)

      :error ->
        scoped_session = Session.with_scope(session, resolved_scope)
        callback_result = callback.(scoped_session)
        restore_scope(callback_result, previous_scope)
    end
  end

  def within(%BrowserSession{} = session, locator, callback) when not is_binary(locator) and is_function(callback, 1) do
    previous_scope = Session.scope(session)
    resolved_scope = resolve_within_scope!(session, locator, previous_scope)
    scoped_session = Session.with_scope(session, resolved_scope)
    callback_result = callback.(scoped_session)

    restore_scope(callback_result, previous_scope)
  end

  def within(session, locator, callback) when not is_binary(locator) and is_function(callback, 1) do
    previous_scope = Session.scope(session)
    resolved_scope = resolve_within_scope!(session, locator, previous_scope)
    scoped_session = Session.with_scope(session, resolved_scope)
    callback_result = callback.(scoped_session)

    restore_scope(callback_result, previous_scope)
  end

  @spec assert_path(arg, String.t() | Regex.t(), Options.path_opts()) :: arg when arg: var
  def assert_path(session, expected, opts \\ []) when is_binary(expected) or is_struct(expected, Regex) do
    call_has_timeout = Keyword.has_key?(opts, :timeout)
    opts = Options.validate_path!(opts, "assert_path/3")
    {validated_timeout, opts} = Keyword.pop(opts, :timeout, 0)
    timeout = resolve_path_timeout(session, call_has_timeout, validated_timeout)

    case session do
      %BrowserSession{} ->
        run_browser_path_assertion!(session, expected, opts, timeout, :assert_path)

      _other ->
        run_non_browser_path_assertion(session, expected, opts, timeout, :assert_path)
    end
  end

  @spec refute_path(arg, String.t() | Regex.t(), Options.path_opts()) :: arg when arg: var
  def refute_path(session, expected, opts \\ []) when is_binary(expected) or is_struct(expected, Regex) do
    call_has_timeout = Keyword.has_key?(opts, :timeout)
    opts = Options.validate_path!(opts, "refute_path/3")
    {validated_timeout, opts} = Keyword.pop(opts, :timeout, 0)
    timeout = resolve_path_timeout(session, call_has_timeout, validated_timeout)

    case session do
      %BrowserSession{} ->
        run_browser_path_assertion!(session, expected, opts, timeout, :refute_path)

      _other ->
        run_non_browser_path_assertion(session, expected, opts, timeout, :refute_path)
    end
  end

  @spec click(arg, locator_input()) :: arg when arg: var
  def click(session, locator), do: click(session, locator, [])

  @spec click(arg, scope_locator_input(), locator_input() | Options.click_opts()) :: arg when arg: var
  def click(session, scope_locator_or_locator, locator_or_opts) do
    if locator_input_term?(locator_or_opts) do
      click(session, scope_locator_or_locator, locator_or_opts, [])
    else
      Assertions.click(session, scope_locator_or_locator, locator_or_opts)
    end
  end

  @spec click(arg, scope_locator_input(), locator_input(), Options.click_opts()) :: arg when arg: var
  def click(session, scope_locator, locator, opts) when is_list(opts) do
    within(session, scope_locator, fn scoped ->
      Assertions.click(scoped, locator, opts)
    end)
  end

  @spec click_link(arg, locator_input(), Options.click_opts()) :: arg when arg: var
  def click_link(session, locator, opts \\ []) do
    click(session, locator, Keyword.put(opts, :kind, :link))
  end

  @spec click_button(arg, locator_input(), Options.click_opts()) :: arg when arg: var
  def click_button(session, locator, opts \\ []) do
    click(session, locator, Keyword.put(opts, :kind, :button))
  end

  @doc """
  Fills a form field matched by `locator`.

  Use plain string/regex label shorthand as the first option, for example:
  `fill_in(session, "Search term", "Aragorn")`.

  Helper locators like `label(...)`, `role(...)`, `placeholder(...)`, `title(...)`,
  `testid(...)`, and `css(...)` are also supported.
  Sigil examples: `fill_in(session, ~l"#search_q"c, "Aragorn")`,
  `fill_in(session, ~l"search-input"t, "Aragorn")`.
  """
  @spec fill_in(arg, locator_input(), Options.fill_in_value(), Options.fill_in_opts()) :: arg when arg: var
  def fill_in(session, locator, value, opts \\ []) when is_list(opts) do
    Assertions.fill_in(session, locator, value, opts)
  end

  @doc """
  Uploads a file into a matched file input.

  Use plain string/regex label shorthand as the first option, for example:
  `upload(session, "Avatar", "/tmp/avatar.jpg")`.

  Helper locators like `label(...)`, `testid(...)`, and `css(...)` are also supported.
  Sigil examples: `upload(session, ~l"#avatar"c, "/tmp/avatar.jpg")`,
  `upload(session, ~l"avatar-upload"t, "/tmp/avatar.jpg")`.
  """
  @spec upload(arg, locator_input(), String.t(), Options.upload_opts()) :: arg when arg: var
  def upload(session, locator, path, opts \\ [])

  def upload(session, locator, path, opts) when is_binary(path) and is_list(opts) do
    Assertions.upload(session, locator, path, opts)
  end

  def upload(_session, _locator, _path, _opts) do
    raise ArgumentError, "upload/4 expects a non-empty path string and keyword options"
  end

  @spec submit(arg, locator_input(), Options.submit_opts()) :: arg when arg: var
  def submit(session, locator, opts \\ []) do
    Assertions.submit(session, locator, opts)
  end

  @doc """
  Selects option text in a `<select>` field matched by `locator`.

  Use plain string/regex label shorthand as the first option, for example:
  `select(session, "Race", option: "Elf")`.

  For multi-select fields, pass the full desired selection on every call
  (`option: ["Elf", "Dwarf"]`). Each `select/3` call replaces the selection
  with the provided option value(s).
  Sigil examples: `select(session, ~l"#race_select"c, option: "Elf")`,
  `select(session, ~l"race-select"t, option: "Elf")`.
  """
  @spec select(arg, locator_input()) :: arg when arg: var
  def select(session, locator), do: select(session, locator, [])

  @spec select(arg, locator_input(), Options.select_opts()) :: arg when arg: var
  def select(session, locator, opts) when is_list(opts) do
    Assertions.select(session, locator, opts)
  end

  @doc """
  Chooses a radio input matched by `locator`.

  Use plain string/regex label shorthand as the first option, for example:
  `choose(session, "Email Choice")`.

  Helper locators like `label(...)`, `testid(...)`, and `css(...)` are also supported.
  Sigil examples: `choose(session, ~l"#contact_email"c)`,
  `choose(session, ~l"contact-email"t)`.
  """
  @spec choose(arg, locator_input()) :: arg when arg: var
  def choose(session, locator), do: choose(session, locator, [])

  @spec choose(arg, locator_input(), Options.choose_opts()) :: arg when arg: var
  def choose(session, locator, opts) when is_list(opts) do
    Assertions.choose(session, locator, opts)
  end

  @doc """
  Checks a checkbox matched by `locator`.

  Use plain string/regex label shorthand as the first option, for example:
  `check(session, "Subscribe to newsletter")`.

  Helper locators like `label(...)`, `testid(...)`, and `css(...)` are also supported.
  Sigil examples: `check(session, ~l"#subscribe"c)`,
  `check(session, ~l"subscribe-checkbox"t)`.
  """
  @spec check(arg, locator_input()) :: arg when arg: var
  def check(session, locator), do: check(session, locator, [])

  @spec check(arg, locator_input(), Options.check_opts()) :: arg when arg: var
  def check(session, locator, opts) when is_list(opts) do
    Assertions.check(session, locator, opts)
  end

  @doc """
  Unchecks a checkbox matched by `locator`.

  Use plain string/regex label shorthand as the first option, for example:
  `uncheck(session, "Subscribe to newsletter")`.

  Helper locators like `label(...)`, `testid(...)`, and `css(...)` are also supported.
  Sigil examples: `uncheck(session, ~l"#subscribe"c)`,
  `uncheck(session, ~l"subscribe-checkbox"t)`.
  """
  @spec uncheck(arg, locator_input()) :: arg when arg: var
  def uncheck(session, locator), do: uncheck(session, locator, [])

  @spec uncheck(arg, locator_input(), Options.check_opts()) :: arg when arg: var
  def uncheck(session, locator, opts) when is_list(opts) do
    Assertions.uncheck(session, locator, opts)
  end

  @doc """
  Asserts that content matched by `locator` exists.

  Unscoped:
  `assert_has(session, ~l"Articles")`

  Scoped:
  `assert_has(session, ~l"#secondary-panel"c, "Status: secondary")`

  In the scoped form, the second argument is a `scope_locator` and the third
  argument is a `locator`. Passing a binary/regex `locator` uses text-locator shorthand.
  """
  @spec assert_has(arg, locator_input()) :: arg when arg: var
  def assert_has(session, locator), do: assert_has(session, locator, [])

  @spec assert_has(arg, scope_locator_input(), locator_input() | Options.assert_opts()) :: arg when arg: var
  def assert_has(session, scope_locator_or_locator, locator_or_opts) do
    if locator_input_term?(locator_or_opts) do
      assert_has(session, scope_locator_or_locator, locator_or_opts, [])
    else
      Assertions.assert_has(session, scope_locator_or_locator, locator_or_opts)
    end
  end

  @spec assert_has(arg, scope_locator_input(), locator_input(), Options.assert_opts()) :: arg when arg: var
  def assert_has(session, scope_locator, locator, opts) when is_list(opts) do
    within(session, scope_locator, fn scoped ->
      Assertions.assert_has(scoped, locator, opts)
    end)
  end

  @doc """
  Refutes that content matched by `locator` exists.

  Unscoped:
  `refute_has(session, ~l"500 Internal Server Error")`

  Scoped:
  `refute_has(session, ~l"#secondary-panel"c, "Status: primary")`

  In the scoped form, the second argument is a `scope_locator` and the third
  argument is a `locator`. Passing a binary/regex `locator` uses text-locator shorthand.
  """
  @spec refute_has(arg, locator_input()) :: arg when arg: var
  def refute_has(session, locator), do: refute_has(session, locator, [])

  @spec refute_has(arg, scope_locator_input(), locator_input() | Options.assert_opts()) :: arg when arg: var
  def refute_has(session, scope_locator_or_locator, locator_or_opts) do
    if locator_input_term?(locator_or_opts) do
      refute_has(session, scope_locator_or_locator, locator_or_opts, [])
    else
      Assertions.refute_has(session, scope_locator_or_locator, locator_or_opts)
    end
  end

  @spec refute_has(arg, scope_locator_input(), locator_input(), Options.assert_opts()) :: arg when arg: var
  def refute_has(session, scope_locator, locator, opts) when is_list(opts) do
    within(session, scope_locator, fn scoped ->
      Assertions.refute_has(scoped, locator, opts)
    end)
  end

  defp driver_module_for_session!(%StaticSession{}), do: StaticSession
  defp driver_module_for_session!(%LiveSession{}), do: LiveSession
  defp driver_module_for_session!(%BrowserSession{}), do: BrowserSession

  defp driver_module_for_session!(session) do
    raise ArgumentError,
          "unsupported session #{inspect(session)}; expected a Cerberus session"
  end

  defp restore_scope(%{__struct__: _} = session, previous_scope) do
    Session.with_scope(session, previous_scope)
  end

  defp restore_scope(_value, _previous_scope) do
    raise ArgumentError, "within/3 callback must return a Cerberus session"
  end

  defp resolve_within_scope!(%BrowserSession{} = session, locator, previous_scope) do
    normalized_locator = Locator.normalize(locator)

    case BrowserSession.resolve_within_scope(session, normalized_locator, previous_scope) do
      {:ok, resolved_scope} ->
        resolved_scope

      {:error, reason} ->
        raise AssertionError, message: "within/3 failed: #{reason}"
    end
  end

  defp resolve_within_scope!(session, locator, previous_scope) do
    normalized_locator = Locator.normalize(locator)
    html = session_html!(session)

    case Html.find_scope_target(html, normalized_locator, previous_scope) do
      {:ok, %{selector: selector}} when is_binary(selector) and selector != "" ->
        selector

      {:error, reason} ->
        raise AssertionError, message: "within/3 failed: #{reason}"
    end
  end

  defp session_html!(%{html: html}) when is_binary(html), do: html
  defp session_html!(_session), do: raise(ArgumentError, "within/3 requires a session with rendered html")

  defp live_child_scope_candidate(%Locator{kind: :css, value: scope}, previous_scope, resolved_scope)
       when previous_scope in [nil, ""] and is_binary(scope) and scope != "" do
    if simple_id_selector?(scope), do: scope, else: resolved_scope
  end

  defp live_child_scope_candidate(_locator, _previous_scope, resolved_scope), do: resolved_scope

  defp restore_live_child_scope(%{__struct__: _} = callback_result, parent_session, previous_scope) do
    case callback_result do
      %LiveSession{} = live_result ->
        if Session.current_path(live_result) == Session.current_path(parent_session) do
          live_result
          |> Map.put(:view, parent_session.view)
          |> Map.put(:html, Phoenix.LiveViewTest.render(parent_session.view))
          |> Session.with_scope(previous_scope)
        else
          Session.with_scope(live_result, previous_scope)
        end

      _ ->
        Session.with_scope(callback_result, previous_scope)
    end
  end

  defp restore_live_child_scope(_value, _parent_session, _previous_scope) do
    raise ArgumentError, "within/3 callback must return a Cerberus session"
  end

  defp live_child_view_for_scope(%LiveSession{view: %View{} = view}, scope) when is_binary(scope) do
    if simple_id_selector?(scope) do
      case Phoenix.LiveViewTest.find_live_child(view, String.trim_leading(scope, "#")) do
        %View{} = child_view -> {:ok, child_view}
        _ -> :error
      end
    else
      :error
    end
  end

  defp live_child_view_for_scope(_session, _scope), do: :error

  defp simple_id_selector?(scope), do: String.match?(scope, ~r/^#[A-Za-z_][A-Za-z0-9_-]*$/)

  defp update_last_result(%{last_result: _} = session, op, observed) do
    %{session | last_result: %{op: op, observed: observed}}
  end

  defp update_last_result(session, _op, _observed), do: session

  defp run_browser_path_assertion!(session, expected, opts, timeout, op) when op in [:assert_path, :refute_path] do
    browser_opts = Keyword.put(opts, :timeout, timeout)
    run_fun = if op == :assert_path, do: &BrowserSession.assert_path/3, else: &BrowserSession.refute_path/3

    case run_fun.(session, expected, browser_opts) do
      {:ok, timed_session, observed} ->
        update_last_result(timed_session, op, observed)

      {:error, _failed_session, observed, _reason} ->
        raise AssertionError, message: format_path_error(Atom.to_string(op), observed)
    end
  end

  defp run_non_browser_path_assertion(session, expected, opts, timeout, op) when op in [:assert_path, :refute_path] do
    LiveViewTimeout.with_timeout(session, timeout, fn timed_session ->
      observed = build_path_observed(timed_session, expected, opts, timeout)
      matches? = observed.path_match? and observed.query_match?
      should_pass? = if op == :assert_path, do: matches?, else: not matches?

      if should_pass? do
        update_last_result(timed_session, op, observed)
      else
        raise AssertionError, message: format_path_error(Atom.to_string(op), observed)
      end
    end)
  end

  defp build_path_observed(session, expected, opts, timeout) do
    refreshed_session = refresh_path_assertion_session(session)
    actual_path = current_path(refreshed_session)
    path_match? = Path.match_path?(actual_path, expected, exact: Keyword.fetch!(opts, :exact))
    query_match? = Path.query_matches?(actual_path, Keyword.get(opts, :query))

    %{
      path: actual_path,
      scope: Session.scope(refreshed_session),
      expected: expected,
      query: Path.normalize_expected_query(Keyword.get(opts, :query)),
      exact: Keyword.fetch!(opts, :exact),
      timeout: timeout,
      path_match?: path_match?,
      query_match?: query_match?
    }
  end

  defp resolve_path_timeout(_session, true, validated_timeout), do: validated_timeout
  defp resolve_path_timeout(%LiveSession{} = session, false, _validated_timeout), do: Session.assert_timeout_ms(session)

  defp resolve_path_timeout(%BrowserSession{} = session, false, _validated_timeout),
    do: Session.assert_timeout_ms(session)

  defp resolve_path_timeout(_session, false, _validated_timeout), do: 0

  defp refresh_path_assertion_session(%BrowserSession{} = session), do: BrowserSession.refresh_path(session)
  defp refresh_path_assertion_session(session), do: session

  defp unwrap_conn_result(%Plug.Conn{} = conn, session, from_driver) when from_driver in [:static, :live] do
    case redirect_target(conn) do
      nil ->
        build_session_from_conn(session, conn, from_driver)

      redirect_path ->
        redirected_session =
          session
          |> static_seed_from_session(conn)
          |> visit(redirect_path)

        transition =
          transition(
            from_driver,
            Session.driver_kind(redirected_session),
            :unwrap,
            session.current_path,
            Session.current_path(redirected_session)
          )

        update_last_result(redirected_session, :unwrap, %{
          path: Session.current_path(redirected_session),
          mode: Session.driver_kind(redirected_session),
          transition: transition
        })
    end
  end

  defp unwrap_conn_result(other, _session, _from_driver) do
    raise ArgumentError,
          "unwrap callback must return a Plug.Conn in static mode, got: #{inspect(other)}"
  end

  defp unwrap_live_result({:ok, %Plug.Conn{} = conn}, %LiveSession{} = session) do
    unwrap_conn_result(conn, session, :live)
  end

  defp unwrap_live_result(%Plug.Conn{} = conn, %LiveSession{} = session) do
    unwrap_conn_result(conn, session, :live)
  end

  defp unwrap_live_result({:ok, %View{} = view, html}, %LiveSession{} = session) when is_binary(html) do
    build_live_session_from_view(session, view, html)
  end

  defp unwrap_live_result({:ok, %View{} = view, _extra}, %LiveSession{} = session) do
    build_live_session_from_view(session, view, Phoenix.LiveViewTest.render(view))
  end

  defp unwrap_live_result(%View{} = view, %LiveSession{} = session) do
    build_live_session_from_view(session, view, Phoenix.LiveViewTest.render(view))
  end

  defp unwrap_live_result({:error, {kind, %{to: to}}}, %LiveSession{} = session)
       when kind in [:redirect, :live_redirect] and is_binary(to) do
    redirected = LiveSession.follow_redirect(session, to)

    transition =
      transition(
        :live,
        Session.driver_kind(redirected),
        kind,
        session.current_path,
        Session.current_path(redirected)
      )

    update_last_result(redirected, :unwrap, %{
      path: Session.current_path(redirected),
      mode: Session.driver_kind(redirected),
      transition: transition
    })
  end

  defp unwrap_live_result({:error, {:live_patch, %{to: to}}}, %LiveSession{} = session) when is_binary(to) do
    path = Path.normalize(to) || session.current_path
    html = Phoenix.LiveViewTest.render(session.view)
    transition = transition(:live, :live, :live_patch, session.current_path, path)

    session
    |> Map.put(:html, html)
    |> Map.put(:current_path, path)
    |> update_last_result(:unwrap, %{path: path, mode: :live, transition: transition})
  end

  defp unwrap_live_result(rendered, %LiveSession{} = session) when is_binary(rendered) do
    path = maybe_live_patch_path(session.view, session.current_path)
    transition = transition(:live, :live, :unwrap, session.current_path, path)

    session
    |> Map.put(:html, rendered)
    |> Map.put(:current_path, path)
    |> update_last_result(:unwrap, %{path: path, mode: :live, transition: transition})
  end

  defp unwrap_live_result(other, _session) do
    raise ArgumentError,
          "unwrap callback in live mode must return render output, redirect tuple, view, or Plug.Conn; got: #{inspect(other)}"
  end

  defp build_session_from_conn(session, conn, from_driver) do
    current_path = DriverConn.current_path(conn, session.current_path)

    case try_live(conn) do
      {:ok, view, html} ->
        transition = transition(from_driver, :live, :unwrap, session.current_path, current_path)

        %LiveSession{
          endpoint: session.endpoint,
          conn: conn,
          view: view,
          html: html,
          form_data: Map.get(session, :form_data),
          scope: session.scope,
          current_path: current_path,
          last_result: %{op: :unwrap, observed: %{path: current_path, mode: :live, transition: transition}}
        }

      :error ->
        transition = transition(from_driver, :static, :unwrap, session.current_path, current_path)

        %StaticSession{
          endpoint: session.endpoint,
          conn: conn,
          html: conn.resp_body || "",
          form_data: Map.get(session, :form_data),
          scope: session.scope,
          current_path: current_path,
          last_result: %{op: :unwrap, observed: %{path: current_path, mode: :static, transition: transition}}
        }
    end
  end

  defp build_live_session_from_view(session, view, html) do
    path = maybe_live_patch_path(view, session.current_path)
    transition = transition(:live, :live, :unwrap, session.current_path, path)

    session
    |> Map.put(:view, view)
    |> Map.put(:html, html)
    |> Map.put(:current_path, path)
    |> update_last_result(:unwrap, %{path: path, mode: :live, transition: transition})
  end

  defp static_seed_from_session(session, conn) do
    %StaticSession{
      endpoint: session.endpoint,
      conn: conn,
      html: conn.resp_body || "",
      form_data: Map.get(session, :form_data),
      scope: session.scope,
      current_path: DriverConn.current_path(conn, session.current_path),
      last_result: session.last_result
    }
  end

  defp redirect_target(%Plug.Conn{status: status} = conn) when status in 300..399 do
    case Plug.Conn.get_resp_header(conn, "location") do
      [location | _] -> Path.normalize(location)
      _ -> nil
    end
  end

  defp redirect_target(_conn), do: nil

  defp try_live(conn) do
    case Phoenix.LiveViewTest.__live__(conn, nil, []) do
      {:ok, view, html} -> {:ok, view, html}
      _ -> :error
    end
  rescue
    _ -> :error
  end

  defp maybe_live_patch_path(nil, fallback_path), do: fallback_path

  defp maybe_live_patch_path(view, fallback_path) do
    path = Phoenix.LiveViewTest.assert_patch(view, 0)
    Path.normalize(path) || fallback_path
  rescue
    ArgumentError -> fallback_path
  end

  defp transition(from_driver, to_driver, reason, from_path, to_path) do
    %{
      from_driver: from_driver,
      to_driver: to_driver,
      reason: reason,
      from_path: from_path,
      to_path: to_path
    }
  end

  defp ensure_same_endpoint!(%{endpoint: endpoint}, %{endpoint: endpoint}), do: :ok

  defp ensure_same_endpoint!(_session, _target_session) do
    raise ArgumentError, "cannot switch tab across sessions with different endpoints"
  end

  defp maybe_put_locator_opt(locator, opts, key) do
    case Keyword.fetch(opts, key) do
      {:ok, value} -> Keyword.put(locator, key, value)
      :error -> locator
    end
  end

  defp locator_input_term?(value) when is_binary(value) or is_struct(value, Regex), do: true
  defp locator_input_term?(%Locator{}), do: true
  defp locator_input_term?(value) when is_map(value), do: true

  defp locator_input_term?(value) when is_list(value) do
    if Keyword.keyword?(value) do
      Enum.any?(Keyword.keys(value), &locator_kind_key?/1)
    else
      false
    end
  end

  defp locator_input_term?(_value), do: false

  defp locator_kind_key?(key) when is_atom(key), do: key in @locator_kind_keys
  defp locator_kind_key?(key) when is_binary(key), do: key in @locator_kind_string_keys
  defp locator_kind_key?(_key), do: false

  @includes_ecto Code.ensure_loaded?(EctoSandbox) && Code.ensure_loaded?(PhoenixSandbox)

  if @includes_ecto do
    defp checkout_ecto_repos(repo, context) do
      repo
      |> List.wrap()
      |> Enum.map(&maybe_start_sandbox_owner(&1, context))
      |> PhoenixSandbox.metadata_for(self())
      |> PhoenixSandbox.encode_metadata()
    end

    defp maybe_start_sandbox_owner(repo, context) do
      pid = EctoSandbox.start_owner!(repo, shared: not context.async)
      ExUnit.Callbacks.on_exit(fn -> stop_sandbox_owner(pid, context) end)
      repo
    rescue
      e in MatchError ->
        case e do
          %MatchError{term: {:error, {{:badmatch, {:already, :allowed}}, _}}} ->
            # Already checked out (e.g. second new_session call in same test)
            repo

          _ ->
            reraise e, __STACKTRACE__
        end
    end

    defp stop_sandbox_owner(checkout_pid, _context), do: do_stop_sandbox_owner(checkout_pid)

    defp do_stop_sandbox_owner(checkout_pid) do
      # delay = Keyword.fetch!(config, :ecto_sandbox_stop_owner_delay)
      # if delay > 0, do: Process.sleep(delay)
      EctoSandbox.stop_owner(checkout_pid)
    catch
      :exit, {:noproc, _} -> :ok
    end
  else
    defp checkout_ecto_repos(_, _) do
      "Ecto not loaded"
    end
  end

  defp format_path_error(op, observed) do
    """
    #{op} failed: expected path assertion did not hold
    actual_path: #{inspect(observed.path)}
    expected_path: #{inspect(observed.expected)}
    expected_query: #{inspect(observed.query)}
    scope: #{inspect(observed.scope)}
    exact: #{inspect(observed.exact)}
    timeout: #{inspect(observed.timeout)}
    path_match?: #{inspect(observed.path_match?)}
    query_match?: #{inspect(observed.query_match?)}
    """
  end
end