sails-gtest

Sails Gtest

Goal

Run the Sails-first test loop with generated clients and explicit gtest evidence before any live-node smoke step.

Inputs

• ../../assets/gtest-report-template.md — report format for gtest results
• ../../references/gtest-cheatsheet.md — quick reference for gtest APIs
• ../../references/gtest-patterns.md — common test patterns
• ../../references/sails-cheatsheet.md — Sails patterns and APIs
• ../../references/sails-gtest-and-local-validation.md — full gtest and validation guide
• ../../references/gear-gas-reservations-and-waitlist.md — gas reasoning for tests
• ../../references/scale-binary-decoding-guide.md — decoding raw reply bytes
• ../../references/sails-syscall-mapping.md — Syscall::* API for gas, message, and execution context

Write the result to docs/plans/YYYY-MM-DD-<topic>-gtest.md.

Expected Loop

1. Confirm the implementation target is ready for verification.
2. Use generated clients or GtestEnv instead of hand-built payloads where the workspace supports them.
3. If the test must go below generated clients, first decide whether the payload or reply bytes are Sails-routed, plain SCALE, or metadata-driven state output; then apply the raw mental model: send_bytes* returns a MessageId, run_next_block returns the BlockRunResult, and the reply evidence lives in the block result.
4. Pick the right BlockRunMode and advance blocks explicitly when replies or deferred effects depend on progression.
5. Use run_to_block when delayed work or timeout behavior spans multiple blocks.
6. Assert behavior, replies, events, or accounting in the test result, not just compilation.
7. Record failure mode, fix, and passing command output in the gtest note.
8. Route to ../sails-local-smoke/SKILL.md only after the suite is green.

Common Pitfalls

• Rust 2024 listener lifetime: Under edition 2024 capture rules, chaining generated-client calls into listen() can fail with "temporary value dropped while borrowed". In Sails 1.0 the service client implements Listener directly, so bind the service client before listening:

  let client = program.service_name();
  let mut events = client.listen().await.unwrap();