# `AshGrant.PolicyTest.YamlParser`
[🔗](https://github.com/jhlee111/ash_grant/blob/v0.14.1/lib/ash_grant/policy_test/yaml_parser.ex#L1)

Parses YAML policy test files and runs them.

YAML provides an alternative format for defining policy tests,
useful for:

- Non-Elixir developers reviewing permissions
- Generating tests from external tools
- Documentation purposes

## YAML Format

    resource: MyApp.Document

    actors:
      reader:
        role: reader
      author:
        role: author
        id: "author_001"

    tests:
      - name: "reader can read"
        assert_can:
          actor: reader
          action: read

      - name: "reader can read published"
        assert_can:
          actor: reader
          action: read
          record:
            status: published

      - name: "reader cannot read drafts"
        assert_cannot:
          actor: reader
          action: read
          record:
            status: draft

### Argument-based scopes

Scopes can reference action arguments via `^arg(:name)`. To exercise those
in a YAML test, supply an `arguments:` map alongside `record:`:

    - name: "manager can update refund in their unit"
      assert_can:
        actor: unit_manager
        action: update
        record:
          author_id: "u1"
        arguments:
          center_id: "center_A"

## Usage

    # Parse YAML file
    {:ok, parsed} = YamlParser.parse_file("policy_tests/document.yaml")

    # Run tests from YAML file
    {:ok, results} = YamlParser.run_yaml_tests("policy_tests/document.yaml")

# `parsed`

```elixir
@type parsed() :: %{
  resource: module(),
  actors: %{required(atom()) => map()},
  tests: [parsed_test()]
}
```

# `parsed_test`

```elixir
@type parsed_test() :: %{
  name: String.t(),
  type:
    :assert_can
    | :assert_cannot
    | :assert_fields_visible
    | :assert_fields_hidden,
  actor: atom(),
  action: atom() | nil,
  action_type: atom() | nil,
  record: map() | nil,
  arguments: map(),
  fields: [atom()] | nil
}
```

# `parse_file`

```elixir
@spec parse_file(String.t()) :: {:ok, parsed()} | {:error, term()}
```

Parses a YAML policy test file.

Returns `{:ok, parsed}` on success or `{:error, reason}` on failure.

# `parse_file!`

```elixir
@spec parse_file!(String.t()) :: parsed()
```

Parses a YAML policy test file and raises on error.

# `run_yaml_tests`

```elixir
@spec run_yaml_tests(String.t()) ::
  {:ok, [AshGrant.PolicyTest.Result.t()]} | {:error, term()}
```

Runs tests from a YAML file and returns results.

---

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