Testing your plugin
Integration-test a plugin against a real Nextly instance with createTestNextly — and why you should add at least one real-database test.
createTestNextly (from @nextlyhq/plugin-sdk/testing) boots a real Nextly on
in-memory SQLite and runs your plugin's full lifecycle — contributes → setup → init —
so you can integration-test behaviour, not mocks. It's @public.
Basic shape
import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
import { myPlugin } from "../src";
const t = await createTestNextly({
plugins: [myPlugin()],
collections: myPlugin().contributes.collections, // register the plugin's schema
});
// drive the instance:
await t.nextly /* CRUD facade */;
t.hooks; // assert hook registration/execution
t.events; // assert emissions (call settle() to flush best-effort events)
t.adapter; // raw DB inspection
await t.destroy(); // runs your plugin's destroy() + resets singletonsAlways await t.destroy() in teardown — it exercises your destroy() (catching
leaked subscriptions) and resets the global registries so tests don't bleed into each
other.
Files the instance generates, such as the migration a Builder save writes, a file
uploaded to local disk (with its .gitignore entry) and the migration log, go into a
temporary folder of its own (t.basePath), which destroy() removes, so a test run
leaves nothing in your package. Pass basePath to choose the folder instead; the
instance then writes there and leaves it in place.
A plugin that declares raw SQL
An app lists the plugins it allows raw SQL in db.rawSqlPlugins, and the boot
refuses a plugin that declares capabilities.db.rawSql without being listed.
createTestNextly has no nextly.config.ts, so it takes the listing as its
pluginConsent option (@experimental):
import { definePlugin } from "@nextlyhq/plugin-sdk";
import { createTestNextly } from "@nextlyhq/plugin-sdk/testing";
const reportsPlugin = definePlugin({
name: "@acme/nextly-reports",
version: "1.0.0",
nextly: ">=0.0.2-alpha.67",
capabilities: { db: { rawSql: true } },
});
const t = await createTestNextly({
plugins: [reportsPlugin],
pluginConsent: { rawSql: ["@acme/nextly-reports"] },
});Without it nothing is listed, and the refusal (PLUGIN_RESOLUTION_ERROR,
capability-not-listed) names the option and the value to pass.
What to assert
-
Schema: your contributed collections/fields exist;
extendadded the fields it should; CRUD permissions were seeded. -
Behaviour: hooks fire and can modify/abort; events emit after commit (use
await t.events.settle()before asserting, since events are best-effort). -
Routes & permissions: a route requires the right permission;
{ as: "system" }vs{ as: "user" }calls behave as expected. Assert that every route declares what reaching it takes, so an undeclared one fails your suite rather than every request:import { undeclaredPluginRoutes } from "@nextlyhq/plugin-sdk/testing"; import { expect, it } from "vitest"; import { myPlugin } from "../src"; it("declares what every route takes", () => { expect(undeclaredPluginRoutes(myPlugin())).toEqual([]); }); -
Uninstall: removing the plugin orphans its tables and
nextly prunewould drop onlyplugin:*provenance (see Schema & data lifecycle).
Add at least one real-database test
The in-memory SQLite harness is fast and great for logic, but SQLite does not enforce several dialect-specific constraints that Postgres and MySQL do (column length, stricter typing, some FK behaviours). A bug can pass every SQLite test and still fail on a real database.
Real-world example: a
varchar(20)column held provenance values likeplugin:@acme/nextly-plugin-name(well over 20 chars). SQLite silently accepted it; Postgres rejected it with22001 value too long. It passed CI and broke on first deploy.
So: for anything that writes typed or system-metadata columns, add at least one
Postgres-backed integration test in addition to the SQLite ones. Point
createTestNextly's adapter at a throwaway Postgres database (or run the test in CI
against a Postgres service container) and exercise the write path on a clean schema —
a polluted/drifted dev database can mask migration-diff bugs.
Also use realistic scoped plugin names in fixtures (@acme/nextly-plugin-thing, not
@t/x) so length/constraint problems surface.
See also: Author guide · Schema & data lifecycle.