A reusable conformance case for Statifier.Invoke.Handler implementations

• the second member of the Statifier.Testing family ADR-0053 opened, and the mechanical pin for the behaviour contract ADR-0051 decision 4 and docs/extending.md state in prose. A host application uses this module in a test alongside use ExUnit.Case and gets the contract checks as generated tests against its own handler:

  defmodule MyApp.EnrichHandlerConformanceTest do

  use ExUnit.Case, async: false
  use Statifier.Testing.HandlerCase,
    handler: MyApp.EnrichHandler,
    type: "myapp:enrich"

  end

What the generated tests verify, each a clause of the documented contract:

1. start/2, cancel/2, and forward/3 are pure planning callbacks - deterministic for fixed inputs, observably effect-free, returning the documented shapes (Statifier.Invoke.Handler's moduledoc, point 1).
2. perform/2 is idempotent on invoke_id: performing the handler's own planned instructions twice must not duplicate observable effects (point 2 there, and docs/extending.md's "At-least-once" section). Idempotency needs an observation point only the implementor can name - see "The observation point" below.
3. cancel/2 after start/2 plans without raising, and cancel/2 for an invoke_id the handler never saw is a no-op, never a raise - the library plans cancels off the live invocation table, but a crash-recovering host may replay a cancel whose start it never durably recorded.
4. {:error, _} from start/2 surfaces as error.execution in the driving chart (ADR-0051 decision 1's classification table), pinned by driving a minimal chart fixture with a case-internal always-failing probe handler registered under the implementor's own type string.
5. Handler exceptions propagate - the library never rescues them into an event (docs/extending.md, "Where the library will not help") - pinned with a case-internal raising probe the same way.

Checks 4 and 5 pin the library's half of the contract with probe handlers rather than the implementation under test, on purpose: a conforming handler has no reason to expose a start that fails or raises on demand, and the point of running the pins downstream is that the contract an implementor builds against stays enforced by tests where the implementations live, not by this repository's suite alone. A handler whose start/2 has a real failure path asserts its own half with assert_erroring_start/3.

Every check is also a public function on this module, so a suite that wants different fixtures - or only one of the checks - calls them directly instead of use-ing the whole case.

Options

• :handler (required) - the Statifier.Invoke.Handler implementation module under test.
• :type (required) - the <invoke type> string the handler serves.

The fixtures, and overriding them

The generated tests plan against a synthetic %Statifier.Effect.Invoke{}, a plan context, and an autoforwarded event, built by build_invoke/2, build_ctx/3, and build_event/1. Each is reachable through an overridable function in the use-ing module, so a handler that reads params, src, or content overrides the one fixture it cares about:

• conformance_invoke/0 - the %Statifier.Effect.Invoke{} handed to start/2.
• conformance_ctx/0 - the plan context handed to every callback.
• conformance_event/0 - the %Statifier.Event{} handed to forward/3.
• observed_effects/1 - the observation point, below.

The observation point

The case cannot see your job queue, your database, or your test inbox, so idempotency (and planning purity) are judged against a function you declare: override observed_effects/1 to return the observable effects attributable to the given invoke_id at the moment of the call - a list of enqueued jobs, a set of rows, whatever your perform/2 writes. The default returns :unobserved, which skips the purity comparisons; the idempotency test flunks under that default whenever the handler actually routes instructions to perform/2, naming the override to write - a handler with real performed effects never gets a silent pass (ADR-0053's fail-not-skip discipline). A handler that routes nothing to perform/2 needs no observation point, and its idempotency test asserts exactly that instead.