bookclerk_plugin_e2e
Support for the staged first-party plugin end-to-end suite.
The suite (tests/staged_plugins.rs) spawns every guest from a real
installation: platform guests under $BOOKCLERK_FILES_DIR/plugins/
(cargo install-platform) and optional/example guests under
$BOOKCLERK_PLUGIN_ARTIFACTS (cargo stage-plugins). It lives in its own
package so ordinary bookclerk-plugin-host test runs never need that
installation.
tests/native_gateway.rs is separate: it needs no staged installation and
launches the test-only native_gateway_probe bin through the production
native-behind-workerd path (CI check native_gateway, all three OSes).
| Variable | Effect |
|---|---|
BOOKCLERK_PLUGIN_ARTIFACTS / BOOKCLERK_FILES_DIR |
Staging roots; unset skips locally |
BOOKCLERK_STAGED_PLUGINS=a,b |
Check only these ids (plus platform guests); unset checks all |
BOOKCLERK_REQUIRE_STAGED_PLUGINS=1 |
Missing roots or ledgers fail instead of skipping (CI) |
| Item | Kind | Summary |
|---|---|---|
StagedScope |
enum | Which staged guests a run must check. |
all_expected_plugins |
function | Every first-party plugin id the full installation must contain. |
require_staged |
function | Whether missing staging prerequisites must fail the run. |
skip_or_fail |
function | Skips (local) or panics (required mode) for a missing prerequisite. |
staged_plugin_dir |
function | Finds the staged directory whose plugin.toml declares id. |
PLATFORM_PLUGINS |
constant | Platform guests installed into $BOOKCLERK_FILES_DIR/plugins/; always checked. |
OPTIONAL_PLUGINS |
constant | Optional first-party guests staged under $BOOKCLERK_PLUGIN_ARTIFACTS. |
EXAMPLE_PLUGINS |
constant | Reference Echo guests staged under $BOOKCLERK_PLUGIN_ARTIFACTS. |
STAGED_PLUGINS_ENV |
constant | Environment variable selecting a subset of staged guests to check. |
REQUIRE_STAGED_ENV |
constant | Environment variable turning missing staging prerequisites into failures. |
startup: Summaries for the plugin cold-start measurement (tests/cold_start.rs).
pub enum StagedScope {
Full,
Subset(BTreeSet<String>),
}
Which staged guests a run must check.
Variants
Full: The complete installation (default).Subset: Only these non-platform ids; platform guests are always included.
pub fn parse(raw: Option<&str>) -> Result<Self, String>
Parses a BOOKCLERK_STAGED_PLUGINS value.
raw- Comma-separated plugin ids;None, empty, orallmeans full.
The scope to check.
Returns a message naming the first id that is not a known first-party plugin, so a typo cannot silently shrink coverage.
pub fn from_env() -> Result<Self, String>
Reads the scope from BOOKCLERK_STAGED_PLUGINS.
The parsed scope.
Same as StagedScope::parse.
pub fn includes(&self, id: &str) -> bool
Whether id is checked in this scope.
id- Plugin manifest id.
true for platform guests and for ids inside the scope.
pub fn required_ids(&self) -> Vec<String>
Ids that must be discovered for this scope.
Platform ids followed by the scoped ids (all expected ids when full).
Implements: Clone, Debug, Eq, PartialEq
pub fn all_expected_plugins() -> Vec<&'static str>
Every first-party plugin id the full installation must contain.
Platform, optional, then example ids.
pub fn require_staged() -> bool
Whether missing staging prerequisites must fail the run.
true when BOOKCLERK_REQUIRE_STAGED_PLUGINS=1.
pub fn skip_or_fail(reason: &str)
Skips (local) or panics (required mode) for a missing prerequisite.
reason- Human-readable prerequisite that is missing.
Panics when require_staged is true.
pub fn staged_plugin_dir(root: &Path, id: &str) -> Option<PathBuf>
Finds the staged directory whose plugin.toml declares id.
Staging writes pk-* directories keyed by plugin key, so an id cannot be
joined onto the artifacts root directly.
root- Staging root ($BOOKCLERK_PLUGIN_ARTIFACTS).id- Plugin manifest id.
The guest directory, or None when no staged manifest declares id.
pub const PLATFORM_PLUGINS: &[&str] = _;
Platform guests installed into $BOOKCLERK_FILES_DIR/plugins/; always checked.
pub const OPTIONAL_PLUGINS: &[&str] = _;
Optional first-party guests staged under $BOOKCLERK_PLUGIN_ARTIFACTS.
pub const EXAMPLE_PLUGINS: &[&str] = _;
Reference Echo guests staged under $BOOKCLERK_PLUGIN_ARTIFACTS.
pub const STAGED_PLUGINS_ENV: &str = "BOOKCLERK_STAGED_PLUGINS";
Environment variable selecting a subset of staged guests to check.
pub const REQUIRE_STAGED_ENV: &str = "BOOKCLERK_REQUIRE_STAGED_PLUGINS";
Environment variable turning missing staging prerequisites into failures.
Generated from crates/bookclerk-plugin-e2e at main · View as Markdown