# `Beancount.Golden`
[🔗](https://github.com/thanos/beancount_ex/blob/v0.6.0/lib/beancount/golden.ex#L1)

Helpers for golden-file regression testing.

A golden fixture is a directory under `test/fixtures/golden/` containing:

  * `input.exs` - an Elixir script whose last expression is a directive list.
  * `expected.bean` - the expected rendered Beancount text.
  * `expected.result.json` - the expected normalized `Beancount.Result`
    (only meaningful when real Beancount is available).

Rendering is deterministic, so the rendered output of `input.exs` must match
`expected.bean` byte-for-byte. The `mix beancount.golden.update` task
regenerates these files.

# `cases`

```elixir
@spec cases() :: [Path.t()]
```

List all golden fixture case directories.

## Examples

    iex> cases = Beancount.Golden.cases()
    iex> is_list(cases)
    true

# `expected_bean`

```elixir
@spec expected_bean(Path.t()) :: binary() | nil
```

Read a fixture's expected `.bean` text, or `nil` if it does not exist.

## Examples

    case_dir = Path.join(Beancount.Golden.root(), "basic_txn")
    bean = Beancount.Golden.expected_bean(case_dir)
    is_binary(bean)
    # => true

# `expected_result`

```elixir
@spec expected_result(Path.t()) :: map() | nil
```

Read and decode a fixture's expected normalized result, or `nil`.

## Examples

    case_dir = Path.join(Beancount.Golden.root(), "basic_txn")
    result = Beancount.Golden.expected_result(case_dir)
    result["status"]
    # => "ok"

# `load_directives`

```elixir
@spec load_directives(Path.t()) :: [Beancount.Directive.t()]
```

Evaluate a fixture's `input.exs` and return its directive list.

## Examples

    case_dir = Path.join(Beancount.Golden.root(), "basic_txn")
    directives = Beancount.Golden.load_directives(case_dir)
    length(directives) > 0
    # => true

# `render`

```elixir
@spec render(Path.t()) :: binary()
```

Render a fixture's directives to `.bean` text.

## Examples

    case_dir = Path.join(Beancount.Golden.root(), "basic_txn")
    bean = Beancount.Golden.render(case_dir)
    String.contains?(bean, "open Assets:Bank")
    # => true

# `root`

```elixir
@spec root() :: Path.t()
```

Root directory containing all golden fixtures.

## Examples

    iex> Beancount.Golden.root() |> String.ends_with?("test/fixtures/golden")
    true

---

*Consult [api-reference.md](api-reference.md) for complete listing*