# Testing

`Twilio.Test` provides process-scoped HTTP stubs via NimbleOwnership, so
your tests can run with `async: true` without interference.

## Setup

Start the test stub server in your `test/test_helper.exs`:

```elixir
Twilio.Test.start()
ExUnit.start()
```

## Stubbing Requests

Use `Twilio.Test.stub/1` to define how the HTTP layer responds. The stub
function receives `(method, url, headers, body)` and returns a
`{status, headers, body}` tuple:

```elixir
defmodule MyApp.NotifierTest do
  use ExUnit.Case, async: true

  test "sends an SMS" do
    Twilio.Test.stub(fn _method, _url, _headers, _body ->
      {201, [], ~s({"sid": "SMxxx", "status": "queued", "body": "Hello!"})}
    end)

    client = Twilio.client("ACtest", "token")

    {:ok, msg} = Twilio.Api.V2010.MessageService.create(client, %{
      "To" => "+15551234567",
      "From" => "+15559876543",
      "Body" => "Hello!"
    })

    assert msg.sid == "SMxxx"
    assert msg.status == "queued"
  end
end
```

## Asserting on Request Parameters

The stub receives the full request, so you can assert on the URL, body,
headers, or method:

```elixir
test "sends correct params" do
  Twilio.Test.stub(fn method, url, _headers, body ->
    assert method == "POST"
    assert url =~ "/Messages.json"

    params = URI.decode_query(body)
    assert params["To"] == "+15551234567"
    assert params["Body"] == "Hello!"

    {201, [], ~s({"sid": "SMxxx"})}
  end)

  client = Twilio.client("ACtest", "token")
  {:ok, _} = Twilio.Api.V2010.MessageService.create(client, %{
    "To" => "+15551234567",
    "Body" => "Hello!"
  })
end
```

## Simulating Errors

Return non-200 status codes to test error handling:

```elixir
test "handles invalid number" do
  Twilio.Test.stub(fn _method, _url, _headers, _body ->
    {400, [],
     ~s({"code": 21211, "message": "The 'To' number is not a valid phone number.", "status": 400})}
  end)

  client = Twilio.client("ACtest", "token")
  {:error, err} = Twilio.Api.V2010.MessageService.create(client, %{
    "To" => "not-a-number",
    "From" => "+15559876543",
    "Body" => "Test"
  })

  assert err.code == 21211
  assert err.message =~ "not a valid phone number"
end
```

## Testing Pagination

Stub multiple pages to test auto-paging behavior:

```elixir
test "streams through pages" do
  call_count = :counters.new(1, [:atomics])

  Twilio.Test.stub(fn _method, url, _headers, _body ->
    count = :counters.get(call_count, 1)
    :counters.add(call_count, 1, 1)

    if count == 0 do
      {200, [], ~s({
        "messages": [{"sid": "SM001"}, {"sid": "SM002"}],
        "meta": {
          "key": "messages",
          "next_page_url": "#{url}?Page=1",
          "page": 0,
          "page_size": 2
        }
      })}
    else
      {200, [], ~s({
        "messages": [{"sid": "SM003"}],
        "meta": {
          "key": "messages",
          "next_page_url": null,
          "page": 1,
          "page_size": 2
        }
      })}
    end
  end)

  client = Twilio.client("ACtest", "token")
  items = client
  |> Twilio.Messaging.V1.MessageService.stream()
  |> Enum.to_list()

  assert length(items) == 3
end
```

## Process Isolation

Stubs are scoped to the test process that defines them. This means:

- **`async: true` works** — concurrent tests don't interfere with each other
- **No shared state** — each test sets up its own stubs independently
- **Automatic cleanup** — stubs are removed when the test process exits

Under the hood, `Twilio.Test` uses `NimbleOwnership` to associate stubs
with the calling process. If your test spawns child processes that make
Twilio calls, you can allow them to share the parent's stubs:

```elixir
test "works in spawned processes" do
  Twilio.Test.stub(fn _method, _url, _headers, _body ->
    {200, [], ~s({"sid": "SMxxx", "status": "sent"})}
  end)

  task = Task.async(fn ->
    Twilio.Test.allow(self())
    client = Twilio.client("ACtest", "token")
    Twilio.Api.V2010.MessageService.fetch(client, "SMxxx")
  end)

  assert {:ok, msg} = Task.await(task)
  assert msg.sid == "SMxxx"
end
```

## Testing Webhooks

`Twilio.Webhook` functions are pure — they don't make HTTP calls, so test
them directly without stubs:

```elixir
test "validates webhook signature" do
  auth_token = "12345"
  url = "https://myapp.com/twilio/webhook"
  params = %{"CallSid" => "CA123", "From" => "+14158675310"}

  signature = Twilio.Webhook.build_signature(url, params, auth_token)

  assert Twilio.Webhook.valid?(url, params, signature, auth_token)
  refute Twilio.Webhook.valid?(url, params, "wrong_signature", auth_token)
end
```

## Testing TwiML

TwiML builders are also pure functions — assert on the generated XML:

```elixir
test "generates voice response" do
  xml = Twilio.TwiML.VoiceResponse.new()
  |> Twilio.TwiML.VoiceResponse.say("Hello!", voice: "alice")
  |> Twilio.TwiML.VoiceResponse.to_xml()

  assert xml =~ ~s(<Say voice="alice">Hello!</Say>)
  assert xml =~ "<Response>"
end
```

## Tips

- **Keep stubs minimal.** Only include the fields your test actually checks.
  The deserializer handles missing fields gracefully.
- **Use `async: true`.** The ownership model is designed for it.
- **Don't stub webhooks or TwiML.** They are pure functions that don't make
  HTTP calls.
- **Stub the response format correctly.** Twilio returns JSON with
  `snake_case` keys (e.g. `"account_sid"`, `"date_created"`).