# `Cyclium.Test.CheckpointMigration`
[🔗](https://github.com/Cyclium/cyclium_ex/blob/main/lib/cyclium/test/checkpoint_migration.ex#L1)

Test helpers for property-based testing of checkpoint schema migrations.

Provides generators and assertion helpers so host apps can verify that
`migrate/2` callbacks safely transform any V1 state to the current version.

Requires `{:stream_data, "~> 1.0", only: :test}` in your deps.

## Usage

    defmodule MyApp.Checkpoints.POInvestigationTest do
      use ExUnit.Case, async: true
      use Cyclium.Test.CheckpointMigration

      describe "migration safety" do
        test "v1 -> current succeeds for any state" do
          assert_migration_safe(MyApp.Checkpoints.POInvestigation,
            from: 1,
            generator: fn ->
              StreamData.fixed_map(%{
                "vendor_id" => StreamData.string(:alphanumeric, min_length: 1),
                "vendor_contacts" => StreamData.list_of(
                  StreamData.map_of(
                    StreamData.string(:alphanumeric),
                    StreamData.string(:alphanumeric)
                  )
                )
              })
            end
          )
        end
      end
    end

If no generator is provided, a default fuzz generator produces random
nested maps with string keys and mixed-type values.

# `assert_migration`
*macro* 

Assert that migrating a specific state from one version to current produces
the expected result.

# `assert_migration_idempotent`
*macro* 

Assert that migration is idempotent — migrating an already-current state
returns it unchanged.

# `assert_migration_safe`
*macro* 

Assert that migrating from `from` to current version succeeds for all
generated states. Runs 100 iterations by default.

## Options

  * `:from` — starting version (required)
  * `:generator` — 0-arity function returning a StreamData generator (optional)
  * `:iterations` — number of property test iterations (default: 100)

# `default_state_generator`

Returns a default StreamData generator for random map states with
string keys and mixed values. Useful for fuzz testing migrations
that should be resilient to unexpected keys.

Only callable at test time (requires StreamData).

---

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