# `CheckerCab`

Documentation for CheckerCab.

This documentation assumes these functions are used in the context of unit
tests.

# `comparable_input`

```elixir
@type comparable_input() :: map() | {map(), :string_keys | :atom_keys}
```

# `inputs`

```elixir
@type inputs() :: [
  expected: comparable_input(),
  actual: comparable_input(),
  fields: [atom()],
  skip_fields: [atom()],
  opts: [option()]
]
```

# `option`

```elixir
@type option() :: {:convert_dates, boolean()}
```

# `assert_values_for`

```elixir
@spec assert_values_for(inputs()) :: :ok | no_return()
```

Compares the values of two maps for specified keys.

When values do not match, this function will flunk the current test with
explicit information about the first value that did not match.

This function also accepts a list of fields to _not_ compare, and can be mixed
with the fields to compare.

This function assumes keys are atoms unless specified as `:string_keys`, and
will convert keys into a common type before comparing values (can compare
atom-keyed and string-keyed maps with same-named keys). Additionally,
`:atom_keys` can be provided to be more explicit.

## Options
* `:convert_dates`
  When `true`, will convert date-representing values to ISO-8601 formatted
strings.

## Examples
```
## your_unit_test.exs
expected = %{key1: :value, key2: :value, key3: :value}
actual = %{"key1" => :value, "key2" => :value, "key3" => :value}

## returns :ok when expected and actual match
assert_values_for(
  expected: expected,
  actual: {actual, :string_keys},
  fields: [:key1, :key2, :key3]
)
```

With dates:

```
expected = %{date: ~U[2021-12-17 03:08:36.579609Z], key2: :value, key3: :value}
actual = %{"date" => "2021-12-17T03:08:36.579609Z", "key2" => :value, "key3" => :value}

## Will not flunk for different types of dates if they both convert to the
same ISO 8601 string

assert_values_for(
  expected: expected,
  actual: {actual, :string_keys},
  fields: [:date, :key2, :key3],
  opts: [convert_dates: true]
)
```

Using `:skip_fields`:

```
expected = %{key1: :value, key2: :value, key3: :value, value_that_wont_match: "Panama"}
actual = %{key1: :value, key2: :value, key3: :value, value_that_wont_match: "Manimal"}

## Returns :ok when expected and actual match. Can exclude fields anticipated
to be different.
assert_values_for(
  expected: expected,
  actual: actual,
  fields: [:key1, :key2, :key3],
  skip_fields: [:value_that_wont_match]
)
```

# `fields_for`

```elixir
@spec fields_for(map() | struct() | Ecto.Schema.t() | module()) :: [
  atom() | String.t()
]
```

Returns the keys of a map or struct.

## Examples

    iex> fields_for(%{"string_key1" => :value, "string_key2" => :value})
    ["string_key1", "string_key2"]

    iex> fields_for(%{atom_key1: :value, atom_key2: :value})
    [:atom_key1, :atom_key2]

Returns a list of defined keys from struct arguments (`:__struct__` is not
returned)

    iex> fields_for(%StructModule{})
    [:key1, :key2, :key3]

Returns a list of defined keys from `Ecto.Schema` arguments, but does not
return virtual fields.

    iex> fields_for(%EctoSchemaModule{})
    [:id, :field1, :field2, :field3]

Additionally, the function accepts the module name of an `Ecto.Schema`.
This does not work with structs.

    iex> fields_for(EctoSchemaModule)
    [:id, :field1, :field2, :field3]

---

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