# `MishkaPay.Test`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/test.ex#L5)

Helpers for a project's tests, the way `Igniter.Test` helps test a task: start a provider, give
keys, answer HTTP calls, without a real provider and without sleeping.

For a provider's own contract tests, see `MishkaPay.ProviderCase`. For PayPal with no keys and
no network, `MishkaPay.Test.PayPal` answers as PayPal does.

## Setup

In `test/test_helper.exs`, once mishka_installer runs (it does in a project that uses it):

    MishkaPay.Test.setup!()
    ExUnit.start()

And in `config/test.exs`, so `stub_http/1` answers every provider call:

    config :mishka_pay, req_options: [plug: {Req.Test, MishkaPay.Client}]

## Webhooks without a provider

`signed_event/4` makes a Stripe event, signed the way Stripe signs it, and `deliver_event/5`
posts it through `MishkaPay.Webhook` as a test request; `stripe_object/2` gives one object of
each kind Mishka Pay acts on, so a host tests its own listeners end to end:

    conn =
      MishkaPay.Test.deliver_event("site-a", "charge.dispute.created",
        MishkaPay.Test.stripe_object(:dispute, %{"payment_intent" => "pi_1"}),
        "whsec_test")

    assert conn.status == 200

## In a test

    test "a checkout with Acme" do
      MishkaPay.Test.start_plugin!(MyApp.Pay.Acme)
      MishkaPay.Test.put_keys("acme", %{secret_key: "sk_test_1"})
      MishkaPay.Test.stub_http(fn conn -> Req.Test.json(conn, %{"id" => "ch_1"}) end)
      # ... call your code
    end

`put_keys/3` and `stub_http/1` belong to the test process and the processes it starts (through
`$callers`), so tests that use only them can be `async: true`. `start_plugin!/1` changes an event
every test sees, so a test that uses it is `async: false`.

Every wait here is on a message: a plugin is ready when its event's compiled module runs it, which
mishka_installer announces each time it rebuilds the event. Nothing sleeps; a plugin that never
starts fails the test after 30 seconds.

# `await_plugin!`

```elixir
@spec await_plugin!(module()) :: :ok
```

Returns once `plugin`, which the application already starts (its provider, its keys plugin),
runs: its event registers it a moment after boot, so the first test could otherwise come first.
Call it in `test_helper.exs`, after `setup!/0`.

# `deliver_event`

```elixir
@spec deliver_event(term(), String.t(), map(), String.t(), keyword()) :: Plug.Conn.t()
```

Posts a signed Stripe event for `tenant` through `MishkaPay.Webhook` and answers the test
connection. `opts` also takes `at:` the webhook path (`"/pay/webhooks"`).

# `put_keys`

```elixir
@spec put_keys(String.t(), map(), term()) :: :ok
```

For this test, `MishkaPay.Credentials.fetch/2` answers `keys` for `provider`, for `tenant` or for
every tenant when it is `:any`. It answers before the project's own keys plugins.

# `setup!`

```elixir
@spec setup!() :: :ok
```

Prepares a test run: mishka_installer's plugin registry (`start_registry!/0`), the table
`put_keys/3` writes to and the one PayPal's stand-in (`MishkaPay.Test.PayPal`) holds its Orders
and subscriptions in. Call it in `test_helper.exs`, whose process lives for the whole run.

# `signed_event`

```elixir
@spec signed_event(String.t(), map(), String.t(), keyword()) ::
  {binary(), [{String.t(), String.t()}]}
```

A Stripe event of `type` about `object`, signed with webhook `secret` the way Stripe signs it:
`{body, headers}`, ready to post. `opts`: `id:` (`"evt_test_..."` by default), `livemode:`
(`false`), `at:` the signing time (now).

# `signed_thin_event`

```elixir
@spec signed_thin_event(String.t(), map(), String.t(), keyword()) ::
  {binary(), [{String.t(), String.t()}]}
```

A Stripe thin event notification of `type` (`"v1.invoice.paid"`) about `related` (its
`related_object`: `%{"id" => "in_1", "type" => "invoice", "url" => "/v1/invoices/in_1"}`), as an
event destination with the thin payload sends it, signed with webhook `secret`:
`{body, headers}`. `opts` as `signed_event/4`, and `context:` the connected account it comes
from. The webhook reads the related object when the event's ids sit inside it: stub that read
with `stub_http/1`.

# `start_plugin!`

```elixir
@spec start_plugin!(module()) :: :ok
```

Starts `plugin` (a project's provider or keys plugin) under the test supervisor and returns once
its event runs it. It is unregistered when the test ends, even when it never started.

A plugin the application already runs (a provider a host starts, as Mishka CMS does) is only
awaited (`await_plugin!/1`): it stays the application's, and a test can name it either way.

# `start_registry!`

```elixir
@spec start_registry!() :: :ok
```

Starts `MishkaPay.Registry` (mishka_installer's plugin registry) when its parts are not running
and returns once it is synchronized: for a test run with no application that lists it, such as a
library's own. A project whose application lists `MishkaPay.Registry` starts nothing here;
`setup!/0` calls it first.

# `stripe_object`

```elixir
@spec stripe_object(atom(), map()) :: map()
```

One Stripe object of `kind` (`:payment_intent`, `:checkout_session`, `:charge`, `:refund`,
`:dispute`, `:invoice`, `:subscription`, `:customer` or `:tax_id`), with the ids Mishka Pay reads from it,
and `overrides` merged on top.

# `stub_http`

```elixir
@spec stub_http((Plug.Conn.t() -&gt; Plug.Conn.t())) :: :ok
```

Answers every `MishkaPay.Client` request of this test with `plug`, a function of a `Plug.Conn`
such as `&Req.Test.json(&1, %{"id" => "ch_1"})`. Needs the `:req_options` config above.

# `sweep!`

```elixir
@spec sweep!([String.t()]) :: :ok
```

Unregisters every plugin whose module name starts with one of `prefixes`
(`"Elixir.MyApp.Test."`): test plugins a killed run left in mishka_installer's registry, which
lives on disk. Call it in `test_helper.exs` before the run.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
