@hot-updater/test-utils 1.0.0-rc.15 → 1.0.0-rc.17

package/README.md

@@ -1,64 +1,94 @@
 # @hot-updater/test-utils
 
-Shared Vitest conformance tests for custom Hot Updater database providers and
-HTTP servers. Official providers and example servers run these same scenarios.
+Vitest suites for Hot Updater database adapters, providers and servers. The
+official providers and example servers run these same suites.
 
 ```bash
 pnpm add -D @hot-updater/test-utils @hot-updater/server vitest
 ```
 
-Connect your database lifecycle and the real server:
+## Database adapters and providers
+
+Register three suites against a disposable test database:
+
+- `setupDatabaseAdapterConformanceSuite` runs the storage adapter contract case
+  by case: value round-trips, ordering, guards, all-or-nothing writes, unique
+  and multi-valued indexes, paging under capped native pages, and concurrent
+  writers.
+- `setupReadBudgetTestSuite` checks what each read of core and the built-in
+  plugins costs at the adapter, using `createMeasuredDatabase` from
+  `@hot-updater/server/db`. `postgresRowsExamined` and `mysqlRowsExamined` also
+  count the rows a SQL database examined.
+- `setupDatabaseTestSuite` runs core, Bundles and the Release Catalog contract
+  through the admin and client HTTP APIs of `createHotUpdater`, then the suites
+  of the server plugins listed in `plugins`, such as the Insights plugin's
+  `insightsTestSuite()` from `@hot-updater/server/plugins/insights/testing`.
+
+Connect your database's lifecycle and the real server:
 
 ```ts
 import { createHotUpdater } from "@hot-updater/server";
+import { createDatabasePluginApis } from "@hot-updater/server/db";
+import {
+  createInsightsModel,
+  insights,
+} from "@hot-updater/server/plugins/insights";
+import { insightsTestSuite } from "@hot-updater/server/plugins/insights/testing";
 import {
-  setupDatabasePluginTestSuite,
+  setupDatabaseTestSuite,
   startHttpTestServer,
 } from "@hot-updater/test-utils";
-import { myDatabase } from "./myDatabase";
-import { db, migrateDatabase, resetDatabase } from "./testDatabase";
 
-setupDatabasePluginTestSuite({
+import { migrateMyDatabase, myDatabase } from "./myDatabase";
+import { resetMyDatabase } from "./testDatabase";
+
+const config = { connectionString: process.env.TEST_DATABASE_URL };
+
+setupDatabaseTestSuite({
   name: "my database",
-  createPlugin: () => myDatabase({ db }),
-  migrate: () => migrateDatabase(db),
-  reset: () => resetDatabase(db),
-  dispose: async (plugin) => { await plugin.dispose?.(); },
-  createHttpClient: (options) => startHttpTestServer(
-    createHotUpdater({ ...options, clientAccess: { type: "public" } }).handlers,
-  ),
+  migrate: () => migrateMyDatabase(config),
+  createDatabase: () => myDatabase(config),
+  reset: () => resetMyDatabase(config),
+  dispose: async (database) => {
+    await database.dispose?.();
+  },
+  createHttpClient: (options) =>
+    startHttpTestServer(
+      createHotUpdater({
+        ...options,
+        plugins: [insights()],
+        clientAccess: "public",
+      }).handlers,
+    ),
+  // The server above runs insights(), so its suite runs too.
+  plugins: [
+    insightsTestSuite({
+      createModel: (database) =>
+        createInsightsModel(
+          createDatabasePluginApis(database, [insights()]).insights,
+        ),
+    }),
+  ],
 });
 ```
 
-Run the spec with `pnpm exec vitest run`. Use an isolated test database; reset
-all data before each scenario while retaining its schema and version settings.
-
-Passing the complete suite verifies the DatabasePlugin and Release Catalog
-HTTP contracts for the installed Hot Updater version: model semantics,
-transactions, pagination, relations, Insights, catalog projections and caching,
-and artifact responses. Lifecycle scenarios feed those HTTP catalogs into the
-production client selector and advance the simulated device after checking the
-selected artifact: built-in → OTA A → OTA B → rollback A → built-in. They also
-exercise deleted Releases, the native minimum bundle, compatibility, cohort
-changes, and crash history. Native download, activation, and restart remain
-device E2E responsibilities.
-
-The HTTP scenarios use real `fetch` requests on Node,
-including independent Release/Catalog expectations and competing conditional
-writes. Run the entire suite against your provider's actual test backend without
-skipping scenarios or replacing model methods with mocks.
+`migrate` creates the tables and schema settings once. `reset` empties every
+data table before each test and keeps the settings rows. Run the suites
+against your actual backend without skipping cases or mocking the database.
+The Release Catalog scenarios feed each catalog they receive to the production
+client selector and keep a simulated device's state across updates, rollbacks
+and the built-in fallback. Native download, activation and restart remain
+device end-to-end responsibilities.
 
-The repository also runs the public suite against deliberately broken providers
-to check that contract violations fail. This is a versioned compatibility gate;
-passing is evidence for the exercised contracts, not a proof of every possible
-execution or deployment condition.
-Add provider-specific migration, concurrency, storage, and deployment tests
-where those need separate verification.
+## Plugins and servers
 
-Use `setupReleaseCatalogTestSuite` with `createHttpTestClient` to test an existing
-server by URL. Use `createHandlerHttpTestClient` for a Workers Vitest pool.
-Server processes can import `createReleaseCatalogTestStorage` from
-`@hot-updater/test-utils/node` to install the suite's storage fixtures.
+- `createPluginTestHarness` runs one server plugin the way `createHotUpdater`
+  does, on a memory adapter by default, and measures what each API call reads.
+- `setupReleaseCatalogTestSuite` with `createHttpTestClient` tests a running
+  server by URL. Use `createHandlerHttpTestClient` inside a Workers Vitest pool.
+- Server processes can import `createReleaseCatalogTestStorage` from
+  `@hot-updater/test-utils/node` to install the suites' storage fixtures.
 
-See the [custom database guide](https://hot-updater.dev/docs/database-plugins/custom-database)
-for the full setup and contract boundaries.
+See the
+[custom database adapter guide](https://hot-updater.dev/docs/database-plugins/custom-database)
+for the adapter contract and complete specs for each suite.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { ArtifactInfo, Bundle, ReleaseCatalog } from "@hot-updater/core";
 import { DatabaseAdapter, DatabaseReadCount, PhysicalTable } from "@hot-updater/plugin-core/internal";
-import { BundleRow, ChannelRow, DeployReleasePolicy, EngineDatabase, HotUpdaterCoreApi, InsightsModel, ReleaseRow, StoragePlugin } from "@hot-updater/plugin-core";
+import { AggregateBatching, BundleRow, ChannelRow, DeployReleasePolicy, EngineDatabase, HotUpdaterCoreApi, ReleaseRow, StoragePlugin } from "@hot-updater/plugin-core";
 //#region src/httpTestClient.d.ts
 type HttpTestRequestInit = NonNullable<ConstructorParameters<typeof Request>[1]>;
 type HttpTestRequest = (path: string, init?: HttpTestRequestInit) => Promise<Response>;
@@ -71,37 +71,6 @@ declare const setupCoreAdminTestSuite: (options: {
   readonly getClient: () => HttpTestClient;
 }) => void;
 //#endregion
-//#region src/setupInsightsHttpTestSuite.d.ts
-/**
- * The Insights plugin's routes on a database: a client reports an event, and
- * the admin routes read it back. The server must run `insights()`.
- */
-declare const setupInsightsHttpTestSuite: (options: {
-  readonly getClient: () => HttpTestClient;
-}) => void;
-//#endregion
-//#region src/databaseTestRunner.d.ts
-type Awaitable<T> = Promise<T> | T;
-/** How a suite gets a provider's database, and gives it back. */
-type DatabaseTestLifecycle<TDatabase> = {
-  readonly name: string;
-  /** Creates the provider's tables and settings rows, before `createDatabase`. */
-  readonly migrate: () => Awaitable<void>;
-  /** The provider's database, as its factory returns it. */
-  readonly createDatabase: () => Awaitable<TDatabase>;
-  /** Empties every table between tests. */
-  readonly reset: (database: TDatabase) => Awaitable<void>;
-  readonly dispose: (database: TDatabase) => Awaitable<void>;
-};
-//#endregion
-//#region src/setupInsightsModelTestSuite.d.ts
-/**
- * The Insights report contract on one database: pass the Insights plugin's
- * model over it, `createInsightsModel(createDatabasePluginApis(database,
- * [insights()]).insights)`, as `createDatabase`.
- */
-declare const setupInsightsModelTestSuite: (lifecycle: DatabaseTestLifecycle<InsightsModel>) => void;
-//#endregion
 //#region src/setupSemverSatisfiesTestSuite.d.ts
 /**
  *
@@ -124,29 +93,50 @@ declare const setupSemverSatisfiesTestSuite: ({ semverSatisfies }: {
   semverSatisfies: (targetAppVersion: string, currentVersion: string) => Promise<boolean> | boolean;
 }) => void;
 //#endregion
+//#region src/databaseTestRunner.d.ts
+type Awaitable<T> = Promise<T> | T;
+/** How a suite gets a provider's database, and gives it back. */
+type DatabaseTestLifecycle<TDatabase> = {
+  readonly name: string;
+  /** Creates the provider's tables and settings rows, before `createDatabase`. */
+  readonly migrate: () => Awaitable<void>;
+  /** The provider's database, as its factory returns it. */
+  readonly createDatabase: () => Awaitable<TDatabase>;
+  /** Empties every table between tests. */
+  readonly reset: (database: TDatabase) => Awaitable<void>;
+  readonly dispose: (database: TDatabase) => Awaitable<void>;
+};
+//#endregion
 //#region src/setupDatabaseTestSuite.d.ts
+/**
+ * A server plugin's tests on a provider's database, such as the Insights
+ * plugin's `insightsTestSuite()`. The provider's HTTP server must run the
+ * plugin.
+ */
+interface DatabasePluginTestSuite<TDatabase = unknown> {
+  readonly name: string;
+  register(context: {
+    readonly getClient: () => HttpTestClient;
+    readonly getDatabase: () => TDatabase;
+  }): void;
+}
 type DatabaseTestSuiteOptions<TDatabase extends EngineDatabase = EngineDatabase> = DatabaseTestLifecycle<TDatabase> & {
   /**
-   * Serves the handlers of `createHotUpdater({ database, storage, plugins:
-   * [insights()], clientAccess: "public" })` over HTTP: in process, or in the
-   * runtime the provider deploys to.
+   * Serves the handlers of `createHotUpdater({ database, storage, plugins,
+   * clientAccess: "public" })` over HTTP, in process or in the runtime the
+   * provider deploys to, with the plugins whose suites `plugins` lists.
    */
   readonly createHttpClient: (options: {
     readonly database: TDatabase;
     readonly storage: readonly StoragePlugin[];
   }) => HttpTestServer | Promise<HttpTestServer>;
-  /**
-   * The Insights plugin's model on the database, to run the Insights report
-   * contract on its tables: `(database) => createInsightsModel(
-   * createDatabasePluginApis(database, [insights()]).insights)`.
-   */
-  readonly createInsightsModel?: (database: TDatabase) => InsightsModel;
+  /** The suites of the server plugins the provider opts in to test. */
+  readonly plugins?: readonly DatabasePluginTestSuite<TDatabase>[];
 };
 /**
  * A provider's database under Hot Updater's server: core's operations, the
- * Release Catalog contract, bundles, and Insights, all through HTTP, on the
- * tables the provider's tooling creates; with `createInsightsModel`, also the
- * Insights report contract in process.
+ * Release Catalog contract, and bundles, all through HTTP, on the tables the
+ * provider's tooling creates, then each opted-in plugin's suite.
  */
 declare const setupDatabaseTestSuite: <TDatabase extends EngineDatabase>(options: DatabaseTestSuiteOptions<TDatabase>) => void;
 //#endregion
@@ -167,9 +157,17 @@ interface DatabaseAdapterConformanceOptions {
   readonly maxOps?: number;
   /** Concurrent writers in the contention cases (default 32). */
   readonly writers?: number;
+  /**
+   * How the backend deletes rows past a table's retention: `prune` (the
+   * default) through the adapter, or `ttl`, natively on every item, with no
+   * `prune` on the adapter.
+   */
+  readonly retention?: "prune" | "ttl";
 }
 declare const conformanceItems: PhysicalTable;
 declare const conformanceCounters: PhysicalTable;
+/** Rows expire 1,000 ms after `at`; a null `at` never expires. */
+declare const conformanceExpiring: PhysicalTable;
 /**
  * The storage-adapter conformance contract (PRD S3 and S4 cases). Every
  * adapter runs it through `verifyAdapter`, which also checks each read and
@@ -281,16 +279,18 @@ interface ReadBudgetServer {
     readonly now: () => number;
     readonly storage: ReadBudgetStorage;
   }): ReadBudgetDatabase;
-  /** `builtInSchema` from `@hot-updater/server/database`: the tables to create. */
-  readonly builtInSchema: {
-    readonly tables: readonly PhysicalTable[];
+  /** `toolingTargetOf` from `@hot-updater/server/database`: core's and the plugins' tables to create. */
+  toolingTargetOf(plugins: readonly unknown[]): {
+    readonly schema: {
+      readonly tables: readonly PhysicalTable[];
+    };
   };
-  /** `[insights(), apiKeys()]`, the built-in plugins whose reads have budgets. */
+  /** `[insights(), apiKeys()]`, the plugins whose reads have budgets. */
   readonly plugins: readonly unknown[];
   /** `targetBaseCandidateKey` from `@hot-updater/server/db`. */
   targetBaseCandidateKey(target: {
-    readonly channelId: string;
-    readonly platform: string;
+    readonly channel: string;
+    readonly platform: "ios" | "android";
     readonly fingerprintHash: string | null;
     readonly appVersion: string | null;
   }): string | null;
@@ -325,6 +325,51 @@ interface ReadBudgetSuiteOptions {
  */
 declare const setupReadBudgetTestSuite: (options: ReadBudgetSuiteOptions) => void;
 //#endregion
+//#region src/setupAggregateBatchingTestSuite.d.ts
+interface Module {
+  readonly id: string;
+  readonly schema: object;
+}
+/**
+ * What the suite takes from `@hot-updater/server/database`; pass that
+ * module, which keeps test-utils free of a dependency on the server.
+ */
+interface AggregateBatchingEngine {
+  resolveSchema(modules: readonly Module[]): {
+    readonly tables: readonly PhysicalTable[];
+  };
+  readonly aggregateBatchingModule: Module;
+  createDatabaseEngine(options: {
+    readonly adapter: DatabaseAdapter;
+    readonly schema: never;
+    readonly batching?: AggregateBatching;
+    readonly retry?: {
+      readonly attempts?: number;
+    };
+  }): {
+    database(module: Module): unknown;
+    flush(): Promise<void>;
+  };
+}
+interface AggregateBatchingSuiteOptions {
+  readonly name: string;
+  /** `import * as engine from "@hot-updater/server/database"`. */
+  readonly engine: AggregateBatchingEngine;
+  /** Returns an adapter over an empty store; each case calls it once. */
+  readonly createAdapter: () => Promise<{
+    readonly adapter: DatabaseAdapter;
+    readonly cleanup?: () => Promise<void>;
+  }>;
+  /** Aggregate rows one transaction changes in the too-large case: more than one write takes. */
+  readonly oversizedRows: number;
+}
+/**
+ * Aggregates declared `batched` on a key-value store: log rows the store
+ * writes with each transaction and a compaction merges once, and a memory
+ * buffer, read back exactly as transactional writes read.
+ */
+declare const setupAggregateBatchingTestSuite: ({ name, engine, createAdapter, oversizedRows }: AggregateBatchingSuiteOptions) => void;
+//#endregion
 //#region src/runContentionHarness.d.ts
 /** Delays every adapter call by `ms`, like a round trip to a remote database. */
 declare const withAdapterLatency: (adapter: DatabaseAdapter, ms: number) => DatabaseAdapter;
@@ -385,6 +430,8 @@ interface PluginTestEngine {
 interface HarnessPlugin {
   readonly id: string;
   readonly schema: object;
+  /** `false` keeps the declared table names, as `createHotUpdater` does. */
+  readonly namespace?: false;
   init(context: never): {
     readonly api: unknown;
   };
@@ -449,4 +496,4 @@ declare const RELEASE_CATALOG_STORAGE_FIXTURES: Readonly<Record<string, string>>
 /** Storage boundary shared by provider and separately spawned server tests. */
 declare const createReleaseCatalogTestStorage: () => StoragePlugin;
 //#endregion
-export { AdminApiTestClient, ContentionOptions, ContentionReport, DatabaseAdapterConformanceContext, DatabaseAdapterConformanceOptions, type DatabaseTestLifecycle, DatabaseTestSuiteOptions, HttpTestClient, HttpTestHandlers, HttpTestRequest, HttpTestRequestInit, HttpTestServer, PluginTestEngine, PluginTestHarnessOptions, RELEASE_CATALOG_DOWNLOAD_HASH, RELEASE_CATALOG_MANIFEST_URIS, RELEASE_CATALOG_STORAGE_FIXTURES, ReadBudgetAdapterContext, ReadBudgetDatabase, ReadBudgetServer, ReadBudgetStorage, ReadBudgetSuiteOptions, RowsExamined, SqlExecutorLike, SqlQuery, SqlStatementLike, conformanceCounters, conformanceItems, createAdminApiTestClient, createHandlerHttpTestClient, createHttpTestClient, createPluginTestHarness, createReleaseCatalogTestStorage, jsonRequest, mysqlRowsExamined, postgresRowsExamined, releaseCatalogArtifact, releaseCatalogDownloadUrl, runContentionHarness, setupBundleMethodsTestSuite, setupCoreAdminTestSuite, setupDatabaseAdapterConformanceSuite, setupDatabaseTestSuite, setupInsightsHttpTestSuite, setupInsightsModelTestSuite, setupReadBudgetTestSuite, setupReleaseCatalogTestSuite, setupSemverSatisfiesTestSuite, startHttpTestServer, toDeployBundle, withAdapterLatency };
+export { AdminApiTestClient, AggregateBatchingEngine, AggregateBatchingSuiteOptions, ContentionOptions, ContentionReport, DatabaseAdapterConformanceContext, DatabaseAdapterConformanceOptions, DatabasePluginTestSuite, type DatabaseTestLifecycle, DatabaseTestSuiteOptions, HttpTestClient, HttpTestHandlers, HttpTestRequest, HttpTestRequestInit, HttpTestServer, PluginTestEngine, PluginTestHarnessOptions, RELEASE_CATALOG_DOWNLOAD_HASH, RELEASE_CATALOG_MANIFEST_URIS, RELEASE_CATALOG_STORAGE_FIXTURES, ReadBudgetAdapterContext, ReadBudgetDatabase, ReadBudgetServer, ReadBudgetStorage, ReadBudgetSuiteOptions, RowsExamined, SqlExecutorLike, SqlQuery, SqlStatementLike, conformanceCounters, conformanceExpiring, conformanceItems, createAdminApiTestClient, createHandlerHttpTestClient, createHttpTestClient, createPluginTestHarness, createReleaseCatalogTestStorage, jsonRequest, mysqlRowsExamined, postgresRowsExamined, releaseCatalogArtifact, releaseCatalogDownloadUrl, runContentionHarness, setupAggregateBatchingTestSuite, setupBundleMethodsTestSuite, setupCoreAdminTestSuite, setupDatabaseAdapterConformanceSuite, setupDatabaseTestSuite, setupReadBudgetTestSuite, setupReleaseCatalogTestSuite, setupSemverSatisfiesTestSuite, startHttpTestServer, toDeployBundle, withAdapterLatency };