Expand description
In-process test harness for Portaki module unit tests.
§Role in the SDK stack
portaki-test-utils complements portaki_sdk for dev-dependencies in
module crates. Production Wasm modules call host functions through
portaki_sdk::host (KV, i18n, connectors, repo, …). This crate supplies
MockHostFunctions, a portaki_sdk::host::HostBackend that runs entirely
in memory on the test thread.
Typical test flow:
- Build a
portaki_sdk::ContextwithMockContextBuilder::guestorMockContextBuilder::host. - Seed translations, KV bytes, and connector JSON stubs.
- Call
MockContextBuilder::runto install the mock backend viaportaki_sdk::host::with_hostand execute module code. - Assert rendered SDUI with
SurfaceAssertions. It walks every primitive of the contract, so a module needs nocontains_component_typehelper of its own:
use portaki_sdk::sdui::primitives::{Card, EmptyState, Stack};
use portaki_sdk::sdui::surface::Surface;
use portaki_test_utils::SurfaceAssertions;
let surface = Surface::new(Stack::new().child(Card::new()));
let tree = SurfaceAssertions::new(&surface);
// Was: assert!(contains_component_type(&surface, "Card"));
assert!(tree.contains_type("Card"));
assert!(!tree.contains_primitive::<EmptyState>());§Relationship to portaki-connectors
When module code calls portaki_connectors::OpenWeather::current, the mock
host returns JSON registered with
MockContextBuilder::with_connector_response. No network or gateway
process is required.
§Example
use portaki_sdk::capability::{core, external};
use portaki_test_utils::{MockContext, Property};
MockContext::guest()
.with_property(Property::default())
.with_capabilities(&[core::STORAGE, external::OPEN_WEATHER_POOL])
.with_connector_response(
"open-weather",
"current",
r#"{"main":{"temp":21.5,"humidity":55},"weather":[{"main":"Clear"}]}"#,
)
.run(|_ctx| {
// Module code calling portaki_connectors::OpenWeather::current reads the stub.
});§Layout
MockContextBuilder/MockHostFunctions— mock host installationProperty,Booking,GuestIdentityFixture— default fixturesSurfaceAssertions,PrimitiveTag— SDUI tree queries over every primitiveassert_refused,assert_declared_error— a handler refused with a declared codescenarios— the seven pathological cases of the sandbox, fortests/scenarios.rsconformance!/conformance— the battery every module runs: manifest, listing, surfaces, operations, i18n, emails, contracts
Modules§
- conformance
- The conformance battery every Portaki module runs — one call, seven checks.
- scenarios
- The seven pathological cases the sandbox replays after every deploy, for
cargo test.
Macros§
- conformance
- Generates the conformance tests of the module this integration test belongs to.
- link_
module - Links the module’s library into this integration test, so its
#[surface]s are declared — for a test that names nothing of it, like one that only asserts on the battery’s findings.
Structs§
- Booking
- Sample booking window for event-handler tests.
- Connector
Call - One
host::connectors::call, as the module made it. - Guest
Identity Fixture - Guest session fixture convertible to
GuestIdentity. - LogLine
- One
host::logline, as the module wrote it. - Mock
Context Builder - Fluent builder for a test
ContextandMockHostFunctionsbackend. - Mock
Host Functions - Thread-safe in-memory implementation of
HostBackend. - Property
- Sample rental property for tests.
- Surface
Assertions - Borrowed wrapper for depth-first SDUI tree queries.
Traits§
- Primitive
Tag - Associates a type with the
Componentnodes it matches, forSurfaceAssertionsqueries.
Functions§
- assert_
declared_ error - Asserts that
codeis declared byportaki_module!(error = "…")in a module linked into this test binary. - assert_
refused - Asserts that
resultis the refusalcode, and that the module declares it.
Type Aliases§
- Mock
Context - Alias for
MockContextBuilder— preferred name in module test code.