Test Plugins
Fidius ships a dedicated testing crate, fidius-test, with helpers for the
three workflows plugin and host authors need: in-process unit tests, full
dylib integration tests, and signed-plugin flows. This guide walks through
each layer.
All helpers are pub in fidius-test. Add it under [dev-dependencies]:
[dev-dependencies]fidius-test = "0.0.5"The fidius init-plugin and fidius init-host scaffolds add this automatically.
Layer 1: in-process tests (fastest)
Section titled “Layer 1: in-process tests (fastest)”The generated {Trait}Client::in_process(name) constructor invokes a plugin
method without compiling a cdylib or loading a dylib. Uses inventory to
find the plugin descriptor in the current test binary’s address space.
When to use: quick feedback during plugin development. A cargo test cycle
finishes in milliseconds because there’s no dylib build and no dlopen.
// In your plugin's src/lib.rsuse my_plugin_api::{plugin_impl, MyTrait};
pub struct MyPlugin;
#[plugin_impl(MyTrait)]impl MyTrait for MyPlugin { fn process(&self, input: String) -> String { format!("processed: {input}") }}
fidius::fidius_plugin_registry!();
#[cfg(test)]mod tests { use my_plugin_api::MyTraitClient;
#[test] fn process_works() { let client = MyTraitClient::in_process("MyPlugin").expect("registered"); let out = client.process(&"hello".to_string()).unwrap(); assert_eq!(out, "processed: hello"); }}The test imports the client from the interface crate. For the client to
be visible in tests, declare the interface crate as a [dev-dependencies]
entry with the host feature enabled (the fidius init-plugin scaffold
does this automatically):
[dependencies]my-plugin-api = { path = "..." } # cdylib build: no host featurefidius = { version = "..." }
[dev-dependencies]my-plugin-api = { path = "...", features = ["host"] } # tests: host feature onfidius-test = "0.0.5"Cargo unifies features per target, so the cdylib build does not pull
libloading through the host feature.
Client::in_process returns Err(LoadError::PluginNotFound) if no
#[plugin_impl] with that struct name is linked into the test binary.
Layer 2: dylib integration tests
Section titled “Layer 2: dylib integration tests”For end-to-end tests that exercise the full FFI path — including dylib
compilation, dlopen, descriptor validation, and signature verification —
use fidius_test::dylib_fixture.
use fidius_host::{PluginHandle, PluginHost};use fidius_test::dylib_fixture;use my_plugin_api::MyTraitClient;
#[test]fn loads_and_calls_plugin() { let fixture = dylib_fixture("../my-plugin").build();
let host = PluginHost::builder() .search_path(fixture.dir()) .build() .unwrap();
let loaded = host.load("MyPlugin").unwrap(); let handle = PluginHandle::from_loaded(loaded); let client = MyTraitClient::from_handle(handle);
let out = client.process(&"hello".to_string()).unwrap(); assert_eq!(out, "processed: hello");}dylib_fixture invokes cargo build on the plugin crate once per test
binary process — subsequent calls with the same path return the cached
build. Multiple tests in the same file share one build cycle.
Layer 3: signed-plugin flows
Section titled “Layer 3: signed-plugin flows”Signature verification is normally painful to test because it needs a real
keypair. fidius_test provides deterministic fixtures:
use fidius_host::PluginHost;use fidius_test::{dylib_fixture, fixture_keypair};
#[test]fn signed_plugin_with_trusted_key() { let (signing_key, verifying_key) = fixture_keypair();
let fixture = dylib_fixture("../my-plugin") .signed_with(&signing_key) .build();
let host = PluginHost::builder() .search_path(fixture.dir()) .require_signature(true) .trusted_keys(&[verifying_key]) .build() .unwrap();
host.load("MyPlugin").expect("signed with trusted key");}Available helpers:
| Helper | Purpose |
|---|---|
fixture_keypair() |
Deterministic (SigningKey, VerifyingKey) derived from a fixed seed |
fixture_keypair_with_seed(u8) |
Deterministic keypair with a caller-chosen seed — use different seeds for “wrong key” tests |
sign_dylib(path, &key) |
Write a .sig file next to a dylib (same convention as fidius sign) |
DylibFixtureBuilder::signed_with(&key) |
Sign the dylib during fixture build |
These keys are not secure — they exist only so tests can exercise the signing verification path deterministically. Never use them in production.
Layer 4: CLI smoke test
Section titled “Layer 4: CLI smoke test”For a zero-setup smoke test of a plugin package, use fidius test:
$ fidius test ./my-pluginBuilt: ./my-plugin/target/debug/libmy_plugin.dylib
Plugin: MyPlugin (interface MyTrait v1, 2 methods) [0] — needs input (method takes args) [1] ✓ invoked (output decoded as JSON)
Smoke passed: 1 plugin(s), 1 zero-arg method(s) invoked cleanlyThis builds the package, loads it, and attempts to invoke each method with a zero-argument input. It’s a smoke test — it verifies the FFI round-trip works, not that your method returns correct values. Methods with arguments are reported but not failed.
Useful as a CI pre-check and during local development to catch descriptor or registry issues without writing code.
Which layer should I write?
Section titled “Which layer should I write?”| Question | Answer |
|---|---|
| Fastest feedback while writing plugin logic | Layer 1 (in-process) |
| Verify the full FFI round-trip works | Layer 2 (dylib fixture) |
| Test signed-plugin host-side policy | Layer 3 (signing fixtures) |
| “Does my plugin even build and load?” | Layer 4 (fidius test) |
Write Layer 1 tests for nearly every method — they’re nearly free. Add Layer 2 integration tests for critical paths. Use Layer 3 when testing signature policy. Use Layer 4 as a CI smoke gate.