Testing
View SourceTest the package as four connected boundaries: data, Codec, compilation, and execution. Give each behavior one primary test owner.
Public Contract Properties
The public contract register connects critical promises
to fixed and generated evidence. Property tests live under test/property/,
grouped by API area. They are excluded from default mix test.
mix test.property --warnings-as-errors
mix test.fuzz --warnings-as-errors --seed 123
Selected runs write _build/test/property-report.json with runtime, revision,
test results, contract IDs, and declared forced case IDs. The report counts passing
evidence; it does not claim complete API, branch, or random-transition coverage.
One passed owner is not proof of every clause in a contract. The report marks
incomplete and failed runs. CI must remove old reports before Mix starts and
check the Mix exit status as well as the new report.
See test/property/README.md in the source checkout for replay and cleanup.
The :fuzz tag selects fifteen larger cases; :property selects the short suite.
Budgets and input-size limits are ExUnit tags in the owning tests. Both tags are
excluded by default. Each fuzz case records observations and saves reduced
failures for replay. Fourteen use StreamData and JSON inputs; the revision case
uses PropCheck's native command generation, shrinking, and term replay.
Every fuzz case has a 15-minute ExUnit timeout. StreamData discovery also has a 5-minute limit and a sample-count limit. The revision case uses 500 histories with a maximum size of 100. Short cases keep their current limits. The report separates property and fuzz evidence and records contract IDs with measurements. The fuzz contract plan lists all fifteen implemented cases, their public contract IDs, and their expected checks.
Test Data Without Running Work
Data tests cover:
- Action and Instruction construction;
- component constructors;
- Flow expressions and reference scopes;
- Flow graph validation;
- explicit and inferred dependencies; and
- semantic identity.
test "declares a result dependency" do
flow = MyApp.Flows.BuildReport.flow()
assert {:ok, dependencies} = Jido.Flow.dependencies(flow)
assert dependencies["summary"] == %{
needs: [],
references: ["load"],
effective: ["load"]
}
endUse Jido.Flow.validate/1 for inert structure checks. Use
validate_executable/1 only when the test must check target contracts.
Test Codec And Registry
Codec tests own:
- Registry validation and aliases;
- encode and decode parity;
- real JSON byte round trips;
- exact stored keys and version;
- unknown identifier errors;
- UTF-8, depth, width, and total-node limits; and
- the rule that decode does not execute work.
{:ok, document} = Jido.Flow.Codec.encode(flow, registry)
json = Jason.encode!(document)
{:ok, restored} = Jido.Flow.Codec.decode(Jason.decode!(json), registry)
assert Jido.Flow.to_map(restored) == Jido.Flow.to_map(flow)Do not use Jido.Flow.to_map/1 as the stored format.
Test Native Compilation
Compilation tests own the mapping from canonical components to native Runic constructs. Assert ports, connections, cardinality, Join, InputBinding, FanOut, FanIn, nested Workflow boundaries, source maps, and compilation identity where those facts are part of the contract.
assert {:ok, %Jido.Flow.Compiled{} = compiled} =
Jido.Flow.compile(flow)
assert %Runic.Workflow{} = compiled.workflowDo not make an internal compiler module public for a test.
Test Action Behavior And Exec Separately
Call run/2 directly for the Action business rule.
test "adds values" do
assert {:ok, %{value: 3}} =
MyApp.Actions.Add.run(%{left: 1, right: 2}, %{})
endThen test the public boundary for validation, output normalization, process failure, and error conversion.
test "rejects invalid input before work" do
assert {:error, %Jido.Action.Error.InvalidInputError{}} =
Jido.Exec.run(MyApp.Actions.Add, %{left: "1", right: 2})
endInclude returned errors, raises, throws, exits, and hard process kills when the application relies on those boundaries. Assert process cleanup as well as the returned error.
Test Flow Results And Transitions
Run-to-completion tests own final values and Flow errors.
assert {:ok, expected} =
Jido.Exec.run(MyApp.Flows.BuildReport, input)Step-wise tests own readiness and state transitions.
assert {:ok, execution} =
Jido.Exec.start(MyApp.Flows.BuildReport, input)
assert Enum.all?(
Jido.Exec.ready(execution),
&match?(%Jido.Exec.Work{}, &1)
)
assert {:ok, _runnables, execution} = Jido.Exec.wave(execution)
assert {:ok, execution} = Jido.Exec.continue(execution)
assert Jido.Exec.result(execution) == {:ok, expected}Always bind the newest Execution value. Add a focused test that an old revision fails before work starts.
A failed runnable is an applied transition. step/2 can return :ok with a
Work whose status is :failed. Read the terminal error with result/1.
Test Components At Their Semantic Boundary
For Choice, test every option, first-match order, and fallback. Confirm that a selected target failure does not run fallback.
For Map, test input order, empty input, both error modes, and concurrent order preservation. For Reduce, use a non-associative example to prove serial source order and test the empty collection.
For Iterate, test zero-iteration completion, State replacement, normal completion, State schema rejection, and exhaustion without one extra body call.
For Subflow, test the child directly, then test the parent input and output
mapping. Use Work paths and roles to test child stopping points. Keep native shape
assertions in compiler tests or explicit Jido.Exec.native/1 inspection tests.
Keep Concurrent Tests Deterministic
Do not use elapsed time or Process.sleep/1 as synchronization.
- Give each worker a unique reference.
- Make each worker send a ready message.
- Release work with an explicit message.
- Monitor workers and callers when exit behavior matters.
- Use a confirmed barrier before
refute_received/1. - Assert canonical result order, not task completion order.
- Stop Tasks and helper processes in the test or
on_exit/1. - Use
async: falsefor global names, application environment, or shared telemetry state.
Use unique telemetry handler IDs. Detach every handler in on_exit/1.
Centralize Only Shared Fixtures
Place shared fixtures under test/support/fixtures with action, flow,
codec, and execution folders. Keep a one-use incidental fixture in its test
module. A fixture function must not make assertions or hide the public
contract under test.
A small end-to-end test can prove that DSL, direct constructors, data definitions, and Codec converge. Do not repeat every lower-level case in that combined test.
Test Runnable Examples
test/examples/action_effects_test.exs executes the Elixir cells from
Maps, Streams, And Optional Effects. It checks the
same order approval and CSV export Actions through public execution APIs.
The tests run in the default suite; no external service is needed.
mix test test/examples/action_effects_test.exs