Search documentation of ash

# View Source Ash.Generator (ash v3.4.30)

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:

    # All generated posts will have text as `"text"`. Equivalent to providing `StreamData.constant("text")`.
    Ash.Generator.seed_input(Post, %{text: "text"})

# Summary

## Functions

action_input(resource_or_record, action, generators \\ %{})

Generate input meant to be passed into a resource action.

changeset(resource_or_record, action, generators \\ %{}, changeset_options \\ [])

Creates the input for the provided action with `action_input/3`, and creates a changeset for that action with that input.

initialize_sequence(identifier)

Starts and links an agent for a sequence, or returns the existing agent pid if it already exists.

many_changesets(resource_or_record, action, n, generators \\ %{}, changeset_options \\ [])

Generate n changesets and return them as a list.

many_queries(resource, action, n, generators \\ %{}, changeset_options \\ [])

Generate n queries and return them as a list.

mixed_map(map, keys)

Creates a generator map where the keys are required except the list provided

query(resource, action, generators \\ %{}, changeset_options \\ [])

Creates the input for the provided action with `action_input/3`, and creates a query for that action with that input.

seed!(resource, generators \\ %{})

Gets input using `seed_input/2` and passes it to `Ash.Seed.seed!/2`, returning the result

seed_input(resource, generators \\ %{})

Generate input meant to be passed into `Ash.Seed.seed!/2`.

seed_many!(resource, n, generators \\ %{})

Generates an input `n` times, and passes them all to seed, returning the list of seeded items.

sequence(identifier, generator, sequencer \\ fn i -> (i || -1) + 1 end)

Generate globally unique values.

stop_sequence(identifier)

Stops the agent for a sequence.

# Functions

Link to this function

# action_input(resource_or_record, action, generators \\ %{})

View Source

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.

Link to this function

# changeset(resource_or_record, action, generators \\ %{}, changeset_options \\ [])

View Source

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.

Link to this function

# initialize_sequence(identifier)

View Source

    @spec initialize_sequence(atom()) :: pid()

Starts and links an agent for a sequence, or returns the existing agent pid if it already exists.

See `sequence/3` for more.

Link to this function

# many_changesets(resource_or_record, action, n, generators \\ %{}, changeset_options \\ [])

View Source

Generate n changesets and return them as a list.

Link to this function

# many_queries(resource, action, n, generators \\ %{}, changeset_options \\ [])

View Source

Generate n queries and return them as a list.

Link to this function

# mixed_map(map, keys)

View Source

Creates a generator map where the keys are required except the list provided

Link to this function

# query(resource, action, generators \\ %{}, changeset_options \\ [])

View Source

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.

Link to this function

# seed!(resource, generators \\ %{})

View Source

Gets input using `seed_input/2` and passes it to `Ash.Seed.seed!/2`, returning the result

Link to this function

# seed_input(resource, generators \\ %{})

View Source

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")})`

Link to this function

# seed_many!(resource, n, generators \\ %{})

View Source

Generates an input `n` times, and passes them all to seed, returning the list of seeded items.

Link to this function

# sequence(identifier, generator, sequencer \\ fn i -> (i || -1) + 1 end)

View Source

    @spec sequence(pid() | atom(), (iterator | nil -> value), (iterator | nil -> iterator)) ::
      StreamData.t(value)
    when iterator: term(), value: term()

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"]

Link to this function

# stop_sequence(identifier)

View Source

Stops the agent for a sequence.

See `sequence/3` for more.