Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

42.9 KB
Raw Blame
defmodule FirecrawlTest do
  use ExUnit.Case

  test "sends no authorization header when no API key is configured" do
    old = Application.get_env(:firecrawl, :api_key)
    Application.delete_env(:firecrawl, :api_key)
    on_exit(fn -> if old, do: Application.put_env(:firecrawl, :api_key, old) end)

    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})
      {request, Req.Response.new(status: 200, body: "")}
    end

    assert {:ok, %Req.Response{status: 200}} = Firecrawl.get_credit_usage(adapter: adapter)
    assert_receive {:request, request}
    refute Map.has_key?(request.headers, "authorization")
  end

  test "does not raise when API key is in application config" do
    Application.put_env(:firecrawl, :api_key, "test-config-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    result = Firecrawl.get_queue_status(base_url: "http://localhost:1", retry: false)
    assert {:error, _} = result
  end

  test "does not raise when API key is passed as option" do
    old = Application.get_env(:firecrawl, :api_key)
    Application.delete_env(:firecrawl, :api_key)
    on_exit(fn -> if old, do: Application.put_env(:firecrawl, :api_key, old) end)

    result =
      Firecrawl.get_queue_status(
        api_key: "test-opt-key",
        base_url: "http://localhost:1",
        retry: false
      )

    assert {:error, _} = result
  end

  test "non-bang returns {:error, _} for missing required params" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %NimbleOptions.ValidationError{}} =
             Firecrawl.scrape_and_extract_from_url([])
  end

  test "non-bang returns {:error, _} for unknown keys (typo detection)" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %NimbleOptions.ValidationError{message: msg}} =
             Firecrawl.scrape_and_extract_from_url(url: "https://example.com", typo_option: true)

    assert msg =~ "unknown options"
  end

  test "non-bang returns {:error, _} for wrong types" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %NimbleOptions.ValidationError{}} =
             Firecrawl.crawl_urls(url: "https://example.com", limit: "not an integer")
  end

  test "bang raises for missing required params" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert_raise NimbleOptions.ValidationError, ~r/required/, fn ->
      Firecrawl.scrape_and_extract_from_url!([])
    end
  end

  test "bang raises for unknown keys" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert_raise NimbleOptions.ValidationError, ~r/unknown options/, fn ->
      Firecrawl.scrape_and_extract_from_url!(url: "https://example.com", typo_option: true)
    end
  end

  test "create_monitor accepts a search target" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    result =
      Firecrawl.create_monitor(
        [
          name: "search monitor",
          schedule: [interval: "24h"],
          goal: "Track new mentions",
          judge_enabled: true,
          targets: [
            [
              type: "search",
              queries: ["firecrawl"],
              search_window: "24h",
              include_domains: ["example.com"],
              exclude_domains: [],
              max_results: 10
            ]
          ]
        ],
        base_url: "http://localhost:1",
        retry: false
      )

    # Validation passes (it is not a ValidationError); the request itself fails
    # because the base_url is unreachable.
    assert {:error, error} = result
    refute match?(%NimbleOptions.ValidationError{}, error)
  end

  test "accepts atom values for enum params" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    result =
      Firecrawl.crawl_urls(
        [url: "https://example.com", sitemap: :skip],
        base_url: "http://localhost:1",
        retry: false
      )

    assert {:error, _} = result
  end

  test "accepts string values for enum params (model)" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    result =
      Firecrawl.start_agent(
        [prompt: "test", model: "spark-1-mini"],
        base_url: "http://localhost:1",
        retry: false
      )

    assert {:error, err} = result
    refute match?(%NimbleOptions.ValidationError{}, err),
      "Expected connection error, got validation error: #{inspect(err)}"
  end

  test "start_agent sends effort in the request body" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "agent-job"})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.start_agent(
               [prompt: "find pricing", effort: "high"],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["effort"] == "high"
    assert body["prompt"] == "find pricing"
    # @sdk_origin is built from the mix.exs @version so the two cannot drift
    assert body["origin"] == "elixir-sdk@" <> Mix.Project.config()[:version]
  end

  test "start_agent rejects invalid effort values" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %NimbleOptions.ValidationError{}} =
             Firecrawl.start_agent(prompt: "test", effort: "ultra")
  end

  # Sends the request body as decoded from the bytes put on the wire.
  defp wire_body_adapter(parent) do
    fn request ->
      send(parent, {:body, request.body |> IO.iodata_to_binary() |> Jason.decode!()})
      {request, Req.Response.new(status: 200, body: "")}
    end
  end

  test "start_agent and start_agent! send thread_id, mode and exchange with camelCase keys at every level" do
    opts = [api_key: "test-key", adapter: wire_body_adapter(self())]
    thread_id = "6f1c2a4e-0d8b-4c1e-9a57-3b2f8e9d1c40"
    origin = "elixir-sdk@" <> Mix.Project.config()[:version]

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.start_agent(
               [
                 prompt: "find leads",
                 thread_id: thread_id,
                 mode: :chat,
                 exchange: [
                   enabled: true,
                   toolkits: ["apollo"],
                   max_calls: 5,
                   require_approval: true,
                   approve: [approval_id: "approval-1", call_ids: ["c1"], always: true],
                   on_terms_required: :ask
                 ]
               ],
               opts
             )

    assert_receive {:body, body}

    assert body == %{
             "prompt" => "find leads",
             "threadId" => thread_id,
             "mode" => "chat",
             "exchange" => %{
               "enabled" => true,
               "toolkits" => ["apollo"],
               "maxCalls" => 5,
               "requireApproval" => true,
               "approve" => %{"approvalId" => "approval-1", "callIds" => ["c1"], "always" => true},
               "onTermsRequired" => "ask"
             },
             "origin" => origin
           }

    assert %Req.Response{status: 200} =
             Firecrawl.start_agent!(
               [
                 prompt: "skip that",
                 thread_id: thread_id,
                 exchange: [decline: [approval_id: "approval-2"]]
               ],
               opts
             )

    assert_receive {:body, body}

    assert body == %{
             "prompt" => "skip that",
             "threadId" => thread_id,
             "exchange" => %{"decline" => %{"approvalId" => "approval-2"}},
             "origin" => origin
           }
  end

  test "start_agent leaves omitted thread, mode and exchange fields out of the body" do
    opts = [api_key: "test-key", adapter: wire_body_adapter(self())]
    origin = "elixir-sdk@" <> Mix.Project.config()[:version]

    assert {:ok, _} = Firecrawl.start_agent([prompt: "find pricing"], opts)
    assert_receive {:body, body}
    assert body == %{"prompt" => "find pricing", "origin" => origin}

    assert {:ok, _} = Firecrawl.start_agent([prompt: "find pricing", exchange: [toolkits: ["apollo"]]], opts)
    assert_receive {:body, body}
    assert body == %{"prompt" => "find pricing", "exchange" => %{"toolkits" => ["apollo"]}, "origin" => origin}

    assert {:ok, _} = Firecrawl.start_agent([prompt: "find pricing", exchange: []], opts)
    assert_receive {:body, body}
    assert body == %{"prompt" => "find pricing", "exchange" => %{}, "origin" => origin}
  end

  test "start_agent rejects unknown or incomplete exchange keys before sending" do
    opts = [api_key: "test-key", adapter: wire_body_adapter(self())]

    assert {:error, %NimbleOptions.ValidationError{message: msg}} =
             Firecrawl.start_agent([prompt: "find leads", exchange: [max_call: 5]], opts)

    assert msg =~ "unknown options [:max_call]"

    assert {:error, %NimbleOptions.ValidationError{message: msg}} =
             Firecrawl.start_agent([prompt: "find leads", exchange: [approve: [call_ids: ["c1"]]]], opts)

    assert msg =~ "required :approval_id option not found"

    refute_received {:body, _}
  end

  test "get_agent_trace hits /v2/agent/:id/trace" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body:
          Jason.encode!(%{
            "success" => true,
            "id" => "job-123",
            "events" => [
              %{
                "type" => "run.started",
                "schemaVersion" => 1,
                "eventId" => "evt-1",
                "runId" => "job-123",
                "occurredAt" => "2026-08-26T00:00:00Z",
                "producerSequence" => 0,
                "agent" => %{"id" => "agent", "name" => "spark-2"}
              }
            ],
            "creditsUsed" => 5
          })
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.get_agent_trace("job-123", api_key: "test-key", adapter: adapter)

    assert_receive {:request, request}
    assert request.url.path == "/v2/agent/job-123/trace"
    refute Map.has_key?(URI.decode_query(request.url.query || ""), "liveView")
  end

  test "get_agent_trace sends liveView=true query param when live_view: true" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body:
          Jason.encode!(%{
            "success" => true,
            "id" => "job-123",
            "events" => [],
            "creditsUsed" => 5,
            "activeBrowserSessions" => [
              %{
                "id" => "sess-1",
                "liveViewUrl" => "https://example.com/live",
                "viewport" => %{"width" => 1280, "height" => 720}
              }
            ]
          })
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.get_agent_trace("job-123",
               live_view: true,
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}
    assert request.url.path == "/v2/agent/job-123/trace"
    assert URI.decode_query(request.url.query || "")["liveView"] == "true"
  end

  test "get_agent_trace! returns the response on success" do
    adapter = fn request ->
      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "job-123", "events" => [], "creditsUsed" => 5})
      )

      {request, resp}
    end

    assert %Req.Response{status: 200} =
             Firecrawl.get_agent_trace!("job-123", api_key: "test-key", adapter: adapter)
  end

  test "list_agents hits /v2/agent" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body:
          Jason.encode!(%{
            "success" => true,
            "agents" => [
              %{
                "id" => "job-123",
                "createdAt" => "2026-08-31T12:00:00.000Z",
                "targetHint" => "https://example.com",
                "origin" => "api",
                "settings" => %{"hidden" => false, "starred" => true, "label" => "prod"},
                "status" => "completed",
                "options" => %{"urls" => ["https://example.com"], "prompt" => "find pricing", "model" => "spark-1-pro"}
              }
            ]
          })
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200} = response} =
             Firecrawl.list_agents([], api_key: "test-key", adapter: adapter)

    assert_receive {:request, request}
    assert request.url.path == "/v2/agent"
    refute Map.has_key?(URI.decode_query(request.url.query || ""), "before")

    assert [%{"id" => "job-123", "status" => "completed"}] = response.body["agents"]
  end

  test "list_agents sends before query param" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body:
          Jason.encode!(%{
            "success" => true,
            "agents" => [],
            "next" => "https://api.firecrawl.dev/v2/agent?before=1756600000000"
          })
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.list_agents([before: 1_756_600_000_000], api_key: "test-key", adapter: adapter)

    assert_receive {:request, request}
    assert request.url.path == "/v2/agent"
    assert URI.decode_query(request.url.query || "")["before"] == "1756600000000"
  end

  test "list_agents! returns the response on success" do
    adapter = fn request ->
      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "agents" => []})
      )

      {request, resp}
    end

    assert %Req.Response{status: 200} =
             Firecrawl.list_agents!([], api_key: "test-key", adapter: adapter)
  end

  test "get_agent_snapshot hits /v2/agent/:id/snapshots/:snapshot_id" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body:
          Jason.encode!(%{
            "success" => true,
            "id" => "job-123",
            "snapshotId" => "snap-456",
            "snapshot" => "snapshot content"
          })
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.get_agent_snapshot("job-123", "snap-456", api_key: "test-key", adapter: adapter)

    assert_receive {:request, request}
    assert request.url.path == "/v2/agent/job-123/snapshots/snap-456"
  end

  test "accepts string values for enum params (sitemap)" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    result =
      Firecrawl.crawl_urls(
        [url: "https://example.com", sitemap: "skip"],
        base_url: "http://localhost:1",
        retry: false
      )

    assert {:error, err} = result
    refute match?(%NimbleOptions.ValidationError{}, err),
      "Expected connection error, got validation error: #{inspect(err)}"
  end

  test "parse_file returns error tuple when filename is empty" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %ArgumentError{message: msg}} =
             Firecrawl.parse_file([filename: "", data: "x"])

    assert msg =~ "filename cannot be empty"
  end

  test "parse_file returns error tuple when data is nil" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %ArgumentError{message: msg}} =
             Firecrawl.parse_file([filename: "doc.pdf", data: nil])

    assert msg =~ "file data cannot be empty"
  end

  test "parse_file rejects unknown options" do
    Application.put_env(:firecrawl, :api_key, "test-key")
    on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)

    assert {:error, %NimbleOptions.ValidationError{message: msg}} =
             Firecrawl.parse_file(
               [filename: "doc.pdf", data: "x"],
               typo_option: true
             )

    assert msg =~ "unknown options"
  end

  test "non-bang returns {:error, %Firecrawl.Error{}} for API errors" do
    adapter = fn request ->
      resp = Req.Response.new(
        status: 402,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => false, "error" => "Payment required"})
      )
      {request, resp}
    end

    result =
      Firecrawl.scrape_and_extract_from_url(
        [url: "https://example.com"],
        api_key: "test-key",
        adapter: adapter
      )

    assert {:error, %Firecrawl.Error{status: 402}} = result
  end

  test "bang raises Firecrawl.Error for API errors" do
    adapter = fn request ->
      resp = Req.Response.new(
        status: 401,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => false, "error" => "Unauthorized"})
      )
      {request, resp}
    end

    assert_raise Firecrawl.Error, ~r/Unauthorized/, fn ->
      Firecrawl.scrape_and_extract_from_url!(
        [url: "https://example.com"],
        api_key: "test-key",
        adapter: adapter
      )
    end
  end

  test "non-bang returns {:ok, response} for successful API calls" do
    adapter = fn request ->
      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "data" => %{}})
      )
      {request, resp}
    end

    result =
      Firecrawl.get_credit_usage(
        api_key: "test-key",
        adapter: adapter
      )

    assert {:ok, %Req.Response{status: 200}} = result
  end

  test "scrape maps redact_pii to redactPII" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "data" => %{}})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.scrape_and_extract_from_url(
               [url: "https://example.com", redact_pii: true],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["redactPII"] == true
    refute Map.has_key?(body, "formats")
  end

  test "batch scrape maps redact_pii to redactPII" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "batch-id"})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.scrape_and_extract_from_urls(
               [urls: ["https://example.com"], redact_pii: true],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["redactPII"] == true
    assert body["urls"] == ["https://example.com"]
  end

  test "parse_file sends check_prompt_injection as checkPromptInjection only when set" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "data" => %{}})
      )

      {request, resp}
    end

    parse_options = fn params ->
      assert {:ok, %Req.Response{status: 200}} =
               Firecrawl.parse_file(
                 [filename: "doc.html", data: "<p>hi</p>", content_type: "text/html"],
                 params,
                 api_key: "test-key",
                 adapter: adapter
               )

      assert_receive {:request, request}
      body = request.body |> Enum.to_list() |> IO.iodata_to_binary()
      [_, options] = Regex.run(~r/name="options"\r\n\r\n(.*?)\r\n--/s, body)
      Jason.decode!(options)
    end

    assert parse_options.(check_prompt_injection: true)["checkPromptInjection"] == true
    refute Map.has_key?(parse_options.([]), "checkPromptInjection")
  end

  test "scrape maps check_prompt_injection to checkPromptInjection" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "data" => %{}})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.scrape_and_extract_from_url(
               [url: "https://example.com", check_prompt_injection: true],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["checkPromptInjection"] == true
    refute Map.has_key?(body, "formats")
  end

  test "batch scrape maps check_prompt_injection to checkPromptInjection" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "batch-id"})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.scrape_and_extract_from_urls(
               [urls: ["https://example.com"], check_prompt_injection: true],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["checkPromptInjection"] == true
    assert body["urls"] == ["https://example.com"]
  end

  test "request endpoints map audit_metadata to auditMetadata" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "job", "links" => []})
      )

      {request, resp}
    end

    metadata = [username: "[email protected]"]
    serialized_metadata = %{"username" => "[email protected]"}

    requests = [
      fn ->
        Firecrawl.scrape_and_extract_from_url(
          [url: "https://example.com", audit_metadata: metadata],
          api_key: "test-key",
          adapter: adapter
        )
      end,
      fn ->
        Firecrawl.map_urls(
          [url: "https://example.com", audit_metadata: metadata],
          api_key: "test-key",
          adapter: adapter
        )
      end,
      fn ->
        Firecrawl.start_agent(
          [prompt: "find pricing", audit_metadata: metadata],
          api_key: "test-key",
          adapter: adapter
        )
      end
    ]

    Enum.each(requests, fn make_request ->
      assert {:ok, %Req.Response{status: 200}} = make_request.()
      assert_receive {:request, request}

      body =
        cond do
          is_binary(request.body) -> Jason.decode!(request.body)
          is_map(request.body) -> request.body
          true -> request.options[:json]
        end

      assert body["auditMetadata"] == serialized_metadata
    end)
  end

  test "create_browser_session sends location only when set" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "id" => "session-1"})
      )

      {request, resp}
    end

    sent_body = fn params ->
      assert {:ok, %Req.Response{status: 200}} =
               Firecrawl.create_browser_session(params, api_key: "test-key", adapter: adapter)

      assert_receive {:request, request}

      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end
    end

    assert sent_body.(location: [country: "GB"])["location"] == %{"country" => "GB"}
    refute Map.has_key?(sent_body.(ttl: 60), "location")
  end

  test "create_browser_session rejects a location without a country" do
    assert {:error, %NimbleOptions.ValidationError{}} =
             Firecrawl.create_browser_session([location: []], api_key: "test-key")
  end

  test "audit_metadata rejects unsupported fields" do
    assert_raise NimbleOptions.ValidationError, fn ->
      Firecrawl.scrape_and_extract_from_url!(
        [
          url: "https://example.com",
          audit_metadata: [username: "[email protected]", session: "session-123"]
        ],
        api_key: "test-key"
      )
    end
  end

  test "search maps highlights to highlights" do
    parent = self()

    adapter = fn request ->
      send(parent, {:request, request})

      resp = Req.Response.new(
        status: 200,
        headers: %{"content-type" => ["application/json"]},
        body: Jason.encode!(%{"success" => true, "data" => %{}})
      )

      {request, resp}
    end

    assert {:ok, %Req.Response{status: 200}} =
             Firecrawl.search_and_scrape(
               [query: "firecrawl", highlights: false],
               api_key: "test-key",
               adapter: adapter
             )

    assert_receive {:request, request}

    body =
      cond do
        is_binary(request.body) -> Jason.decode!(request.body)
        is_map(request.body) -> request.body
        true -> request.options[:json]
      end

    assert body["highlights"] == false
  end

  defp parse_formats_adapter(parent, status, body) do
    fn request ->
      send(parent, {:request, request})

      resp =
        Req.Response.new(
          status: status,
          headers: %{"content-type" => ["application/json"]},
          body: Jason.encode!(body)
        )

      {request, resp}
    end
  end

  test "get_parse_formats sends GET /v2/parse/formats and returns typed formats" do
    body = %{
      "success" => true,
      "data" => %{
        "formats" => [
          %{
            "format" => "pdf",
            "kind" => "document",
            "extensions" => [".pdf"],
            "mimeTypes" => ["application/pdf"],
            "available" => true
          },
          %{
            "format" => "png",
            "kind" => "image",
            "extensions" => [".png"],
            "mimeTypes" => ["image/png"],
            "available" => false
          }
        ]
      }
    }

    assert {:ok, [pdf, png]} =
             Firecrawl.get_parse_formats(
               api_key: "test-key",
               adapter: parse_formats_adapter(self(), 200, body)
             )

    assert_receive {:request, request}
    assert request.method == :get
    assert URI.to_string(request.url) == "https://api.firecrawl.dev/v2/parse/formats"
    assert request.headers["authorization"] == ["Bearer test-key"]

    assert pdf == %Firecrawl.ParseFormat{
             format: "pdf",
             kind: :document,
             extensions: [".pdf"],
             mime_types: ["application/pdf"],
             available: true
           }

    assert png == %Firecrawl.ParseFormat{
             format: "png",
             kind: :image,
             extensions: [".png"],
             mime_types: ["image/png"],
             available: false
           }
  end

  test "get_parse_formats keeps unknown kinds as strings and ignores unknown fields" do
    body = %{
      "success" => true,
      "data" => %{
        "formats" => [
          %{
            "format" => "glb",
            "kind" => "model",
            "extensions" => [".glb"],
            "mimeTypes" => ["model/gltf-binary"],
            "available" => true,
            "maxSizeBytes" => 1024
          }
        ]
      }
    }

    formats =
      Firecrawl.get_parse_formats!(
        api_key: "test-key",
        adapter: parse_formats_adapter(self(), 200, body)
      )

    assert [%Firecrawl.ParseFormat{format: "glb", kind: "model", mime_types: ["model/gltf-binary"]}] =
             formats
  end

  test "get_parse_formats returns {:error, %Firecrawl.Error{}} on API errors" do
    adapter =
      parse_formats_adapter(self(), 401, %{"success" => false, "error" => "Unauthorized"})

    assert {:error, %Firecrawl.Error{status: 401}} =
             Firecrawl.get_parse_formats(api_key: "bad-key", adapter: adapter, retry: false)

    assert_raise Firecrawl.Error, ~r/Unauthorized/, fn ->
      Firecrawl.get_parse_formats!(api_key: "bad-key", adapter: adapter, retry: false)
    end
  end

  test "get_parse_formats returns a non-API error for an unexpected success body" do
    adapter = parse_formats_adapter(self(), 200, %{"success" => true, "data" => %{}})

    assert {:error, %RuntimeError{message: msg}} =
             Firecrawl.get_parse_formats(api_key: "test-key", adapter: adapter)

    assert msg =~ "unexpected GET /parse/formats response (HTTP 200)"
  end

  test "get_parse_formats fills missing format and kind with empty strings" do
    body = %{"success" => true, "data" => %{"formats" => [%{"extensions" => [".x"]}]}}

    assert {:ok, [%Firecrawl.ParseFormat{format: "", kind: "", extensions: [".x"], available: false}]} =
             Firecrawl.get_parse_formats(
               api_key: "test-key",
               adapter: parse_formats_adapter(self(), 200, body)
             )
  end

  test "get_parse_formats! raises Firecrawl.Error on server errors" do
    adapter =
      parse_formats_adapter(self(), 500, %{"success" => false, "error" => "Internal error"})

    assert_raise Firecrawl.Error, ~r/HTTP 500/, fn ->
      Firecrawl.get_parse_formats!(api_key: "test-key", adapter: adapter, retry: false)
    end
  end

  defp developer_search_body do
    %{
      "success" => true,
      "partial" => false,
      "results" => [
        %{
          "id" => "issue:square/okhttp#4963",
          "url" => "https://github.com/square/okhttp/issues/4963",
          "title" => "Issues with retry on connection failure",
          "passages" => [%{"text" => "OkHttp retries when a client reuses a closed connection."}],
          "license" => "Apache-2.0"
        },
        %{
          "id" => "doc:okhttp/recipes",
          "url" => "https://square.github.io/okhttp/recipes/",
          "passages" => [],
          "license" => %{"state" => "unknown"}
        }
      ],
      "repos" => [
        %{
          "repo" => "square/okhttp",
          "indexed" => true,
          "types" => %{"issue" => true, "pullRequest" => true, "readme" => false}
        }
      ]
    }
  end

  test "search_developer posts the query, filters and origin and returns a typed response" do
    assert {:ok, %Firecrawl.DeveloperSearch{} = response} =
             Firecrawl.search_developer(
               [
                 query: "http client retry",
                 k: 3,
                 passages: 2,
                 types: ["issue"],
                 repos: ["square/okhttp"],
                 sources: ["okhttp-docs"],
                 language: "Java",
                 topic: ["http"],
                 license: "apache-2.0",
                 min_stars: 100,
                 max_stars: 100_000,
                 archived: false,
                 fork: false,
                 skills: :only
               ],
               api_key: "test-key",
               adapter: parse_formats_adapter(self(), 200, developer_search_body())
             )

    assert_receive {:request, request}
    assert request.method == :post
    assert URI.to_string(request.url) == "https://api.firecrawl.dev/v2/search/developer"
    assert request.headers["authorization"] == ["Bearer test-key"]

    assert Jason.decode!(request.body) == %{
             "query" => "http client retry",
             "k" => 3,
             "passages" => 2,
             "types" => ["issue"],
             "repos" => ["square/okhttp"],
             "sources" => ["okhttp-docs"],
             "language" => "Java",
             "topic" => ["http"],
             "license" => "apache-2.0",
             "min_stars" => 100,
             "max_stars" => 100_000,
             "archived" => false,
             "fork" => false,
             "skills" => "only",
             "origin" => "elixir-sdk@" <> Mix.Project.config()[:version]
           }

    assert %Firecrawl.DeveloperSearch{success: true, partial: false, sources: nil} = response

    assert [
             %Firecrawl.DeveloperSearch.Result{
               id: "issue:square/okhttp#4963",
               title: "Issues with retry on connection failure",
               passages: ["OkHttp retries when a client reuses a closed connection."],
               license: "Apache-2.0"
             },
             %Firecrawl.DeveloperSearch.Result{title: nil, passages: [], license: %{"state" => "unknown"}}
           ] = response.results

    assert [
             %Firecrawl.DeveloperSearch.Repo{
               repo: "square/okhttp",
               indexed: true,
               types: %{issue: true, pull_request: true, readme: false}
             }
           ] = response.repos
  end

  test "search_developer! returns the typed response" do
    assert %Firecrawl.DeveloperSearch{results: [_, _]} =
             Firecrawl.search_developer!(
               [query: "http client retry"],
               api_key: "test-key",
               adapter: parse_formats_adapter(self(), 200, developer_search_body())
             )
  end

  test "search_developer rejects a blank query before sending a request" do
    adapter = parse_formats_adapter(self(), 200, developer_search_body())

    for query <- ["", "   "] do
      assert {:error, %ArgumentError{message: "query cannot be empty"}} =
               Firecrawl.search_developer([query: query], api_key: "test-key", adapter: adapter)

      assert_raise ArgumentError, "query cannot be empty", fn ->
        Firecrawl.search_developer!([query: query], api_key: "test-key", adapter: adapter)
      end
    end

    assert {:error, %NimbleOptions.ValidationError{}} =
             Firecrawl.search_developer([], api_key: "test-key", adapter: adapter)

    refute_received {:request, _}
  end

  test "search_developer returns {:error, %Firecrawl.Error{}} on API errors" do
    adapter = parse_formats_adapter(self(), 401, %{"success" => false, "error" => "Unauthorized"})

    assert {:error, %Firecrawl.Error{status: 401}} =
             Firecrawl.search_developer([query: "retry"], api_key: "bad-key", adapter: adapter, retry: false)
  end

  test "search_developer returns a non-API error for an unexpected success body" do
    adapter = parse_formats_adapter(self(), 200, %{"success" => true})

    assert {:error, %RuntimeError{message: msg}} =
             Firecrawl.search_developer([query: "retry"], api_key: "test-key", adapter: adapter)

    assert msg =~ "unexpected POST /search/developer response (HTTP 200)"
  end

  test "search_developer returns an error tuple for malformed result entries" do
    adapter = parse_formats_adapter(self(), 200, %{"success" => true, "results" => ["not a map"]})

    assert {:error, exception} =
             Firecrawl.search_developer([query: "retry"], api_key: "test-key", adapter: adapter)

    assert is_exception(exception)
  end

  test "all expected API functions are defined with bang variants" do
    functions = Firecrawl.__info__(:functions)

    expected = [
      {:scrape_and_extract_from_url, 0},
      {:scrape_and_extract_from_url, 1},
      {:scrape_and_extract_from_url, 2},
      {:scrape_and_extract_from_url!, 0},
      {:scrape_and_extract_from_url!, 1},
      {:scrape_and_extract_from_url!, 2},
      {:crawl_urls, 0},
      {:crawl_urls!, 0},
      {:get_credit_usage, 0},
      {:get_credit_usage!, 0},
      {:get_queue_status, 0},
      {:get_queue_status!, 0},
      {:cancel_crawl, 1},
      {:cancel_crawl!, 1},
      {:parse_file, 1},
      {:parse_file, 2},
      {:parse_file, 3},
      {:parse_file!, 1},
      {:parse_file!, 2},
      {:parse_file!, 3},
      {:get_agent_trace, 2},
      {:get_agent_trace!, 2},
      {:get_agent_snapshot, 3},
      {:get_agent_snapshot!, 3},
      {:list_agents, 0},
      {:list_agents, 1},
      {:list_agents, 2},
      {:list_agents!, 0},
      {:list_agents!, 1},
      {:list_agents!, 2},
      {:get_parse_formats, 0},
      {:get_parse_formats, 1},
      {:get_parse_formats!, 0},
      {:get_parse_formats!, 1},
      {:search_developer, 0},
      {:search_developer, 1},
      {:search_developer, 2},
      {:search_developer!, 0},
      {:search_developer!, 1},
      {:search_developer!, 2}
    ]

    for {name, arity} <- expected do
      assert {name, arity} in functions,
             "Expected #{name}/#{arity} to be defined in Firecrawl"
    end
  end

  defp monitor_check_adapter(parent, next) do
    fn request ->
      send(parent, {:request, request})

      body =
        case request.url.path do
          "/v2/monitor/mon-1/checks/chk-1" ->
            %{"success" => true, "data" => %{"id" => "chk-1", "pages" => [%{"url" => "https://a.example"}], "next" => next}}

          "/v2/monitor/mon-1/checks/chk-1/pages" ->
            %{
              "success" => true,
              "data" => %{
                "pages" => [%{"url" => "https://b.example"}],
                "next" => "https://evil2.example/v2/monitor/mon-1/checks/chk-1/last?skip=20"
              }
            }

          _ ->
            %{"success" => true, "data" => %{"pages" => [%{"url" => "https://c.example"}]}}
        end

      resp =
        Req.Response.new(
          status: 200,
          headers: %{"content-type" => ["application/json"]},
          body: Jason.encode!(body)
        )

      {request, resp}
    end
  end

  defp assert_monitor_next_pinned(get_check, next, expected_url) do
    adapter = monitor_check_adapter(self(), next)
    response = get_check.(adapter)

    assert response.body["data"]["pages"] == [
             %{"url" => "https://a.example"},
             %{"url" => "https://b.example"},
             %{"url" => "https://c.example"}
           ]

    assert_receive {:request, first}
    assert URI.to_string(first.url) == "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1"
    assert_receive {:request, followed}
    assert URI.to_string(followed.url) == expected_url
    assert followed.headers["authorization"] == ["Bearer test-key"]
    assert_receive {:request, last}
    assert URI.to_string(last.url) == "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/last?skip=20"
    assert last.headers["authorization"] == ["Bearer test-key"]
    refute_receive {:request, _}
  end

  @monitor_next_cases [
    {"same origin", "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=1",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=1"},
    {"cross host", "https://evil.example/v2/monitor/mon-1/checks/chk-1/pages?skip=10",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"},
    {"protocol-relative", "//evil.example/v2/monitor/mon-1/checks/chk-1/pages?skip=10",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"},
    {"different port", "https://api.firecrawl.dev:8443/v2/monitor/mon-1/checks/chk-1/pages?skip=10",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"},
    {"relative", "/monitor/mon-1/checks/chk-1/pages?skip=10",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"},
    {"userinfo", "https://user:[email protected]/v2/monitor/mon-1/checks/chk-1/pages?skip=10",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"},
    {"different scheme", "http://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10#frag",
     "https://api.firecrawl.dev/v2/monitor/mon-1/checks/chk-1/pages?skip=10"}
  ]

  for {name, next, expected} <- @monitor_next_cases do
    test "get_monitor_check pins #{name} next URL to the api_url origin" do
      assert_monitor_next_pinned(
        fn adapter ->
          assert {:ok, response} =
                   Firecrawl.get_monitor_check("mon-1", "chk-1", [], api_key: "test-key", adapter: adapter)

          response
        end,
        unquote(next),
        unquote(expected)
      )
    end

    test "get_monitor_check! pins #{name} next URL to the api_url origin" do
      assert_monitor_next_pinned(
        fn adapter ->
          Firecrawl.get_monitor_check!("mon-1", "chk-1", [], api_key: "test-key", adapter: adapter)
        end,
        unquote(next),
        unquote(expected)
      )
    end
  end

  test "get_monitor_check pins next URLs to a self-hosted base_url origin" do
    adapter = monitor_check_adapter(self(), "https://evil.example/v2/monitor/mon-1/checks/chk-1/pages?skip=10")

    assert {:ok, _} =
             Firecrawl.get_monitor_check("mon-1", "chk-1", [],
               api_key: "test-key",
               base_url: "http://localhost:3002/v2",
               adapter: adapter
             )

    assert_receive {:request, first}
    assert URI.to_string(first.url) == "http://localhost:3002/v2/monitor/mon-1/checks/chk-1"
    assert_receive {:request, followed}
    assert URI.to_string(followed.url) == "http://localhost:3002/v2/monitor/mon-1/checks/chk-1/pages?skip=10"
    assert followed.headers["authorization"] == ["Bearer test-key"]
  end
end