Cyclium.Test.CheckpointMigration (Cyclium v0.1.5)

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.

Summary

Functions

assert_migration(schema_module, from, state, expected)

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

assert_migration_idempotent(schema_module, state)

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

assert_migration_safe(schema_module, opts)

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

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.

Functions

assert_migration(schema_module, from, state, expected)

(macro)

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

assert_migration_idempotent(schema_module, state)

(macro)

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

assert_migration_safe(schema_module, opts)

(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).