improvement: make testing helpers public and document them

improvement: deprecate the DSL router configuration

Author: zachdaniel

lib/ash_json_api/domain/domain.ex

@@ -119,7 +119,9 @@ defmodule AshJsonApi.Domain do
     ],
     modules: [:router],
     deprecations: [
-      serve_schema?: "Use the `json_schema` option to `use AshJsonApi.Router` instead."
+      serve_schema?: "Use the `json_schema` option to `use AshJsonApi.Router` instead.",
+      router:
+        "Specify the router option in your calls to test helpers, or configure it via `config :your_app, YourDomain, test_router: YourRouter` in config/test.exs."
     ],
     schema: [
       router: [

lib/ash_json_api/domain/info.ex

@@ -35,7 +35,8 @@ defmodule AshJsonApi.Domain.Info do
   end
 
   def router(domain) do
-    Extension.get_opt(domain, [:json_api], :router, nil, false)
+    Extension.get_opt(domain, [:json_api], :test_router, nil, true) ||
+      Extension.get_opt(domain, [:json_api], :router, nil, false)
   end
 
   def include_nil_values?(domain) do

lib/ash_json_api/test/test.ex

@@ -1,23 +1,52 @@
 defmodule AshJsonApi.Test do
-  @moduledoc false
+  @moduledoc """
+  Utilities for testing AshJsonApi.
+
+  ## Making Requests
+
+  The request testing functions get/patch/post/delete all support the following options
+
+  - `:status`: Asserts that the response has the provided status after making the request
+  - `:router`: The corresponding JsonApiRouter to go through. Can be set statically in config, see below for more.
+  - `:actor`: Sets the provided actor as the actor for the request
+  - `:tenant`: Sets the provided tenant as the tenant for the request
+
+  A standard test would look like this:
+
+  ```elixir
+  test "can list posts", %{current_user: current_user} do
+    Domain
+    # GET /posts
+    # assert resp.status == 200
+    |> get("/posts", status: 200, actor: current_user, router: MyAppWeb.JsonApiRouter)
+    # pattern match on the data key of the response
+    |> assert_data_matches([
+      %{
+        "attributes" => %{
+          "name" => "foo"
+        }
+      }
+    ])
+  end
+  ```
+  """
   use Plug.Test
 
   require ExUnit.Assertions
   import ExUnit.Assertions
 
-  # This probably won't work for users of ashjsonapi
-  @schema_file "lib/ash_json_api/test/response_schema"
-  @external_resource @schema_file
-
+  @doc """
+  Sends a GET request to the given path. See the module docs for more.
+  """
   def get(domain, path, opts \\ []) do
     result =
       :get
       |> conn(path)
+      |> set_req_headers(opts)
+      |> set_context_opts(opts)
       |> maybe_set_endpoint(opts)
       |> set_accept_request_header(opts)
-      |> AshJsonApi.Domain.Info.router(domain).call(
-        AshJsonApi.Domain.Info.router(domain).init([])
-      )
+      |> call_router(domain, opts)
 
     assert result.state == :sent
 
@@ -50,15 +79,18 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Sends a POST request to the given path. See the module docs for more.
+  """
   def post(domain, path, body, opts \\ []) do
     result =
       :post
       |> conn(path, Jason.encode!(body))
+      |> set_req_headers(opts)
+      |> set_context_opts(opts)
       |> set_content_type_request_header(opts)
       |> set_accept_request_header(opts)
-      |> AshJsonApi.Domain.Info.router(domain).call(
-        AshJsonApi.Domain.Info.router(domain).init([])
-      )
+      |> call_router(domain, opts)
 
     assert result.state == :sent
 
@@ -95,22 +127,25 @@ defmodule AshJsonApi.Test do
   end
 
   if Code.ensure_loaded?(Multipart) do
+    @doc """
+    Sends a multipart POST request to the given path. See the module docs for more.
+    """
     def multipart_post(domain, path, body, opts \\ []) do
       parser_opts =
         Plug.Parsers.init(parsers: [AshJsonApi.Plug.Parser], pass: ["*/*"], json_decoder: Jason)
 
       result =
         :post
         |> conn(path, Multipart.body_binary(body))
+        |> set_req_headers(opts)
+        |> set_context_opts(opts)
         |> put_req_header(
           "content-type",
           Multipart.content_type(body, "multipart/x.ash+form-data")
         )
         |> set_accept_request_header(opts)
         |> Plug.Parsers.call(parser_opts)
-        |> AshJsonApi.Domain.Info.router(domain).call(
-          AshJsonApi.Domain.Info.router(domain).init([])
-        )
+        |> call_router(domain, opts)
 
       assert result.state == :sent
 
@@ -157,15 +192,18 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Sends a PATCH request to the given path. See the module docs for more.
+  """
   def patch(domain, path, body, opts \\ []) do
     result =
       :patch
       |> conn(path, Jason.encode!(body))
+      |> set_req_headers(opts)
+      |> set_context_opts(opts)
       |> set_content_type_request_header(opts)
       |> set_accept_request_header(opts)
-      |> AshJsonApi.Domain.Info.router(domain).call(
-        AshJsonApi.Domain.Info.router(domain).init([])
-      )
+      |> call_router(domain, opts)
 
     assert result.state == :sent
 
@@ -201,14 +239,17 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Sends a DELETE request to the given path. See the module docs for more.
+  """
   def delete(domain, path, opts \\ []) do
     result =
       :delete
       |> conn(path)
+      |> set_req_headers(opts)
+      |> set_context_opts(opts)
       |> set_accept_request_header(opts)
-      |> AshJsonApi.Domain.Info.router(domain).call(
-        AshJsonApi.Domain.Info.router(domain).init([])
-      )
+      |> call_router(domain, opts)
 
     assert result.state == :sent
 
@@ -241,6 +282,9 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Assert that the response body's `"data"` equals an exact value
+  """
   defmacro assert_data_equals(conn, expected_data) do
     quote do
       conn = unquote(conn)
@@ -251,6 +295,9 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Assert that the response body's `"data"` matches a pattern
+  """
   defmacro assert_data_matches(conn, data_pattern) do
     quote do
       conn = unquote(conn)
@@ -260,6 +307,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_meta_equals(conn, expected_meta) do
     quote bind_quoted: [conn: conn, expected_meta: expected_meta] do
       assert %{"meta" => ^expected_meta} = conn.resp_body
@@ -268,11 +316,13 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   def assert_response_header_equals(conn, header, value) do
     assert get_resp_header(conn, header) == [value]
     conn
   end
 
+  @doc false
   defmacro assert_attribute_equals(conn, attribute, expected_value) do
     quote bind_quoted: [attribute: attribute, expected_value: expected_value, conn: conn] do
       assert %{"data" => %{"attributes" => %{^attribute => ^expected_value}}} = conn.resp_body
@@ -281,6 +331,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_id_equals(conn, expected_value) do
     quote bind_quoted: [expected_value: expected_value, conn: conn] do
       assert %{"data" => %{"id" => ^expected_value}} = conn.resp_body
@@ -289,15 +340,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
-  @doc """
-  Validate the response contains a Resource Object as per 5.2 Specification 1.0
-
-  A resource object MUST contain at least the following top-level members:
-  - id
-  - type
-
-  see: https://jsonapi.org/format/1.0/#document-resource-objects
-  """
+  @doc false
   defmacro assert_valid_resource_object(conn, expected_type, expected_id) do
     quote bind_quoted: [conn: conn, expected_type: expected_type, expected_id: expected_id] do
       assert %{
@@ -311,6 +354,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_valid_resource_objects(conn, expected_type, expected_ids) do
     quote bind_quoted: [conn: conn, expected_type: expected_type, expected_ids: expected_ids] do
       assert %{
@@ -329,6 +373,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_invalid_resource_objects(conn, expected_type, expected_ids) do
     quote bind_quoted: [conn: conn, expected_type: expected_type, expected_ids: expected_ids] do
       assert %{
@@ -347,6 +392,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_attribute_missing(conn, attribute) do
     quote bind_quoted: [conn: conn, attribute: attribute] do
       assert %{"data" => %{"attributes" => attributes}} = conn.resp_body
@@ -357,6 +403,22 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Asserts that an error is in the response where each key present in the provided map
+  has the same value in the error.
+
+  ## Example
+   
+  ```elixr
+  Domain
+  |> delete("/posts/1", status: 404)
+  |> assert_has_error(%{
+    "code" => "not_found",
+    "detail" => "No post record found with `id: 1`",
+    "title" => "Entity Not Found"
+  })
+  ```
+  """
   defmacro assert_has_error(conn, fields) do
     quote do
       assert %{"errors" => [_ | _] = errors} = unquote(conn).resp_body
@@ -371,6 +433,21 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Assert that the given function returns true for at least one included record
+
+  ## Example
+
+  Domain
+  |> get("/posts/\#{post.id}/?include=author", status: 200)
+  |> assert_has_matching_include(fn
+    %{"type" => "author", "id" => ^author_id} ->
+      true
+
+    _ ->
+      false
+  end)
+  """
   defmacro assert_has_matching_include(conn, function) do
     quote do
       assert %{"included" => included} = unquote(conn).resp_body
@@ -384,6 +461,21 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc """
+  Refute that the given function returns true for at least one included record
+
+  ## Example
+
+  Domain
+  |> get("/posts/\#{post.id}/?include=author", status: 200)
+  |> refute_has_matching_include(fn
+    %{"type" => "author", "id" => ^author_id} ->
+      true
+
+    _ ->
+      false
+  end)
+  """
   defmacro refute_has_matching_include(conn, function) do
     quote do
       with %{"included" => included} when is_list(included) <- unquote(conn).resp_body do
@@ -396,6 +488,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   defmacro assert_equal_links(conn, expected_links) do
     quote bind_quoted: [expected_links: expected_links, conn: conn] do
       %{"links" => resp_links} = conn.resp_body
@@ -411,6 +504,7 @@ defmodule AshJsonApi.Test do
     end
   end
 
+  @doc false
   def uri_with_query(nil), do: nil
 
   def uri_with_query(value) do
@@ -456,4 +550,24 @@ defmodule AshJsonApi.Test do
       conn
     end
   end
+
+  defp set_context_opts(conn, opts) do
+    conn
+    |> Ash.PlugHelpers.set_actor(opts[:actor])
+    |> Ash.PlugHelpers.set_tenant(opts[:tenant])
+  end
+
+  defp set_req_headers(conn, opts) do
+    opts[:headers]
+    |> Kernel.||([])
+    |> Enum.reduce(conn, fn {header, value}, conn ->
+      Plug.Conn.put_req_header(conn, to_string(header), to_string(value))
+    end)
+  end
+
+  defp call_router(conn, domain, opts) do
+    router = opts[:router] || AshJsonApi.Domain.Info.router(domain)
+
+    router.call(conn, router.init([]))
+  end
 end

mix.exs

@@ -92,7 +92,8 @@ defmodule AshJsonApi.MixProject do
           AshJsonApi.Domain
         ],
         Utilities: [
-          AshJsonApi.OpenApi
+          AshJsonApi.OpenApi,
+          AshJsonApi.Test
         ],
         Introspection: [
           AshJsonApi.Resource.Info,