AshScenario (ash_scenario v0.6.0)

View Source

Test data generation for your Ash application.

AshScenario provides a DSL for defining named prototypes in your Ash resources, allowing you to create test data with automatic dependency resolution.

Usage

Add the DSL to your Ash resources:

defmodule MyApp.Post do
  use Ash.Resource, extensions: [AshScenario.Dsl]

  prototypes do
    prototype :example_post,
      title: "My Example Post",
      content: "This is example content",
      blog_id: :example_blog  # Reference to prototype in Blog resource
  end
end

defmodule MyApp.Blog do
  use Ash.Resource, extensions: [AshScenario.Dsl]

  prototypes do
    prototype :example_blog,
      name: "My Example Blog"
  end
end

Then run scenarios:

# Run prototypes with database persistence (default)
AshScenario.run([
  {MyApp.Blog, :example_blog},
  {MyApp.Post, :example_post}
])

# Run prototypes as in-memory structs
AshScenario.run([
  {MyApp.Post, :example_post}
], strategy: :struct)

# Run all prototypes for a resource
AshScenario.run_all(MyApp.Post)

Summary

Functions

__using__(opts)

Use this in your Ash resources to enable prototype support.

clear_prototypes()

Clear all registered prototypes (useful for testing).

dsl_patches()

Returns any DSL patches provided by AshScenario. Currently returns an empty list as no patches are defined.

has_prototypes?(resource)

See AshScenario.Info.has_prototypes?/1.

prototype(resource, name)

See AshScenario.Info.prototype/2.

prototype_names(resource)

See AshScenario.Info.prototype_names/1.

prototypes(resource)

Get prototype information from a resource module.

register_prototypes(resource_module)

Register prototypes from a resource module. This is typically called automatically when the resource is compiled.

run(prototype_refs, opts \\ [])

Execute prototypes with the specified strategy.

run_all(resource_module, opts \\ [])

Execute all prototypes defined for a resource module.

run_scenario(test_module, scenario_name, opts \\ [])

Run a named scenario from a test module.

sections()

Returns the DSL sections provided by AshScenario. Delegates to AshScenario.Dsl for the actual sections.

start_registry(opts \\ [])

Start the scenario registry (should be called in your application supervision tree).

Functions

__using__(opts)

(macro)

Use this in your Ash resources to enable prototype support.

Example

defmodule MyApp.Post do
  use Ash.Resource, extensions: [AshScenario.Dsl]
  # ... your resource definition
end

clear_prototypes()

Clear all registered prototypes (useful for testing).

dsl_patches()

Returns any DSL patches provided by AshScenario. Currently returns an empty list as no patches are defined.

has_prototypes?(resource)

See AshScenario.Info.has_prototypes?/1.

prototype(resource, name)

See AshScenario.Info.prototype/2.

prototype_names(resource)

See AshScenario.Info.prototype_names/1.

prototypes(resource)

Get prototype information from a resource module.

register_prototypes(resource_module)

@spec register_prototypes(module()) :: :ok | {:error, String.t()}

Register prototypes from a resource module. This is typically called automatically when the resource is compiled.

run(prototype_refs, opts \\ [])

@spec run(
  [{module(), atom()}],
  keyword()
) :: {:ok, map()} | {:error, any()}

Execute prototypes with the specified strategy.

Parameters

  • prototype_refs - List of prototype references as {Module, :prototype_name} tuples
  • opts - Options for execution

Options

  • :strategy - Execution strategy (:database or :struct, defaults to :database)
  • :domain - The Ash domain to use (will be inferred if not provided)
  • :overrides - Map of attribute overrides keyed by prototype reference

Examples

# Execute with database persistence (default)
{:ok, resources} = AshScenario.run([
  {User, :admin},
  {Post, :published_post}
])

# Execute as in-memory structs
{:ok, structs} = AshScenario.run([
  {User, :admin}
], strategy: :struct)

# With overrides
{:ok, resources} = AshScenario.run([
  {Post, :draft}
], overrides: %{{Post, :draft} => %{title: "Custom Title"}})

run_all(resource_module, opts \\ [])

@spec run_all(
  module(),
  keyword()
) :: {:ok, map()} | {:error, any()}

Execute all prototypes defined for a resource module.

Parameters

  • resource_module - The Ash resource module containing prototype definitions
  • opts - Options for execution

Options

  • :strategy - Execution strategy (:database or :struct, defaults to :database)
  • :domain - The Ash domain to use (will be inferred if not provided)

Examples

{:ok, resources} = AshScenario.run_all(Post)
{:ok, structs} = AshScenario.run_all(Post, strategy: :struct)

run_scenario(test_module, scenario_name, opts \\ [])

@spec run_scenario(module(), atom(), keyword()) :: {:ok, map()} | {:error, String.t()}

Run a named scenario from a test module.

This function works with the scenario DSL for defining named test setups.

Options

  • :domain - The Ash domain to use (will be inferred if not provided)
  • :strategy - Execution strategy (:database or :struct, defaults to :database)

Examples

{:ok, instances} = AshScenario.run_scenario(MyTest, :basic_setup)
{:ok, instances} = AshScenario.run_scenario(MyTest, :basic_setup, domain: MyApp.Domain)
{:ok, structs} = AshScenario.run_scenario(MyTest, :basic_setup, strategy: :struct)

sections()

Returns the DSL sections provided by AshScenario. Delegates to AshScenario.Dsl for the actual sections.

start_registry(opts \\ [])

@spec start_registry(keyword()) :: {:ok, pid()} | {:error, term()}

Start the scenario registry (should be called in your application supervision tree).