docs: improve the readme and moduledocs.
All checks were successful
continuous-integration/drone/push Build is passing
All checks were successful
continuous-integration/drone/push Build is passing
This commit is contained in:
parent
01c9e73b5b
commit
744e555577
2 changed files with 100 additions and 3 deletions
12
README.md
12
README.md
|
@ -25,7 +25,7 @@ defmodule MyApp.CharacterTest do
|
|||
use MyApp.Factory
|
||||
|
||||
test "it can build a character" do
|
||||
assert character = MyApp.Factory.build!(Character)
|
||||
assert character = insert!(Character)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
@ -43,7 +43,15 @@ def deps do
|
|||
end
|
||||
```
|
||||
|
||||
Since the package hasn't been published, there are no docs available on [HexDocs](https://hexdocs.pm/), but you can access the latest version [here](https://docs.harton.nz/james/smokestack).
|
||||
Since the package hasn't been published, there are no docs available on
|
||||
[HexDocs](https://hexdocs.pm/), but you can access the latest version
|
||||
[here](https://docs.harton.nz/james/smokestack).
|
||||
|
||||
## Github Mirror
|
||||
|
||||
This repository is mirrored [on Github](https://github.com/jimsynz/smokestack)
|
||||
from it's primary location [on my Forejo instance](https://code.harton.nz/james/smokestack).
|
||||
Feel free to raise issues and open PRs on Github.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
@ -2,6 +2,88 @@ defmodule Smokestack do
|
|||
alias Spark.{Dsl, Dsl.Extension}
|
||||
|
||||
@moduledoc """
|
||||
Smokestack provides a way to define test factories for your
|
||||
[Ash Resources](https://ash-hq.org/docs/module/ash/latest/ash-resource)
|
||||
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
|
||||
```
|
||||
|
||||
## 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](https://hex.pm/packages/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.
|
||||
|
||||
<!--- ash-hq-hide-start --> <!--- -->
|
||||
|
||||
|
@ -137,10 +219,17 @@ defmodule Smokestack do
|
|||
end
|
||||
end
|
||||
|
||||
defmacro __using__(_) do
|
||||
quote do
|
||||
import __MODULE__
|
||||
end
|
||||
end
|
||||
|
||||
defoverridable params: 2,
|
||||
params!: 2,
|
||||
insert: 2,
|
||||
insert!: 2
|
||||
insert!: 2,
|
||||
__using__: 1
|
||||
end
|
||||
] ++ super(opts)
|
||||
end
|
||||
|
|
Loading…
Reference in a new issue