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

package/README.md

@@ -1,64 +1,86 @@
 # @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, the Release Catalog contract and
+  Insights through the admin and client HTTP APIs of `createHotUpdater`.
+
+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 {
-  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,
+    ),
+  createInsightsModel: (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

@@ -289,8 +289,8 @@ interface ReadBudgetServer {
   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;

package/dist/index.mjs

@@ -880,6 +880,25 @@ const registerInsightsModelTests = (state) => {
 				bundle: [predicate, predicate]
 			}), 1);
 		});
+		it("counts a latest installation once when a from and a to predicate both match it", async () => {
+			const model = state.getDatabase();
+			const moved = createBundleEventRowFixture("9701", 100);
+			await record(model, moved);
+			await expectInsightsIndex(() => model.countLatestEvents({
+				platform: moved.platform,
+				channel: moved.channel,
+				sinceMs: 0,
+				bundle: [{
+					field: "from_bundle_id",
+					value: moved.from_bundle_id,
+					types: [moved.type]
+				}, {
+					field: "to_bundle_id",
+					value: moved.to_bundle_id,
+					types: [moved.type]
+				}]
+			}), 1);
+		});
 		it("returns zero for successful empty scalar queries", async () => {
 			const model = state.getDatabase();
 			await expect(model.countLatestEvents({
@@ -2886,7 +2905,7 @@ const seed = async (database, server) => {
 		nightlyId: (await channel("nightly")).id,
 		/** The auto-patch base key of a new production iOS 1.0.0 bundle. */
 		candidateKey: server.targetBaseCandidateKey({
-			channelId: productionId,
+			channel: "production",
 			platform: "ios",
 			fingerprintHash: null,
 			appVersion: "1.0.0"
@@ -3006,12 +3025,12 @@ const READ_BUDGETS = [
 		returned: (releases) => releases.length
 	}),
 	budget({
-		api: "deploy base candidates: at most maxBaseBundles rows",
+		api: "deploy base candidates: 1 catalog point read",
 		read: ({ core, candidateKey }) => core.findBaseBundleIds(candidateKey, createBundleFixture("107").id, 2),
-		adapter: reads(0, 0, 1, 2),
+		adapter: reads(1, 1, 0, 0),
 		engine: {
 			calls: 1,
-			rows: 2
+			rows: 1
 		},
 		check: (ids) => expect(ids).toEqual(["106", "105"].map((suffix) => createBundleFixture(suffix).id))
 	}),
@@ -3035,17 +3054,47 @@ const READ_BUDGETS = [
 		returned: (channel) => channel === null ? 0 : 1
 	}),
 	budget({
-		api: "list events: limit rows, and one zero-row query per empty day",
+		api: "list events of a dense day: limit rows from one query",
+		read: ({ insights }) => insights.listEvents({
+			filter: { kind: "all" },
+			sinceMs: T0 - DAY,
+			beforeReceivedAtMs: T0,
+			limit: 5
+		}),
+		adapter: reads(0, 0, 1, 5),
+		engine: {
+			calls: 1,
+			rows: 5
+		},
+		returned: (events) => events.length
+	}),
+	budget({
+		api: "list events across a gap: limit rows, one empty day, and one outcome row",
 		read: ({ insights }) => insights.listEvents({
 			filter: bundleEvents,
 			sinceMs: T0,
 			beforeReceivedAtMs: T0 + 3 * DAY,
 			limit: 5
 		}),
-		adapter: reads(0, 0, 3, 5),
+		adapter: reads(1, 7, 4, 6),
 		engine: {
-			calls: 3,
-			rows: 5
+			calls: 4,
+			rows: 6
+		},
+		returned: (events) => events.length + 1
+	}),
+	budget({
+		api: "list events over an empty range: its top day and one outcome read, both empty",
+		read: ({ insights }) => insights.listEvents({
+			filter: { kind: "all" },
+			sinceMs: T0 - 91 * DAY,
+			beforeReceivedAtMs: T0 - DAY,
+			limit: 5
+		}),
+		adapter: reads(0, 0, 2, 0),
+		engine: {
+			calls: 2,
+			rows: 0
 		},
 		returned: (events) => events.length
 	}),
@@ -3179,7 +3228,7 @@ const READ_BUDGETS = [
 			bundle: bundleOf("107"),
 			release: production
 		}]),
-		adapter: (copies) => reads(copies ? 6 : 4, copies ? 9 : 4, 3, 6),
+		adapter: (copies) => reads(copies ? 5 : 3, copies ? 8 : 3, 3, 6),
 		engine: {
 			calls: 6,
 			rows: 9
@@ -3213,7 +3262,7 @@ const READ_BUDGETS = [
 			install_id: "install-2",
 			received_at_ms: T0 + 3 * HOUR
 		})),
-		adapter: reads(5, 19, 0, 0),
+		adapter: reads(5, 21, 0, 0),
 		engine: {
 			calls: 2,
 			rows: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hot-updater/test-utils",
-  "version": "1.0.0-rc.15",
+  "version": "1.0.0-rc.16",
   "type": "module",
   "description": "Test utilities for Hot Updater packages",
   "sideEffects": false,
@@ -38,7 +38,7 @@
     "execa": "*",
     "vitest": "^4.0.0",
     "@hot-updater/core": "^1.0.0-rc.15",
-    "@hot-updater/plugin-core": "^1.0.0-rc.15"
+    "@hot-updater/plugin-core": "^1.0.0-rc.16"
   },
   "devDependencies": {
     "@types/node": "^20",
@@ -47,9 +47,9 @@
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vitest": "4.1.4",
     "workspace-tools": "^0.41.7",
-    "@hot-updater/plugin-core": "1.0.0-rc.15",
-    "@hot-updater/js": "1.0.0-rc.14",
-    "@hot-updater/core": "1.0.0-rc.15"
+    "@hot-updater/core": "1.0.0-rc.15",
+    "@hot-updater/plugin-core": "1.0.0-rc.16",
+    "@hot-updater/js": "1.0.0-rc.14"
   },
   "inlinedDependencies": {
     "@nodelib/fs.scandir": "2.1.5",