AGENTS.md

1# AGENTS.md - Jido Test Support Guide
2 
3## Intent
4Provide stable, reusable testing patterns for pure agents, AgentServer runtime behavior, and multi-agent flows.
5 
6## Runtime Baseline
7- Elixir `~> 1.18`
8- OTP `27+` (release QA baseline)
9 
10## Commands
11- `mix test`
12- `mix test test/path/to/file_test.exs`
13- `mix test --cover`
14- `mix test --include example`
15 
16## Support Modules
17- `JidoTest.Case`: isolated Jido instance per test (`jido`, `jido_pid` context)
18- `JidoTest.Eventually`: polling helpers/macros (`eventually`, `assert_eventually`, `eventually_state`)
19- `JidoTest.Support.TestTracer`: lightweight span capture for runtime assertions
20- `JidoTest.TestAgents` and `JidoTest.TestActions`: canonical fixtures for behavior-level tests
21 
22## Standards
23- Prefer behavior assertions over implementation/log assertions
24- Avoid `Process.sleep/1`; use eventual assertions and monitored process lifecycle checks
25- Keep tests focused and deterministic (single behavior per test where practical)
26- Use unique IDs/helpers to avoid test cross-talk
27 
28## High-Value Coverage
29- `cmd/2` immutability and directive emission semantics
30- AgentServer signal routing and runtime directive execution
31- Parent-child lifecycle (`SpawnAgent`, `StopChild`) and state synchronization
32- StateOp behavior (`SetState`, `ReplaceState`, `DeleteKeys`, `SetPath`, `DeletePath`)
33 
34## Release Hygiene
35- Keep test fixtures aligned with current directive/state-op/tool contracts
36- Use Conventional Commits
37- Update examples in `test/examples/` when behavior contracts change
38 
39## References
40- `test/support/`
41- `test/examples/`
42- `../README.md`
43- https://hexdocs.pm/jido
44