View Source Smokestack behaviour (smokestack v0.4.0)
Smokestack provides a way to define test factories for your Ash Resources using a convenient DSL:
defmodule MyApp.Factory do
use Smokestack
factory Character do
attribute :name, &Faker.StarWars.character/0
attribute :affiliation, choose(["Galactic Empire", "Rebel Alliance"])
end
end
defmodule MyApp.CharacterTest do
use MyApp.DataCase
use MyApp.Factory
test "it can build a character" do
assert character = insert!(Character)
end
end
Templates
Each attribute uses a template to generate a value when building a factory.
Templates can be anything that implements the Smokestack.Template
protocol.
This protocol is automatically implemented for functions with arities zero
through two - meaning you can just drop in your own functions - or use one of
the built-in helpers from Smokestack.Dsl.Template
.
Variants
Sometimes you need to make slightly different factories to build a resource in a specific state for your test scenario.
Here's an example defining an alternate :trek
variant for the character
factory defined above:
factory Character, :trek do
attribute :name, choose(["J.L. Pipes", "Severn", "Slickback"])
attribute :affiliation, choose(["Entrepreneur", "Voyager"])
end
Building resource records
You can use insert/2
and insert!/2
to build and insert records. Records
are inserted using Ash.Seed.seed/2
, which means that they bypass the usual
Ash lifecycle (actions, validations, etc).
Options
load
: an atom, list of atoms or keyword list of the same listing relationships, calculations and aggregates that should be loaded after the record is created.count
: rather than inserting just a single record, you can specify a number of records to be inserted. A list of records will be returned.build
: an atom, list of atoms or keyword list of the same describing relationships which you would like built alongside the record. If the related resource has a variant which matches the current one, it will be used, and if not the:default
variant will be.attrs
: A map or keyword list of attributes you would like to set directly on the created record, rather than using the value provided by the factory.
Building parameters
As well as inserting records directly you can use params/2
and params!/2
to build parameters for use testing controller actions, HTTP requests, etc.
Options
encode
: rather than returning a map or maps, provide an encoder module to serialise the parameters. Commonly you would useJason
orPoison
.nest
: rather than returning a map or maps directly, wrap the result in an outer map using the provided key.key_case
: change the case of the keys into one of the many cases supported by recase.key_type
: specify whether the returned map or maps should use string or atom keys (ignored when using theencode
option).count
: rather than returning just a single map, you can specify a number of results to be returned. A list of maps will be returned.build
: an atom, list of atoms or keyword list of the same describing relationships which you would like built within the result. If the related resource has a variant which matches the current one, it will be used, and if not the:default
variant will be.attrs
: A map or keyword list of attributes you would like to set directly on the result, rather than using the value provided by the factory.
DSL Documentation
Index
- smokestack
- factory
- attribute
- factory
Docs
smokestack
- factory
- attribute
:api
(atom/0
) - The default Ash API to use when evaluating loads
factory
Define factories for a resource
:api
(atom/0
) - The Ash API to use when evaluating loads:resource
(atom/0
) - Required. An Ash Resource:variant
(atom/0
) - The name of a factory variant The default value is:default
.
attribute
:name
(atom/0
) - Required. The name of the target attribute:generator
- Required. A function which can generate an appropriate value for the attribute.œ
Summary
Types
Choose a factory variant to use. Defaults to :default
.
Callbacks
Runs a factory and uses it to insert Ash resources into their data layers.
Raising version of insert/4
.
Runs a factory and uses it to build a parameters suitable for simulating a request.
Raising version of params/2
.
Types
@type insert_option() :: variant_option() | Smokestack.RecordBuilder.option()
@type param_option() :: variant_option() | Smokestack.ParamBuilder.option()
@type recursive_atom_list() :: atom() | [atom() | {atom(), recursive_atom_list()}]
@type t() :: module()
@type variant_option() :: {:variant, atom()}
Choose a factory variant to use. Defaults to :default
.
Callbacks
@callback insert(Ash.Resource.t(), [insert_option()]) :: {:ok, Smokestack.RecordBuilder.result()} | {:error, any()}
Runs a factory and uses it to insert Ash resources into their data layers.
Automatically implemented by modules which use Smokestack
.
See Smokestack.RecordBuilder.build/3
for more information.
@callback insert!(Ash.Resource.t(), [insert_option()]) :: Smokestack.RecordBuilder.result() | no_return()
Raising version of insert/4
.
Automatically implemented by modules which use Smokestack
.
See Smokestack.RecordBuilder.build/3
for more information.
@callback params(Ash.Resource.t(), [param_option()]) :: {:ok, Smokestack.ParamBuilder.result()} | {:error, any()}
Runs a factory and uses it to build a parameters suitable for simulating a request.
Automatically implemented by modules which use Smokestack
.
See Smokestack.ParamBuilder.build/2
for more information.
@callback params!(Ash.Resource.t(), [param_option()]) :: Smokestack.ParamBuilder.result() | no_return()
Raising version of params/2
.
Automatically implemented by modules which use Smokestack
.
See Smokestack.ParamBuilder.build/3
for more information.