defmodule Patch do
  @moduledoc """
  Patch - Ergonomic Mocking for Elixir

  Patch makes it easy to mock one or more functions in a module returning a value or executing
  custom logic.  Patches and Spies allow tests to assert or refute that function calls have been
  made.

  Using Patch is as easy as adding a single line to your test case.

  ```elixir
  use Patch
  ```

  After this all the patch functions will be available, see the function documentation for
  details.
  """
  alias Patch.Mock
  alias Patch.Mock.Naming
  alias Patch.Mock.Value
  import Value
  require Value

  ## Exceptions

  defmodule ConfigurationError do
    defexception [:message]
  end

  defmodule InvalidAnyCall do
    defexception [:message]
  end

  defmodule MissingCall do
    defexception [:message]
  end

  defmodule UnexpectedCall do
    defexception [:message]
  end

  defmacro __using__(options \\ []) do
    quote do
      use Patch.Importer, unquote(options)
      use Patch.Case
    end
  end

  @doc """
  Asserts that the given module and function has been called with any arity.

  ```elixir
  patch(Example, :function, :patch)

  assert_any_call Example.function   # fails

  Example.function(1, 2, 3)

  assert_any_call Example.function   # passes
  ```
  """
  @spec assert_any_call(call :: Macro.t()) :: Macro.t()
  defmacro assert_any_call(call) do
    {module, function, arguments} = Macro.decompose_call(call)

    unless Enum.empty?(arguments) do
      raise InvalidAnyCall, message: "assert_any_call/1 does not support arguments"
    end

    quote do
      Patch.Assertions.assert_any_call(unquote(module), unquote(function))
    end
  end

  @doc """
  Asserts that the given module and function has been called with any arity.

  ```elixir
  patch(Example, :function, :patch)

  assert_any_call Example, :function   # fails

  Example.function(1, 2, 3)

  assert_any_call Example, :function   # passes
  ```

  This function exists for advanced use cases where the module or function are not literals in the
  test code.  If they are literals then `assert_any_call/1` should be preferred.
  """
  @spec assert_any_call(module :: module(), function :: atom()) :: nil
  defdelegate assert_any_call(module, function), to: Patch.Assertions

  @doc """
  Given a call will assert that a matching call was observed by the patched function.

  This macro fully supports patterns and will perform non-hygienic binding similar to ExUnit's
  `assert_receive/3` and `assert_received/2`.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  assert_called Example.function(1, 2, 3)   # passes
  assert_called Example.function(1, _, 3)   # passes
  assert_called Example.function(4, 5, 6)   # fails
  assert_called Example.function(4, _, 6)   # fails
  ```
  """
  @spec assert_called(Macro.t()) :: Macro.t()
  defmacro assert_called(call) do
    quote do
      Patch.Assertions.assert_called(unquote(call))
    end
  end

  @doc """
  Given a call will assert that a matching call was observed exactly the number of times provided
  by the patched function.

  This macro fully supports patterns and will perform non-hygienic binding similar to ExUnit's
  `assert_receive/3` and `assert_received/2`.  Any binds will bind to the latest matching call
  values.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  assert_called Example.function(1, 2, 3), 1   # passes
  assert_called Example.function(1, _, 3), 1   # passes

  Example.function(1, 2, 3)

  assert_called Example.function(1, 2, 3), 2   # passes
  assert_called Example.function(1, _, 3), 2   # passes
  ```
  """
  @spec assert_called(call :: Macro.t(), count :: Macro.t()) :: Macro.t()
  defmacro assert_called(call, count) do
    quote do
      Patch.Assertions.assert_called(unquote(call), unquote(count))
    end
  end

  @doc """
  Given a call will assert that a matching call was observed exactly once by the patched function.

  This macro fully supports patterns and will perform non-hygienic binding similar to ExUnit's
  `assert_receive/3` and `assert_received/2`.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  assert_called_once Example.function(1, 2, 3)   # passes
  assert_called_once Example.function(1, _, 3)   # passes

  Example.function(1, 2, 3)

  assert_called_once Example.function(1, 2, 3)   # fails
  assert_called_once Example.function(1, _, 3)   # fails
  ```
  """
  @spec assert_called_once(call :: Macro.t()) :: Macro.t()
  defmacro assert_called_once(call) do
    quote do
      Patch.Assertions.assert_called_once(unquote(call))
    end
  end

  @doc """
  Enable or disable library level debugging.

  There is a suite level configuration that can be set by using

  ```elixir
  config :patch,
    debug: true # or false
  ```

  Calling this helper will enable or disable debugging for a given test.

  Library level debugging can be useful when patch behavior isn't meeting expectations.
  Additional logging will occur at the debug log level using Logger to provide insight into how
  Patch is working.
  """
  @spec debug(value :: boolean()) :: :ok
  def debug(value \\ true) do
    Application.put_env(:patch, :debug, value)
  end

  @doc """
  Expose can be used to turn private functions into public functions for the
  purpose of testing them.

  To expose every private function as a public function, pass the sentinel value `:all`.

  ```elixir
  expose(Example, :all)
  ```

  Otherwise pass a `Keyword.t(arity)` of the functions to expose.

  For example, if one wanted to expose `private_function/1` and `private_function/2`.

  ```elixir
  expose(Example, [private_function: 1, private_function: 2])
  ```

  After exposing a function, attempting to call the exposed function will cause the Elixir
  Compiler to flag calls to exposed functions as a warning.  There are companion macros
  `private/1` and `private/2` that test authors can wrap their calls with to prevent warnings.
  """
  @spec expose(module :: module, exposes :: Patch.Mock.exposes()) :: :ok | {:error, term()}
  def expose(module, exposes) do
    Mock.expose(module, exposes)
  end

  @doc """
  Fakes out a module with an alternative implementation.

  The real module can still be accessed with `real/1`.

  For example, if your project has the module `Example.Datastore` and there's a fake available in the testing
  environment named `Example.Test.InMemoryDatastore`  the following table describes which calls are executed by which
  code before and after faking with the following call.

  ```elixir
  fake(Example.Datastore, Example.Test.InMemoryDatastore)
  ```

  | Calling Code                         | Responding Module before fake/2      | Responding Module after fake/2       |
  |--------------------------------------|--------------------------------------|--------------------------------------|
  | Example.Datastore.get/1              | Example.Datastore.get/1              | Example.Test.InMemoryDatastore.get/1 |
  | Example.Test.InMemoryDatastore.get/1 | Example.Test.InMemoryDatastore.get/1 | Example.Test.InMemoryDatastore.get/1 |
  | real(Example.Datastore).get/1        | (UndefinedFunctionError)             | Example.Datastore.get/1              |

  The fake module can use the renamed module to access the original implementation.
  """
  @spec fake(real_module :: module(), fake_module :: module()) :: :ok
  def fake(real_module, fake_module) do
    {:ok, _} = Mock.module(real_module)

    real_functions = Patch.Reflection.find_functions(real_module)
    fake_functions = Patch.Reflection.find_functions(fake_module)

    Enum.each(fake_functions, fn {name, arity} ->
      is_real_function? = Enum.any?(real_functions, &match?({^name, ^arity}, &1))

      if is_real_function? do
        patch(
          real_module,
          name,
          callable(
            fn args ->
              apply(fake_module, name, args)
            end,
            :list
          )
        )
      end
    end)
  end

  @spec inject(
          tag :: Patch.Listener.tag(),
          target :: Patch.Listener.target(),
          keys :: [term(), ...],
          options :: [Patch.Listener.option()]
        ) :: {:ok, pid()} | {:error, :not_found} | {:error, :invalid_keys}
  def inject(tag, target, keys, options \\ []) do
    state = :sys.get_state(target)

    case Patch.Access.fetch(state, keys) do
      {:ok, subject} ->
        with {:ok, listener} <- listen(tag, subject, options) do
          replace(target, keys, listener)
          {:ok, listener}
        end

      :error ->
        {:error, :invalid_keys}
    end
  end

  @doc """
  Get all the observed calls to a module.  These calls are expressed as a `{name, argument}` tuple
  and can either be provided in ascending (oldest first) or descending (newest first) order by
  providing a sorting of `:asc` or `:desc`, respectively.

  ```elixir
  Example.example(1, 2, 3)
  Example.function(:a)

  assert history(Example) == [{:example, [1, 2, 3]}, {:function, [:a]}]
  assert history(Example, :desc) == [{:function, [:a]}, {:example, [1, 2, 3]}]
  ```

  For asserting or refuting that a call happened the `assert_called/1`, `assert_any_call/2`,
  `refute_called/1`, and `refute_any_call/2` functions provide a more convenient API.
  """
  @spec history(module :: module(), sorting :: :asc | :desc) :: [Mock.History.entry()]
  def history(module, sorting \\ :asc) do
    module
    |> Mock.history()
    |> Mock.History.entries(sorting)
  end

  @doc """
  Starts a listener process.

  Each listener should provide a unique `tag` that will be used when forwarding messages to the
  test process.

  ## Named Processes

  When used on a named process, this is sufficient to begin intercepting all messages to the named
  process.

  ```elixir
  listen(:listener, Example)
  ```

  ## Unnamed Processes

  When used on an unnamed process, the process that is spawned will forward any messages to the
  caller and target process but any processes holding a reference to the old pid will need to be
  updated.

  `replace/3` can be used to replace part of a running process with the listener

  ```elixir
  {:ok, listener} = listen(:listener, original)
  replace(target, [:original], listener)
  ```

  `inject/3` provides a nice convenience when you want to wrap a listener around the pid in the
  state.

  ```elixir
  inject(:listener, target, [:original])
  ```

  This code will look for the key `:original` in the `target` process's state, and wrap it with
  a listener tagged with `:listener`

  ## Substituting for a Process

  Listeners can also act as a complete substitute for a process.  This is useful in scenarios
  where one Process starts other Processes but starting those Processes is outside of the bounds
  of the test.  In those cases you can start a "targetless listener."

  `replace/3` can be used to replace part of a running process with the substitute listener.

  ```elixir
  {:ok, listener} = listen(:listener)
  replace(target, [:original], listener)
  ```

  `inject/3` provides a nice conveninece when the state already has a nil that you want to replace
  with a listener

  ```elixir
  inject(:listener, target, [:original])
  ```

  This code will look for the key `:original` in the `target` process's state, finding it `nil` it
  will create a "targetless listener" tagged with `:listener` and put it in the state.
  """
  @spec listen(
          tag :: Patch.Listener.tag(),
          target :: Patch.Listener.target(),
          options :: [Patch.Listener.option()]
        ) :: {:ok, pid()} | {:error, :not_found}
  def listen(tag, target \\ nil, options \\ []) do
    Patch.Listener.Supervisor.start_child(self(), tag, target, options)
  end

  @doc """
  Patches a function in a module

  When called with a function the function will be called instead of the original function and its
  results returned.

  ```elixir
  patch(Example, :function, fn arg -> {:mock, arg} end)

  assert Example.function(:test) == {:mock, :test}
  ```

  To handle multiple arities create a `callable/2` with the `:list` option and the arguments will
  be wrapped to the function in a list.

  ```elixir
  patch(Example, :function, callable(fn
    [] ->
      :zero

    [a] ->
      {:one, a}

    [a, b] ->
      {:two, a, b}
  end, :list))

  assert Example.function() == :zero
  assert Example.function(1) == {:one, 1}
  assert Example.function(1, 2) == {:two, 1, 2}
  ```

  To provide a function as a literal value to be returned, use the `scalar/1` function.

  ```elixir
  patch(Example, :function, scalar(fn arg -> {:mock, arg} end))

  callable = Example.function()
  assert callable.(:test) == {:mock, :test}
  ```

  The function `cycle/1` can be given a list which will be infinitely cycled when the function is
  called.

  ```elixir
  patch(Example, :function, cycle([1, 2, 3]))

  assert Example.function() == 1
  assert Example.function() == 2
  assert Example.function() == 3
  assert Example.function() == 1
  assert Example.function() == 2
  assert Example.function() == 3
  assert Example.function() == 1
  ```

  The function `raises/1` can be used to `raise/1` a `RuntimeError` when the function is called.

  ```elixir
  patch(Example, :function, raises("patched"))

  assert_raise RuntimeError, "patched", fn ->
    Example.function()
  end
  ```

  The function `raises/2` can be used to `raise/2` any exception with any attributes when the function
  is called.

  ```elixir
  patch(Example, :function, raises(ArgumentError, message: "patched"))

  assert_raise ArgumentError, "patched", fn ->
    Example.function()
  end
  ```

  The function `sequence/1` can be given a list which will be used until a single value is
  remaining, the remaining value will be returned on all subsequent calls.

  ```elixir
  patch(Example, :function, sequence([1, 2, 3]))

  assert Example.function() == 1
  assert Example.function() == 2
  assert Example.function() == 3
  assert Example.function() == 3
  assert Example.function() == 3
  assert Example.function() == 3
  assert Example.function() == 3
  ```

  The function `throws/1` can be given a value to `throw/1` when the function is called.

  ```elixir
  patch(Example, :function, throws(:patched))

  assert catch_throw(Example.function()) == :patched
  ```

  Any other value will be returned as a literal scalar value when the function is called.

  ```elixir
  patch(Example, :function, :patched)

  assert Example.function() == :patched
  ```
  """
  @spec patch(module :: module(), function :: atom(), value :: Value.t()) :: Value.t()
  def patch(module, function, %value_module{} = value) when is_value(value_module) do
    {:ok, _} = Patch.Mock.module(module)
    :ok = Patch.Mock.register(module, function, value)
    value
  end

  @spec patch(module :: module(), function :: atom(), callable) :: callable
        when callable: function()
  def patch(module, function, callable) when is_function(callable) do
    patch(module, function, callable(callable))
    callable
  end

  @spec patch(module :: module(), function :: atom(), return_value) :: return_value
        when return_value: term()
  def patch(module, function, return_value) do
    patch(module, function, scalar(return_value))
    return_value
  end

  @doc """
  Suppress warnings for using exposed private functions in tests.

  Patch allows you to make a private function public via the `expose/2` function.  Exposure
  happens dynamically at test time. The Elixir Compiler will flag calls to exposed functions as a
  warning.

  One way around this is to change the normal function call into an `apply/3` but this is
  cumbersome and makes tests harder to read.

  This macro just rewrites a normal looking call into an `apply/3` so the compiler won't complain
  about calling an exposed function.

  ```elixir
  expose(Example, :all)

  patch(Example, :private_function, :patched)

  assert Example.private_function() == :patched   # Compiler will warn about call to undefined function
  assert apply(Example, :private_function, []) == :patched   # Compiler will not warn
  assert private(Example.private_function()) == :patched     # Same as previous line, but looks nicer.
  ```
  """
  @spec private(Macro.t()) :: Macro.t()
  defmacro private(call) do
    {module, function, arguments} = Macro.decompose_call(call)

    quote do
      apply(unquote(module), unquote(function), unquote(arguments))
    end
  end

  @doc """
  Suppress warnings for using exposed private functions in tests.

  Patch allows you to make a private function public via the `expose/2` function.  Exposure
  happens dynamically at test time. The Elixir Compiler will flag calls to exposed functions as a
  warning.

  One way around this is to change the normal function call into an `apply/3` but this is
  cumbersome and makes tests harder to read.

  This macro just rewrites a normal looking call into an `apply/3` so the compiler won't complain
  about calling an exposed function, with support for pipelines.

  ```elixir
  expose(Example, :all)

  example_that_warns =
    Example.new()
    |> Example.private_function()  # Compiler will warn about call to undefined function


  example_that_does_not_warn
    Example.new()
    |> private(Example.private_function())  # Compiler will not warn and Example.new() is provided
                                            # as the first argument to Example.private_function/1
  ```
  """
  @spec private(Macro.t(), Macro.t()) :: Macro.t()
  defmacro private(argument, call) do
    {module, function, arguments} = Macro.decompose_call(call)

    quote do
      apply(unquote(module), unquote(function), [unquote(argument) | unquote(arguments)])
    end
  end

  @doc """
  Gets the real module name for a fake.

  This is useful for Fakes that want to defer some part of the functionality back to the real
  module.

  ```elixir
  def Example do
    def calculate(a) do
      # ...snip some complex calculations...
      result
    end
  end

  def Example.Fake do
    import Patch, only: [real: 1]

    def calculate(a) do
      real_result = real(Example).calculate(a)

      {:fake, real_result}
    end
  end
  """
  @spec real(module :: module()) :: module()
  def real(module) do
    Naming.original(module)
  end

  @doc """
  Refutes that the given module and function has been called with any arity.

  ```elixir
  patch(Example, :function, :patch)

  refute_any_call Example.function   # passes

  Example.function(1, 2, 3)

  refute_any_call Example.function   # fails
  ```
  """
  @spec refute_any_call(call :: Macro.t()) :: Macro.t()
  defmacro refute_any_call(call) do
    {module, function, arguments} = Macro.decompose_call(call)

    unless Enum.empty?(arguments) do
      raise InvalidAnyCall, message: "refute_any_call/1 does not support arguments"
    end

    quote do
      Patch.Assertions.refute_any_call(unquote(module), unquote(function))
    end
  end

  @doc """
  Refutes that the given module and function has been called with any arity.

  ```elixir
  patch(Example, :function, :patch)

  refute_any_call Example, :function   # passes

  Example.function(1, 2, 3)

  refute_any_call Example, :function   # fails
  ```

  This function exists for advanced use cases where the module or function are not literals in the
  test code.  If they are literals then `refute_any_call/1` should be preferred.
  """
  @spec refute_any_call(module :: module(), function :: atom()) :: nil
  defdelegate refute_any_call(module, function), to: Patch.Assertions

  @doc """
  Given a call will refute that a matching call was observed by the patched function.

  This macro fully supports patterns.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  refute_called Example.function(4, 5, 6)   # passes
  refute_called Example.function(4, _, 6)   # passes
  refute_called Example.function(1, 2, 3)   # fails
  refute_called Example.function(1, _, 3)   # fails
  ```
  """
  @spec refute_called(call :: Macro.t()) :: Macro.t()
  defmacro refute_called(call) do
    quote do
      Patch.Assertions.refute_called(unquote(call))
    end
  end

  @doc """
  Given a call will refute that a matching call was observed exactly the number of times provided
  by the patched function.

  This macro fully supports patterns.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  refute_called Example.function(1, 2, 3), 2   # passes
  refute_called Example.function(1, _, 3), 2   # passes

  Example.function(1, 2, 3)

  refute_called Example.function(1, 2, 3), 1   # passes
  refute_called Example.function(1, _, 3), 1   # passes
  ```
  """
  @spec refute_called(call :: Macro.t(), count :: Macro.t()) :: Macro.t()
  defmacro refute_called(call, count) do
    quote do
      Patch.Assertions.refute_called(unquote(call), unquote(count))
    end
  end

  @doc """
  Given a call will refute that a matching call was observed exactly once by the patched function.

  This macro fully supports patterns.

  ```elixir
  patch(Example, :function, :patch)

  Example.function(1, 2, 3)

  refute_called_once Example.function(1, 2, 3)   # fails
  refute_called_once Example.function(1, _, 3)   # fails

  Example.function(1, 2, 3)

  refute_called_once Example.function(1, 2, 3)   # passes
  refute_called_once Example.function(1, _, 3)   # passes
  ```
  """
  @spec refute_called_once(call :: Macro.t()) :: Macro.t()
  defmacro refute_called_once(call) do
    quote do
      Patch.Assertions.refute_called_once(unquote(call))
    end
  end

  @doc """
  Convenience function for replacing part of the state of a running process.

  Uses the `Access` module to traverse the state structure according to the given `keys`.

  Structs have special handling so that they can be updated without having to implement the
  `Access` behavior.

  For example to replace the key `:key` in the map found under the key `:map` with the value
  `:replaced`

  ```elixir
  replace(target, [:map, :key], :replaced)
  ```
  """
  @spec replace(target :: GenServer.server(), keys :: [term(), ...], value :: term()) :: term()
  def replace(target, keys, value) do
    :sys.replace_state(target, &Patch.Access.put(&1, keys, value))
  end

  @doc """
  Remove any mocks or spies from the given module

  ```elixir
  original = Example.example()

  patch(Example, :example, :patched)
  assert Example.example() == :patched

  restore(Example)
  assert Example.example() == original
  ```
  """
  @spec restore(module :: module()) :: :ok | {:error, term()}
  def restore(module) do
    Mock.restore(module)
  end

  @doc """
  Remove any patches associated with a function in a module.

  ```elixir
  original = Example.example()

  patch(Example, :example, :example_patch)
  patch(Example, :other, :other_patch)

  assert Example.example() == :example_patch
  assert Example.other() == :other_patch

  restore(Example, :example)

  assert Example.example() == original
  assert Example.other() == :other_patch
  """
  @spec restore(module :: module(), name :: atom()) :: :ok | {:error, term()}
  def restore(module, name) do
    Mock.restore(module, name)
  end

  @doc """
  Spies on the provided module

  Once a module has been spied on the calls to that module can be asserted / refuted without
  changing the behavior of the module.

  ```elixir
  spy(Example)

  Example.example(1, 2, 3)

  assert_called Example.example(1, 2, 3)   # passes
  """
  @spec spy(module :: module()) :: :ok
  def spy(module) do
    {:ok, _} = Mock.module(module)
    :ok
  end
end