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

package/README.md

@@ -19,8 +19,10 @@ Register three suites against a disposable test database:
   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, the Release Catalog contract and
-  Insights through the admin and client HTTP APIs of `createHotUpdater`.
+- `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:
 
@@ -31,6 +33,7 @@ import {
   createInsightsModel,
   insights,
 } from "@hot-updater/server/plugins/insights";
+import { insightsTestSuite } from "@hot-updater/server/plugins/insights/testing";
 import {
   setupDatabaseTestSuite,
   startHttpTestServer,
@@ -57,10 +60,15 @@ setupDatabaseTestSuite({
         clientAccess: "public",
       }).handlers,
     ),
-  createInsightsModel: (database) =>
-    createInsightsModel(
-      createDatabasePluginApis(database, [insights()]).insights,
-    ),
+  // The server above runs insights(), so its suite runs too.
+  plugins: [
+    insightsTestSuite({
+      createModel: (database) =>
+        createInsightsModel(
+          createDatabasePluginApis(database, [insights()]).insights,
+        ),
+    }),
+  ],
 });
 ```
 

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,11 +279,13 @@ 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: {
@@ -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 };