Test activation, restart, and persisted state

Test lifecycle transitions deliberately. Reload, disable, safe mode, and full restart remove different runtime state while preserving different durable state.

Use an isolated Phials Home so you can inspect first-run behavior and reset the profile without affecting normal files or plugin data.

Add a small lifecycle probe

During development, make activation and deactivation observable:

export default function createPlugin(): PhialsPlugin {
  let api: PluginAPI | null = null;

  return {
    id: "acme.lifecycle-probe",
    name: "Lifecycle probe",
    version: "1.0.0",

    onActivate(pluginApi) {
      api = pluginApi;
      api.notify.info("Lifecycle probe activated");
    },

    onDeactivate() {
      api = null;
    },

    providers: [],
  };
}

Pair the notification with a representative capability. An activation notification proves the hook ran; it does not prove every provider, surface, or persisted value works.

Test enable and disable

From Settings → Plugins → Community plugins → Installed:

1. Enable the plugin.
2. Confirm one activation and one copy of each capability.
3. Open or configure representative plugin state.
4. Disable the plugin.
5. Confirm onDeactivate cleanup and that capabilities disappear.
6. Enable it again.
7. Confirm durable state returns without duplicate subscriptions or UI.

Disable retains the plugin’s release files and durable user data. It removes active capabilities and runtime resources.

Safe mode is broader: turning it on deactivates all enabled community plugins in that Phials Home without changing their durable enabled preference. Turning safe mode off reactivates eligible plugins, but does not silently bypass permission review.

Test reload

With the plugin enabled:

1. Create known transient and durable values.
2. Build, validate, and install a visibly changed release.
3. Choose Reload.
4. Confirm one deactivation followed by one activation of the new module.
5. Confirm onBeforeReload to onAfterReload handoff where implemented.
6. Confirm settings, storage, and database values remain.
7. Confirm old capabilities, listeners, styles, and in-memory objects are gone.

Then install one intentionally invalid development build and verify reload reports the failure and restores the prior activated release. Return immediately to a valid build.

Test a full restart

With the plugin enabled and permission-approved:

1. Record the active plugin version and representative state.
2. Quit Phials completely.
3. Confirm no Phials process remains.
4. Relaunch with the same PHIALS_HOME.
5. Confirm the plugin is still enabled, loads once, and activates once.
6. Confirm durable state and host-restored instance state.
7. Confirm reload-only handoff and ordinary module variables are absent.

Repeat with the plugin disabled. It should remain installed and disabled after restart, and no capability should activate.

Repeat after adding a manifest permission. The durable enabled preference should remain selected, but the plugin must stay deactivated until the changed permission set is reviewed.

Use the persistence matrix

The uninstall confirmation can instead delete plugin settings and data. Test that option only in an isolated Phials Home with disposable fixtures.

See Choose between settings, storage, and a database and Manage instances and persisted state.

Verify persistence by identity

All durable plugin state is namespaced by the plugin ID. A changed ID creates a different plugin and therefore a different settings, storage, database, enablement, and permission identity.

Keep the ID stable during normal development. If a test intentionally changes it:

• expect a second Installed entry
• do not treat missing old settings as data loss
• clean up both development identities explicitly

Changing only the plugin version does not create a new storage namespace.

Test failures at lifecycle boundaries

Exercise at least:

Do not leave intentionally broken artifacts installed after the test.

Record the matrix result

For each release candidate, record:

• Phials version and Plugin API version
• plugin version and artifact checksum or commit
• operating system
• Phials Home used
• tested permissions
• transitions exercised
• expected and observed persistence

This turns “worked after reload” into reproducible evidence.

Troubleshoot

• Fix a plugin that will not load or activate
• Recover plugin settings and data
• Verify permissions and runtime compatibility