AshScenario.Scenario (ash_scenario v0.6.0)

Test scenario DSL for creating named data setups with overrides.

This module provides both a macro-based DSL for defining named scenarios in test modules and direct functions for executing prototypes with different strategies.

Direct Execution

Execute prototypes directly without named scenarios:

# Create resources in the database (default)
{:ok, resources} = AshScenario.run([
  {Post, :published_post},
  {User, :admin}
])

# Create in-memory structs without persistence
{:ok, structs} = AshScenario.run([
  {Post, :published_post}
], strategy: :struct)

Named Scenarios

Define reusable scenarios in test modules:

defmodule MyTest do
  use ExUnit.Case
  use AshScenario.Scenario

  scenario :basic_setup do
    another_post do
      title "Custom title for this test"
    end
  end

  test "basic scenario" do
    {:ok, instances} = AshScenario.run_scenario(__MODULE__, :basic_setup)
    assert instances.another_post.title == "Custom title for this test"
  end
end

Options

:extensions (list of module that adopts Spark.Dsl.Extension) - A list of DSL extensions to add to the Spark.Dsl
:otp_app (atom/0) - The otp_app to use for any application configurable options
:fragments (list of module/0) - Fragments to include in the Spark.Dsl. See the fragments guide for more.

Summary

Types

created_resources_map()

prototype_ref()

Functions

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.

Types

created_resources_map()

@type created_resources_map() :: %{required(prototype_ref()) => struct()}

prototype_ref()

@type prototype_ref() :: {module(), atom()}

Functions

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 (same as run/2)

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 is for compatibility with the scenario DSL.

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)