defmodule Ash.Generator do
@moduledoc """
Tools for generating input to Ash resource actions, as well as for seeds.
These tools are young, and various factors are not taken into account. For example,
validations and identities are not automatically considered.
If you want to use this with stream data testing, you will likely want to get familiar with `StreamData`.
Many functions in this module support overrides, which allow passing down either constant values
or your own generators.
For example:
```elixir
# All generated posts will have text as `"text"`. Equivalent to providing `StreamData.constant("text")`.
Ash.Generator.seed_input(Post, %{text: "text"})
```
"""
@dialyzer {:nowarn_function,
seed_input: 2,
seed_input: 1,
seed!: 1,
seed!: 2,
seed_many!: 2,
seed_many!: 3,
action_input: 2,
action_input: 3,
changeset: 2,
changeset: 3,
changeset: 4,
do_mixed_map: 1,
query: 2,
query: 3,
query: 4,
generate_attributes: 4,
mixed_map: 2,
many_changesets: 3,
many_changesets: 4,
many_changesets: 5,
many_queries: 3,
many_queries: 4,
many_queries: 5,
do_changeset_or_query: 5}
@doc "Creates a generator map where the keys are required except the list provided"
def mixed_map(map, keys) do
map = to_generators(map)
{optional, required} = Map.split(map, keys)
do_mixed_map({StreamData.fixed_map(required), StreamData.optional_map(optional)})
end
@doc """
Generate input meant to be passed into `Ash.Seed.seed!/2`.
A map of custom `StreamData` generators can be provided to add to or overwrite the generated input,
for example: `Ash.Generator.for_seed(Post, %{text: StreamData.constant("Post")})`
"""
def seed_input(resource, generators \\ %{}) do
relationships = Ash.Resource.Info.relationships(resource)
resource
|> Ash.Resource.Info.attributes()
|> Enum.reject(fn attribute ->
Enum.any?(relationships, &(&1.source_attribute == attribute.name))
end)
|> generate_attributes(generators, true, :create)
end
@doc """
Generate globally unique values.
This is useful for generating values that are unique across all resources, such as email addresses,
or for generating values that are unique across a single resource, such as identifiers. The values will be unique
for anything using the same sequence name.
The name of the identifier will be used as the name of the agent process, so use a unique name not in use anywhere else.
The lifecycle of this generator is tied to the process that initially starts it. In general,
that will be the test. In the rare case where you are running async processes that need to share a sequence
that is not created in the test process, you can initialize a sequence in the test using `initialize_sequence/1`.
Example:
Ash.Generator.sequence(:unique_email, fn i -> "user\#\{i\}@example.com" end) |> Enum.take(3)
iex> ["user0@example.com", "user1@example.com", "user2@example.com"]
## Using a different sequencer
By default we use an incrementing integer starting at 0. However, if you want to use something else, you can provide
your own sequencer. The initial value will be `nil`, which you can use to detect that you are the start of the sequence.
Example:
Ash.Generator.sequence(:unique_email, fn i -> "user\#\{i\}@example.com" end, fn num -> (num || 1) - 1 end) |> Enum.take(3)
iex> ["user0@example.com", "user-1@example.com", "user-2@example.com"]
"""
@spec sequence(pid | atom, (iterator | nil -> value), (iterator | nil -> iterator)) ::
StreamData.t(value)
when iterator: term, value: term
def sequence(identifier, generator, sequencer \\ fn i -> (i || -1) + 1 end) do
pid =
if is_pid(identifier) do
identifier
else
initialize_sequence(identifier)
end
StreamData.repeatedly(fn ->
Agent.get_and_update(pid, fn state ->
next_in_sequence = sequencer.(state)
value = generator.(next_in_sequence)
{value, next_in_sequence}
end)
end)
end
@doc """
Starts and links an agent for a sequence, or returns the existing agent pid if it already exists.
See `sequence/3` for more.
"""
@spec initialize_sequence(atom) :: pid
def initialize_sequence(identifier) do
case Agent.start_link(fn -> nil end, name: identifier) do
{:ok, pid} -> pid
{:error, {:already_started, pid}} -> pid
end
end
@doc """
Stops the agent for a sequence.
See `sequence/3` for more.
"""
def stop_sequence(identifier) do
Agent.stop(identifier)
:ok
end
@doc """
Gets input using `seed_input/2` and passes it to `Ash.Seed.seed!/2`, returning the result
"""
def seed!(resource, generators \\ %{}) do
input =
seed_input(resource, generators)
|> Enum.at(0)
Ash.Seed.seed!(input)
end
@doc """
Generates an input `n` times, and passes them all to seed, returning the list of seeded items.
"""
def seed_many!(resource, n, generators \\ %{}) do
seed_input(resource, generators)
|> Enum.take(n)
|> Enum.map(&Ash.Seed.seed!(resource, &1))
end
@doc """
Generate input meant to be passed into a resource action.
Currently input for arguments that are passed to a `manage_relationship` are excluded, and you will
have to generate them yourself by passing your own generators/values down See the module documentation for more.
This is meant to be used in property testing. If you want to generate a finite list of
"""
def action_input(resource_or_record, action, generators \\ %{}) do
resource =
case resource_or_record do
%resource{} -> resource
resource -> resource
end
action = Ash.Resource.Info.action(resource, action)
arguments = Enum.reject(action.arguments, &find_manage_change(&1, action))
resource
|> Ash.Resource.Info.public_attributes()
|> Enum.filter(&(&1.name in action.accept))
|> set_allow_nil(action)
|> Enum.concat(arguments)
|> generate_attributes(generators, false, action.type)
end
@doc """
Creates the input for the provided action with `action_input/3`, and creates a changeset for that action with that input.
See `action_input/3` and the module documentation for more.
"""
def changeset(resource_or_record, action, generators \\ %{}, changeset_options \\ []) do
resource =
case resource_or_record do
%resource{} -> resource
resource -> resource
end
input =
action_input(resource_or_record, action, generators)
|> Enum.at(0)
do_changeset_or_query(resource, resource_or_record, action, input, changeset_options)
end
@doc """
Generate n changesets and return them as a list.
"""
def many_changesets(resource_or_record, action, n, generators \\ %{}, changeset_options \\ []) do
resource =
case resource_or_record do
%resource{} -> resource
resource -> resource
end
action_input(resource_or_record, action, generators)
|> Enum.take(n)
|> Enum.map(fn input ->
do_changeset_or_query(resource, resource_or_record, action, input, changeset_options)
end)
end
@doc """
Creates the input for the provided action with `action_input/3`, and creates a query for that action with that input.
See `action_input/3` and the module documentation for more.
"""
def query(resource, action, generators \\ %{}, changeset_options \\ []) do
changeset(resource, action, generators, changeset_options)
end
@doc """
Generate n queries and return them as a list.
"""
def many_queries(resource, action, n, generators \\ %{}, changeset_options \\ []) do
many_changesets(resource, action, n, generators, changeset_options)
end
defp do_changeset_or_query(resource, resource_or_record, action, input, changeset_options) do
case Ash.Resource.Info.action(resource, action).type do
:read ->
Ash.Query.for_read(resource, action, input, changeset_options)
:create ->
Ash.Changeset.for_create(resource, action, input, changeset_options)
:update ->
Ash.Changeset.for_update(resource_or_record, action, input, changeset_options)
:destroy ->
Ash.Changeset.for_destroy(resource_or_record, action, input, changeset_options)
end
end
defp generate_attributes(attributes, generators, keep_nil?, action_type) do
attributes
|> Enum.reduce({%{}, %{}}, fn attribute, {required, optional} ->
default =
cond do
action_type == :create ->
attribute.default
action_type in [:update, :destroy] ->
attribute.update_default
true ->
nil
end
# only create a value for attributes that didn't get a dedicated generator
if attribute.name in Map.keys(generators) do
{required, optional}
else
if attribute.allow_nil? || !is_nil(default) do
options = [attribute_generator(attribute)]
options =
if attribute.allow_nil? do
if keep_nil? do
[StreamData.constant(:__keep_nil__) | options]
else
[StreamData.constant(nil) | options]
end
else
options
end
options =
if attribute.allow_nil? && is_nil(default) do
[StreamData.constant(nil) | options]
else
options
end
{required,
Map.put(
optional,
attribute.name,
StreamData.one_of(options)
)}
else
{Map.put(required, attribute.name, attribute_generator(attribute)), optional}
end
end
end)
|> then(fn {required, optional} ->
{Map.merge(required, to_generators(generators)), Map.drop(optional, Map.keys(generators))}
end)
|> do_mixed_map()
end
defp attribute_generator(attribute) do
Ash.Type.generator(attribute.type, attribute.constraints)
end
defp do_mixed_map({required, optional}) do
{StreamData.fixed_map(required), StreamData.optional_map(optional)}
|> StreamData.map(fn {required, optional} ->
Map.merge(required, optional)
end)
end
defp to_generators(generators) do
Map.new(generators, fn {key, value} ->
case value do
%StreamData{} ->
{key, value}
value ->
{key, StreamData.constant(value)}
end
end)
end
defp set_allow_nil(
attributes,
%{
allow_nil_input: allow_nil_input,
require_attributes: require_attributes
}
) do
Enum.map(attributes, fn attribute ->
cond do
attribute.name in allow_nil_input ->
%{attribute | allow_nil?: true}
attribute.name in require_attributes ->
%{attribute | allow_nil?: false}
true ->
attribute
end
end)
end
defp set_allow_nil(attributes, _), do: attributes
defp find_manage_change(argument, action) do
Enum.find_value(Map.get(action, :changes, []), fn
%{change: {Ash.Resource.Change.ManageRelationship, opts}} ->
if opts[:argument] == argument.name do
opts
end
_ ->
nil
end)
end
end
