# Test sandboxed plugins

> Run plugin hooks and routes through EmDash's production sandbox boundary in Vitest.

Source: https://emdashcmseverything.com/official-docs/plugins/creating-plugins/testing/

`@emdash-cms/plugin-test` builds a sandboxed plugin and runs its tests through a local Worker Loader binding. Tests use EmDash's production Cloudflare sandbox wrapper and `PluginBridge`, with local D1 and Worker Loader bindings supplied by `@cloudflare/vitest-plugin`.

Choose the host that matches the behavior under test:

- `createPluginTestHost()` invokes a hook or route directly across the sandbox transport. Use it for serialization, capability enforcement, plugin storage, and route-handler logic.
- `createPluginRuntimeTestHost()` runs real EmDash content, plugin activation, media, comment, scheduled-task, and plugin-route actions. Use it when the test must prove that a host action reaches the plugin.

Projects created by `emdash-plugin init` include this setup. Existing plugin projects can install the test host as a development dependency:

```sh
pnpm add -D @emdash-cms/plugin-test vitest
```

If the project restricts dependency build scripts, allow `workerd` to install its platform binary. The generated pnpm policy includes this entry:

```yaml title="pnpm-workspace.yaml"
allowBuilds:
  workerd: true
```

## Configure Vitest

Add the EmDash test plugin to the project's Vitest configuration:

```ts title="vitest.config.ts"
import { emdashPluginTest } from "@emdash-cms/plugin-test/config";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [emdashPluginTest()],
});
```

`emdashPluginTest()` runs the plugin build before Vitest starts. It reads the generated runtime and manifest, creates an isolated D1 database and Worker Loader binding, and exports the same `PluginBridge` used by Cloudflare deployments. Pass `{ dir: "./packages/gallery" }` when the Vitest configuration lives outside the plugin directory.

Test builds use temporary output directories that are removed after the runtime and manifest are loaded. Testing leaves any existing `dist/` directory unchanged. Run `emdash-plugin build` separately to generate build artifacts.

## Test sandbox transport

Create and dispose a host inside each test. Disposal stops the plugin and resets its test bindings:

```ts title="tests/plugin.test.ts"
import { afterEach, describe, expect, it } from "vitest";

import { createPluginTestHost, type PluginTestHost } from "@emdash-cms/plugin-test";

let host: PluginTestHost | undefined;

afterEach(async () => {
	await host?.dispose();
	host = undefined;
});

describe("health route", () => {
	it("identifies the plugin", async () => {
		host = await createPluginTestHost();

		await expect(host.invokeRoute("health")).resolves.toEqual({
			ok: true,
			plugin: "save-log",
		});
	});
});
```

`invokeRoute()` accepts an input value and optional request properties. The default request is a `POST` to the plugin's route with empty headers and request metadata.

Direct invocation does not exercise EmDash route authentication, permission, token-scope, cross-site request forgery (CSRF), or cache policy. Use `host.actions.routes.request()` on the runtime host for those checks.

## Test hooks and storage

Invoke hooks with the event shape they receive from EmDash. The storage and KV readers inspect the state written through the bridge:

```ts title="tests/plugin.test.ts"
host = await createPluginTestHost();

await host.invokeHook("content:afterSave", {
	collection: "posts",
	content: { id: "post-1", title: "First post" },
});

const events = await host.storage("events").list();
expect(events).toHaveLength(1);
expect(events[0]?.data).toMatchObject({
	collection: "posts",
	contentId: "post-1",
});
```

Storage calls still enforce the collections declared in `emdash-plugin.jsonc`. Content, media, user, email, and network calls still enforce the plugin's declared capabilities and allowed hosts.

## Seed content

Create a collection and seed entries before invoking a route or hook that reads site content:

```ts title="tests/plugin.test.ts"
host = await createPluginTestHost();
await host.createCollection({
	slug: "posts",
	label: "Posts",
	fields: [{ slug: "title", label: "Title", type: "string" }],
});
await host.seedContent("posts", [{ title: "First" }, { title: "Second" }]);

await expect(host.invokeRoute("post-count")).resolves.toEqual({ count: 2 });
```

The collection and entries use the real EmDash schema registry and content repository against D1.

## Test host actions

Create a runtime host when the result depends on EmDash orchestration. Fixtures write initial state without firing plugin hooks. Actions call the production runtime or handler boundary, and inspectors read observable state without invoking plugin code.

`createPluginRuntimeTestHost()` runs `plugin:install` and then `plugin:activate` before resolving, before the test adds fixtures. Keep lifecycle setup independent of fixtures created afterward. A failure in the plugin's own lifecycle hook disables the plugin in the host, so subsequent actions will not invoke its hooks. Check `host.inspect.pluginState()` when diagnosing missing hook effects.

Tasks scheduled during activation are visible through `host.inspect.scheduledTasks()` without calling `host.actions.plugin.activate()`. `host.restart()` preserves recorded plugin state, so successfully completed initial lifecycle hooks do not run again. An explicit `host.actions.plugin.activate()` runs another activation.

For a plugin whose `content:beforeSave` hook appends ` [checked]` to the title, the following test proves that a content save reaches the hook:

```ts title="tests/plugin.test.ts"
import { afterEach, describe, expect, it } from "vitest";

import {
	createPluginRuntimeTestHost,
	type PluginRuntimeTestHost,
} from "@emdash-cms/plugin-test";

let host: PluginRuntimeTestHost | undefined;

afterEach(async () => {
	await host?.dispose();
	host = undefined;
});

describe("content save", () => {
	it("applies the plugin hook", async () => {
		host = await createPluginRuntimeTestHost();
		await host.fixtures.collection({
			slug: "posts",
			label: "Posts",
			fields: [{ slug: "title", label: "Title", type: "string" }],
		});

		const result = await host.actions.content.create("posts", {
			data: { title: "First post" },
		});

		expect(result).toMatchObject({
			success: true,
			data: { item: { data: { title: "First post [checked]" } } },
		});
	});
});
```

The runtime host groups its API by boundary:

- `transport` directly invokes the isolate for transport-level checks.
- `admin` loads validated Block Kit pages and widgets, submits forms, and invokes actions through the production route boundary with host-attested locale context.
- `fixtures` creates site, collection, field, user, byline, taxonomy, content, redirect, binary media, and plugin state without firing hooks.
- `actions` runs content state changes, plugin activation and deactivation, generated settings updates, media uploads, public comment submission, comment moderation, and policy-checked plugin routes.
- `inspect` reads content, redirects, byline credits, taxonomy assignments, plugin storage, KV, raw persisted setting envelopes, plugin state, scheduled tasks, publication-policy rejections, media metadata and bytes, comments, and captured email. Use `inspect.scheduledPolicyRejections()` to verify that a scheduler veto was persisted for administrator attention.
- `scheduled` controls the effective time for cron tasks and scheduled publishing, then runs one production maintenance batch.
- `http` queues external responses and captures the requests that a plugin sends through `ctx.http.fetch()`.
- `restart()` replaces the runtime and isolate while retaining D1, plugin storage, media storage, and plugin state.

Call `await host.waitForDeferredTasks()` after an action to finish deferred runtime work, such as `content:afterPublish` hooks, before inspecting its effects or starting another action on the same entry. Same-entry actions can otherwise fail with `CONTENT_ACTION_REENTRANT` while an after-hook is running.

The method also waits for deferred work queued by those tasks. It does not run future scheduled tasks or wait for arbitrary unawaited plugin promises. Continue to await plugin operations before returning from a route or hook.

Call `dispose()` after each test. Disposal terminates the isolate and resets all bindings, so a later test cannot observe the previous host's database or media.

Use the settings action and raw inspector to prove that a generated settings save reaches the production handler and does not persist plaintext:

```ts title="tests/plugin.test.ts"
const result = await host.actions.plugin.updateSettings({ apiKey: "test-secret" });
expect(result).toMatchObject({ success: true, data: { secretsSet: { apiKey: true } } });

const stored = await host.inspect.settings.raw("apiKey");
expect(stored).toMatchObject({ v: 1, kid: expect.any(String) });
expect(JSON.stringify(stored)).not.toContain("test-secret");
```

Set `EMDASH_ENCRYPTION_KEY` in the test process before creating the host. The raw inspector deliberately returns the persisted envelope; use the plugin's route or hook to verify the decrypted `ctx.settings` value.

Use `host.fixtures.redirect()` to establish redirect state without invoking the plugin. Use `host.inspect.redirects()` to assert the persisted rules after the plugin calls `ctx.redirects`.

Use a binary fixture to test `media:bytes:read` through the runtime's storage adapter and Worker Loader bridge. The following fixture deliberately reports a smaller database size so the test can prove that the stream limit is authoritative:

```ts title="tests/plugin.test.ts"
const fixture = await host.fixtures.media({
	filename: "sample.bin",
	mimeType: "application/octet-stream",
	bytes: new Uint8Array([0, 255, 17, 42]),
	reportedSize: 1,
	contentHash: "sha1:sample",
});

await expect(host.inspect.mediaBytes(fixture.id)).resolves.toEqual(
	new Uint8Array([0, 255, 17, 42]),
);
```

Use `createPluginRuntimeTestHost()` for translation creation. The direct transport host does not run the runtime-owned translation lifecycle that copies shared fields and attribution.

Queue a binary response before invoking the plugin route that fetches it:

```ts title="tests/http.test.ts"
const admin = await host.fixtures.user({
	email: "plugin-test@example.com",
	role: "admin",
});

await host.http.respond(
	"https://api.example.com/report",
	new Response(new Uint8Array([0, 255, 195, 40]), {
		headers: { "content-type": "application/octet-stream" },
	}),
);

await host.actions.routes.request("import-report", {
	user: admin,
	headers: { "X-EmDash-Request": "1" },
});

expect(host.http.requests()).toContainEqual(
	expect.objectContaining({ url: "https://api.example.com/report" }),
);
```

`respond()` consumes and stores the response bytes immediately, so the later Worker Loader request receives a response created in its own request context. Queue another response for each expected call to the same URL. `clear()` removes queued responses and captured requests.

Pass `rawBody` to test a declared `text`, `bytes`, or `form-data` request through the production
route parser:

```ts title="tests/routes.test.ts"
const form = new FormData();
form.append("title", "Quarterly report");
form.append("attachment", new File([new Uint8Array([0, 255])], "report.bin"));

const admin = await host.fixtures.user({
	email: "plugin-test@example.com",
	role: "admin",
});

const response = await host.actions.routes.request("import", {
	method: "POST",
	user: admin,
	headers: { "X-EmDash-Request": "1" },
	rawBody: form,
});

expect(response.ok).toBe(true);
```

`rawBody` accepts any `BodyInit`, including strings, `Uint8Array`, `URLSearchParams`, and
`FormData`. The request body is buffered. Use `body` for the legacy JSON path; the test host
serializes it and sets `Content-Type: application/json`.

The runtime host exposes shipped operations only. Capability-specific helpers for translations, publication policy, Block Kit interactions, taxonomies, redirects, expanded comment administration, media bytes, and encrypted settings belong to the releases that add those capabilities.

## Test boundaries

The default Vitest configuration uses Worker Loader because it is the fastest production sandbox path for plugin development. EmDash also runs equivalent runtime content and restart journeys against the Node.js workerd runner. Add a separate, opt-in Node/workerd job when a plugin depends on runner-sensitive behavior; the generated project does not run both runners by default.

Neither host renders the EmDash admin application or reproduces Cloudflare's deployed CPU, memory, and subrequest limits. Use a disposable EmDash site for browser journeys, and verify limit-sensitive behavior on a Cloudflare preview or staging deployment.

For Block Kit handlers, use `host.admin.loadPage()` or `loadWidget()` to exercise the private route, host-attested locale context, response validation, and Worker Loader isolate. Use `admin.act()` and `admin.submit()` for page interactions.

Saved-entry extensions use the production ownership and route-permission boundary. Create the collection, user, and content with fixtures, then call `admin.loadEditorPanel()`, `actEditorPanel()`, `submitEditorPanel()`, or `invokeEditorAction()`. Pass `locale` for the admin UI language and `contentLocale` when selecting a translated entry. These helpers reload the saved entry before invoking the isolate and never send unsaved field values.

The admin helpers do not render React. Use the [Block Playground](https://blocks.emdashcms.com/) or a browser journey to verify Kumo rendering, confirmation dialogs, keyboard operation, and right-to-left layout.
