docs: add the engine-side test-utils harness page#342
Closed
lgahdl wants to merge 2 commits into
Closed
Conversation
Closes nullislabs#279. crates/nexum-runtime's test-utils feature (MockChainProvider, MockStateStore, MockTypes, mock_components, TestRuntime) had no prose docs anywhere - grepped every doc for MockChainProvider/TestRuntime/ mock_components and found zero hits. The issue's claim of an existing "one-sentence aside" in docs/05-sdk-design.md is also stale: that doc only discusses the guest-side nexum-sdk-test/shepherd-sdk-test mocks, a different surface entirely. New page leads with the guardrail the issue specifies: module business logic tests against MockHost in plain Rust (no wasm), the engine harness reserved for engine/host/boundary correctness (needs a real compiled component). Documents the test-utils feature gate + self dev-dependency pattern (quoted verbatim from Cargo.toml), the two API layers (bare mocks vs TestRuntime), and a worked example covering block injection, wait_for_log, chain-request programming, error/stream-end injection, store assertions, and the manual clock. The worked example is not illustrative pseudocode: built it as a real standalone #[tokio::test] against the actual crate and ran it (caught and fixed a missing type annotation on Header::default() in the process - the same bug would have shipped in the doc otherwise) before copying it into the page. Linked from docs/00-overview.md's SDK section, with a sentence distinguishing the two mock surfaces at the exact spot a reader would otherwise conflate them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfSsJPYDQ1GQGbnSVFxATx
…s harness page Self-review: the "beyond the happy path" bullets present ChainMethod::EthCall and push_block_err(err) as literal code, unlike the main worked example (which is a complete, verified-compiling block with its own use lines). Verified both types are public (nexum_runtime::host::component::ChainMethod, nexum_runtime::host::provider_pool::ProviderError) and added the import path inline so a reader copy-pasting the fragment doesn't hit an unresolved-name error and have to go hunting. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TfSsJPYDQ1GQGbnSVFxATx
mfw78
added
the
base: develop
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Closes #279 — adds
docs/testing-runtime-harness.mddescribingcrates/nexum-runtime'stest-utilsfeature (MockChainProvider,MockStateStore,MockTypes,mock_components,TestRuntime/TestRuntimeBuilder), which had no prose documentation anywhere in the repo.Verification before writing
MockChainProvider,TestRuntime,mock_components— zero hits. Confirmed the gap is real.docs/05-sdk-design.md. Checked: that's stale too — that doc only discusses the guest-sidenexum-sdk-test/shepherd-sdk-testmocks (a different surface for testing module business logic), never the engine-side harness this page is about.test_utils/mod.rs,test_utils/harness.rs,test_utils/chain.rs, the crate'sCargo.tomlfeature/dev-dependency block) to write the API description and feature-gate quote, rather than paraphrasing the issue.The worked example is a real, run test
Rather than write illustrative pseudocode, I built the worked example as a standalone
#[tokio::test]against the actual crate, ran it, and only copied it into the doc after it passed. That caught a real bug before it shipped:Header::default()needs an explicitlet mut header: Header = ...type annotation (the type param can't be inferred without it, sinceHeaderis generic) — I'd dropped it while writing the first draft. Would have been a broken doc example otherwise.Structure
Leads with the guardrail the issue specifies (module logic →
MockHost, no wasm; engine/host/boundary correctness → this harness, real wasm component) since that's the load-bearing part per the issue. Documents the feature gate + self dev-dependency pattern, the two API layers (bare mocks vsTestRuntime), the worked example, then pointers to chain-log injection / chain-request programming / error-and-stream-end injection / store assertions / the manual clock — and a closing section redirecting a module-logic reader to the right page.Linked from
docs/00-overview.md's SDK section with one sentence distinguishing the two mock surfaces at the exact spot a reader would otherwise conflate them, per the issue's explicit ask.Testing
Docs-only change to the repo, but the code sample was compiled and run for real (see above) before being copied into the page.
cargo test -p nexum-runtime test_utils::— 18 passed, unaffected.