|
| 1 | +defmodule Cache.CaseTemplate do |
| 2 | + @moduledoc """ |
| 3 | + A reusable ExUnit case template for applications using `elixir_cache`. |
| 4 | +
|
| 5 | + Creates a `CacheCase` module that automatically starts sandboxed caches in |
| 6 | + `setup` for every test that uses it. |
| 7 | +
|
| 8 | + ## Creating a CacheCase module |
| 9 | +
|
| 10 | + Pass an explicit list of cache modules: |
| 11 | +
|
| 12 | + ```elixir |
| 13 | + defmodule MyApp.CacheCase do |
| 14 | + use Cache.CaseTemplate, default_caches: [MyApp.UserCache, MyApp.SessionCache] |
| 15 | + end |
| 16 | + ``` |
| 17 | +
|
| 18 | + Or discover caches at runtime by inspecting a running supervisor: |
| 19 | +
|
| 20 | + ```elixir |
| 21 | + defmodule MyApp.CacheCase do |
| 22 | + use Cache.CacheTemplate, supervisors: [MyApp.Supervisor] |
| 23 | + end |
| 24 | + ``` |
| 25 | +
|
| 26 | + ## Using the CacheCase in a test file |
| 27 | +
|
| 28 | + ```elixir |
| 29 | + defmodule MyApp.SomeTest do |
| 30 | + use ExUnit.Case, async: true |
| 31 | + use MyApp.CacheCase |
| 32 | +
|
| 33 | + # or with additional caches just for this file: |
| 34 | + use MyApp.CacheCase, caches: [MyApp.ExtraCache] |
| 35 | + end |
| 36 | + ``` |
| 37 | +
|
| 38 | + ## Options for `use Cache.CaseTemplate` |
| 39 | +
|
| 40 | + - `:default_caches` — list of cache modules to start for every test |
| 41 | + - `:supervisors` — list of supervisor atoms; their `Cache` children are discovered at runtime |
| 42 | +
|
| 43 | + ## Options for `use MyApp.CacheCase` |
| 44 | +
|
| 45 | + - `:caches` — additional cache modules for this test file only |
| 46 | + - `:sleep` — milliseconds to sleep after starting caches (default: `10`) |
| 47 | + """ |
| 48 | + |
| 49 | + defmacro __using__(template_opts) do |
| 50 | + default_caches = Keyword.get(template_opts, :default_caches, []) |
| 51 | + supervisors = Keyword.get(template_opts, :supervisors, []) |
| 52 | + |
| 53 | + if Keyword.has_key?(template_opts, :caches) do |
| 54 | + raise ":caches is not valid here, use :default_caches instead" |
| 55 | + end |
| 56 | + |
| 57 | + quote bind_quoted: [default_caches: default_caches, supervisors: supervisors] do |
| 58 | + defmacro __using__(case_opts) do |
| 59 | + sleep_time = Keyword.get(case_opts, :sleep, 10) |
| 60 | + case_caches = Keyword.get(case_opts, :caches, []) |
| 61 | + template_default_caches = unquote(default_caches) |
| 62 | + template_supervisors = unquote(supervisors) |
| 63 | + |
| 64 | + quote do |
| 65 | + setup do |
| 66 | + inferred = Cache.CaseTemplate.inferred_caches(unquote(template_supervisors)) |
| 67 | + |
| 68 | + (unquote(template_default_caches) ++ inferred ++ unquote(case_caches)) |
| 69 | + |> Cache.CaseTemplate.validate_uniq!() |
| 70 | + |> Cache.SandboxRegistry.start() |
| 71 | + |
| 72 | + Process.sleep(unquote(sleep_time)) |
| 73 | + end |
| 74 | + end |
| 75 | + end |
| 76 | + end |
| 77 | + end |
| 78 | + |
| 79 | + @doc """ |
| 80 | + Inspects a running supervisor's children to find cache modules started under a |
| 81 | + `Cache` supervisor child. |
| 82 | +
|
| 83 | + Raises if the given supervisor is not running or has no `Cache` child. |
| 84 | + """ |
| 85 | + @spec inferred_caches([atom] | atom) :: [module] |
| 86 | + def inferred_caches([]), do: [] |
| 87 | + |
| 88 | + def inferred_caches(supervisors) when is_list(supervisors) do |
| 89 | + Enum.flat_map(supervisors, &inferred_caches/1) |
| 90 | + end |
| 91 | + |
| 92 | + def inferred_caches(supervisor) when is_atom(supervisor) do |
| 93 | + case Process.whereis(supervisor) do |
| 94 | + nil -> |
| 95 | + raise """ |
| 96 | + Supervisor #{inspect(supervisor)} is not started. |
| 97 | +
|
| 98 | + It is either misspelled or not started as part of your application's supervision tree. |
| 99 | + Verify that the supervisor exists and that the app starting it is a dependency of |
| 100 | + the current app. |
| 101 | + """ |
| 102 | + |
| 103 | + sup_pid -> |
| 104 | + case find_cache_supervisor(sup_pid) do |
| 105 | + nil -> |
| 106 | + raise """ |
| 107 | + Supervisor #{inspect(supervisor)} has no Cache child supervisor. |
| 108 | +
|
| 109 | + Add a Cache supervisor under #{inspect(supervisor)} in your Application, for example: |
| 110 | +
|
| 111 | + children = [ |
| 112 | + {Cache, [MyApp.UserCache, MyApp.SessionCache]} |
| 113 | + ] |
| 114 | + """ |
| 115 | + |
| 116 | + cache_pid -> |
| 117 | + cache_pid |
| 118 | + |> Supervisor.which_children() |
| 119 | + |> Enum.filter(fn {_id, _pid, _type, modules} -> |
| 120 | + is_list(modules) and |
| 121 | + Enum.any?(modules, &function_exported?(&1, :cache_name, 0)) |
| 122 | + end) |
| 123 | + |> Enum.flat_map(fn {_id, _pid, _type, modules} -> |
| 124 | + Enum.filter(modules, &function_exported?(&1, :cache_name, 0)) |
| 125 | + end) |
| 126 | + end |
| 127 | + end |
| 128 | + end |
| 129 | + |
| 130 | + @doc """ |
| 131 | + Validates that the list of cache modules contains no duplicates. |
| 132 | +
|
| 133 | + Raises with a descriptive message listing the duplicates if any are found. |
| 134 | + """ |
| 135 | + @spec validate_uniq!([module]) :: [module] |
| 136 | + def validate_uniq!(caches) do |
| 137 | + unique = Enum.uniq(caches) |
| 138 | + |
| 139 | + if unique === caches do |
| 140 | + caches |
| 141 | + else |
| 142 | + duplicates = caches -- unique |
| 143 | + |
| 144 | + raise """ |
| 145 | + The following caches have been specified more than once: |
| 146 | + #{inspect(duplicates)} |
| 147 | +
|
| 148 | + Please compare your test file and CacheCase module. |
| 149 | + """ |
| 150 | + end |
| 151 | + end |
| 152 | + |
| 153 | + defp find_cache_supervisor(sup_pid) do |
| 154 | + sup_pid |
| 155 | + |> Supervisor.which_children() |
| 156 | + |> Enum.find_value(fn {_id, pid, _type, modules} -> |
| 157 | + if is_list(modules) and Cache in modules, do: pid |
| 158 | + end) |
| 159 | + end |
| 160 | +end |
0 commit comments