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 use Jason or Poison.
  • 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 the encode 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

Docs

smokestack


  • :api (atom/0) - The default Ash API to use when evaluating loads

factory

Define factories for a resource

  • attribute

  • :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

t()

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.

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.

Raising version of params/2.

Automatically implemented by modules which use Smokestack.

See Smokestack.ParamBuilder.build/3 for more information.