@octogee/core-testing 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Squarepoint Consulting LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,61 @@
1
- # Temporary Holding Version
1
+ # @octogee/core-testing
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ```bash
4
+ npm install --save-dev @octogee/core-testing@X.Y.Z
5
+ ```
6
+
7
+ Each octogee-cloud release `vX.Y.Z` publishes this package at `X.Y.Z`. It
8
+ takes `@octogee/core` and `@octogee/shared` at the same version as peers.
9
+
10
+ Test helpers for code built on `@octogee/core`. Platform packages
11
+ (`gateway-edge`, `platform-api`, `fleet-controller`, `scripts`) and core's own
12
+ specs import them as `@octogee/core-testing/<module>`. None of it is runtime
13
+ code: it is a development dependency only, and `@octogee/core` declares no
14
+ test framework because of it. Image builds copy it only so that `npm ci`
15
+ resolves the dev dependencies of the package they install.
16
+
17
+ | Module | What it gives a spec | Optional peers it needs |
18
+ | --- | --- | --- |
19
+ | `journal-store` | an in-memory `PlatformStateStore` with journaled rows | none |
20
+ | `cron-custody` | gateways that hold and transfer scheduled jobs | none |
21
+ | `admin-dry-run-app` | an Admin API app for dry-run requests | `supertest`, `vitest`, `firebase-admin` (types) |
22
+ | `admin-fleet-route-app` | an Admin API app over in-memory fleet documents | `vitest`, `firebase-admin` (types) |
23
+ | `admin-fleet-releases-app` | an Admin API app for gateway release routes | `vitest`, `firebase-admin` |
24
+ | `firestore-user-accounts` | a `UserAccountReader` over a Firestore-shaped client | `firebase-admin` (types) |
25
+
26
+ ## Consumer contract
27
+
28
+ Platform packages install it beside `@octogee/core`, the same way:
29
+
30
+ ```jsonc
31
+ // <consumer>/package.json
32
+ "dependencies": { "@octogee/core": "file:../core" },
33
+ "devDependencies": { "@octogee/core-testing": "file:../core-testing" }
34
+ ```
35
+
36
+ `@octogee/core` is an optional peer only because core's own specs install
37
+ this package, and npm cannot satisfy a peer with the project being installed.
38
+ Every other consumer installs `@octogee/core` itself.
39
+
40
+ Core's specs run against core's source: `core/vitest.config.ts` and
41
+ `core/tsconfig.spec.json` resolve `@octogee/core/<module>` inside this
42
+ package to `core/src`, so the helpers and the specs share one copy of core.
43
+
44
+ ## Build and test
45
+
46
+ ```bash
47
+ cd core-testing
48
+ npm ci
49
+ npm run typecheck
50
+ npm test
51
+ npm run build
52
+ ```
53
+
54
+ The modules are in `src/`, one per `exports` entry in `package.json`.
55
+
56
+ ## Changing it
57
+
58
+ Build and commit `dist/` with the source change, as for `core`. A change to a
59
+ core module the helpers import needs core's `dist/` rebuilt first. CI rebuilds
60
+ `dist/`, and `scripts/ops/verify-committed-dist.mjs` fails when the committed
61
+ output differs.
@@ -0,0 +1,55 @@
1
+ import express, { Router } from "express";
2
+ import type { Firestore } from "firebase-admin/firestore";
3
+ import request from "supertest";
4
+ import { type ReleasePayload } from "@octogee/shared/types/gateway-releases";
5
+ import { type FleetRouterDeps } from "@octogee/core/admin-fleet-router";
6
+ import type { ReleaseDigestManifest } from "@octogee/core/artifact-registry";
7
+ import type { PlatformStateStore } from "@octogee/core/platform-state";
8
+ export type Seed = Record<string, Record<string, unknown>>;
9
+ export declare const SOURCE_SHA: string;
10
+ export declare const MANIFEST: ReleaseDigestManifest;
11
+ export declare const PAYLOAD: ReleasePayload;
12
+ export declare function gatewayRoot(gatewayId: string, overrides?: Record<string, unknown>): Record<string, unknown>;
13
+ export declare function release(gatewayId: string, number: number, payload?: ReleasePayload): Seed;
14
+ export declare function servingSharedGateway(gatewayId: string): Seed;
15
+ export declare function isolatedGateway(gatewayId: string, ownerUid: string, slug: string): Seed;
16
+ export declare function placedUser(uid: string, slug: string, gatewayId: string): Seed;
17
+ export declare function operation(id: string, row: Record<string, unknown>): Seed;
18
+ export declare const FLEET: Seed;
19
+ export declare const VM_RUNTIME: Seed;
20
+ export declare function sourceRecoveryFleet(): Seed;
21
+ export declare function restoreRecoveryFleet(): Seed;
22
+ export interface DryRunInstall {
23
+ addProductRoutes?: (router: Router, deps: {
24
+ db: Firestore;
25
+ store: PlatformStateStore;
26
+ requestNativeReturnSourceRecovery?: FleetRouterDeps["requestNativeReturnSourceRecovery"];
27
+ }) => void;
28
+ }
29
+ export declare function harness(seed?: Seed, install?: DryRunInstall): {
30
+ app: import("express-serve-static-core").Express;
31
+ router: import("express-serve-static-core").Router;
32
+ records: Map<string, Record<string, unknown>>;
33
+ effects: {
34
+ provisionGatewayAuthSecret: import("vitest").Mock<() => Promise<{}>>;
35
+ suspendAuthUser: import("vitest").Mock<() => Promise<undefined>>;
36
+ revokeConnectorGrantsForUser: import("vitest").Mock<() => Promise<undefined>>;
37
+ requestNativeReturnSourceRecovery: import("vitest").Mock<() => Promise<boolean>>;
38
+ createAccount: import("vitest").Mock<(account: {
39
+ userId: string;
40
+ }) => Promise<{
41
+ kind: "created";
42
+ userId: string;
43
+ }>>;
44
+ setChatPassword: import("vitest").Mock<() => Promise<undefined>>;
45
+ setGitPassword: import("vitest").Mock<() => Promise<string>>;
46
+ };
47
+ snapshot: () => string;
48
+ };
49
+ export type Method = "post" | "patch" | "delete";
50
+ export interface ChangingRequest {
51
+ method: Method;
52
+ path: string;
53
+ body?: Record<string, unknown>;
54
+ }
55
+ export declare function send(app: express.Express, call: ChangingRequest, dryRun: boolean): request.Test;
@@ -0,0 +1,234 @@
1
+ import express, { Router } from "express";
2
+ import request from "supertest";
3
+ import { vi } from "vitest";
4
+ import { GATEWAY_RELEASES_SUBCOLLECTION, releasePayloadHash, } from "@octogee/shared/types/gateway-releases";
5
+ import { GLM_GATEWAYS_COLLECTION, GLM_OPERATIONS_COLLECTION } from "@octogee/shared/types/glm";
6
+ import { addAdminFleetRoutes } from "@octogee/core/admin-fleet-router";
7
+ import { createDocumentFixtureStore } from "./journal-store.js";
8
+ import { noUserAccounts } from "@octogee/core/user-account";
9
+ export const SOURCE_SHA = "a".repeat(40);
10
+ export const MANIFEST = {
11
+ sourceSha: SOURCE_SHA,
12
+ manifestDigest: `sha256:${"b".repeat(64)}`,
13
+ openclawVersion: "2026.8.1",
14
+ openclawSourceSha: "f".repeat(40),
15
+ repository: "registry.example/platform",
16
+ surfaces: {
17
+ gateway: {
18
+ "octogee-gateway": `sha256:${"c".repeat(64)}`,
19
+ "octogee-gateway-builder": `sha256:${"d".repeat(64)}`,
20
+ "gateway-edge": `sha256:${"e".repeat(64)}`,
21
+ },
22
+ platform: {},
23
+ },
24
+ };
25
+ export const PAYLOAD = { imageRepository: "us-central1-docker.pkg.dev/octogee/octogee/octogee-gateway", imageTag: "abc1234" };
26
+ export function gatewayRoot(gatewayId, overrides = {}) {
27
+ return {
28
+ gatewayId,
29
+ createdAt: 1,
30
+ createdBy: "operator",
31
+ updatedAt: 1,
32
+ updatedBy: "operator",
33
+ latestRelease: 1,
34
+ desiredRelease: 1,
35
+ liveRelease: null,
36
+ desiredStatus: "running",
37
+ configSchemaVersion: 1,
38
+ profile: "standard",
39
+ gatewayClass: "shared",
40
+ imageProfile: "standard",
41
+ sizingTier: null,
42
+ gcpProject: null,
43
+ gatewayContainerSecurityContext: null,
44
+ serviceAccountName: null,
45
+ serviceAccount: null,
46
+ builderAccess: null,
47
+ ownerUid: null,
48
+ builderSlug: null,
49
+ modelBrokerLimits: null,
50
+ preemption: null,
51
+ coOwnerUids: [],
52
+ ...overrides,
53
+ };
54
+ }
55
+ export function release(gatewayId, number, payload = PAYLOAD) {
56
+ return {
57
+ [`gateways/${gatewayId}/${GATEWAY_RELEASES_SUBCOLLECTION}/${number}`]: {
58
+ gatewayId,
59
+ release: number,
60
+ createdAt: 1,
61
+ createdBy: "operator",
62
+ sourceRelease: null,
63
+ note: null,
64
+ payloadHash: releasePayloadHash(payload),
65
+ payload,
66
+ },
67
+ };
68
+ }
69
+ export function servingSharedGateway(gatewayId) {
70
+ const observedAt = Date.now();
71
+ return {
72
+ [`gateways/${gatewayId}`]: gatewayRoot(gatewayId, { liveRelease: 1 }),
73
+ ...release(gatewayId, 1),
74
+ [`${GLM_GATEWAYS_COLLECTION}/${gatewayId}`]: {
75
+ docKind: "runtime",
76
+ gatewayId,
77
+ release: 1,
78
+ lifecycle: "serving",
79
+ createdAt: 1,
80
+ createdByOperationId: null,
81
+ helm: {},
82
+ heartbeat: {
83
+ status: "ready",
84
+ lastHeartbeatAt: observedAt,
85
+ version: "abc1234",
86
+ startedAt: observedAt - 1_000,
87
+ mountedCustomers: [],
88
+ },
89
+ lastError: { message: null, at: null },
90
+ },
91
+ };
92
+ }
93
+ export function isolatedGateway(gatewayId, ownerUid, slug) {
94
+ return {
95
+ [`gateways/${gatewayId}`]: gatewayRoot(gatewayId, {
96
+ gatewayClass: "isolated",
97
+ imageProfile: "isolated",
98
+ profile: "isolated",
99
+ sizingTier: "s",
100
+ ownerUid,
101
+ builderSlug: slug,
102
+ latestRelease: 2,
103
+ desiredRelease: 2,
104
+ }),
105
+ ...release(gatewayId, 1),
106
+ ...release(gatewayId, 2, { ...PAYLOAD, imageTag: "deadbee" }),
107
+ };
108
+ }
109
+ export function placedUser(uid, slug, gatewayId) {
110
+ return {
111
+ [`users/${uid}`]: {
112
+ username: slug,
113
+ provisioning: { status: "complete", openclaw: { slug, gatewayId, status: "complete" } },
114
+ },
115
+ [`gateways/${gatewayId}/assignments/${uid}`]: {
116
+ uid,
117
+ slug,
118
+ gatewayId,
119
+ source: "onboarding",
120
+ state: "serving",
121
+ epoch: 1,
122
+ createdAt: 1,
123
+ updatedAt: 1,
124
+ updatedByOperationId: null,
125
+ },
126
+ };
127
+ }
128
+ export function operation(id, row) {
129
+ return { [`${GLM_OPERATIONS_COLLECTION}/${id}`]: row };
130
+ }
131
+ export const FLEET = {
132
+ "config/orchestrator": { defaultGatewayId: "shared-a", sharedGatewayIds: ["shared-a", "shared-b"] },
133
+ ...servingSharedGateway("shared-a"),
134
+ ...servingSharedGateway("shared-b"),
135
+ ...isolatedGateway("iso-ada", "uid-ada", "ada"),
136
+ "gateways/idle": gatewayRoot("idle"),
137
+ "gateways/gone": gatewayRoot("gone", { desiredStatus: "retired" }),
138
+ ...placedUser("uid-ada", "ada", "shared-a"),
139
+ };
140
+ export const VM_RUNTIME = {
141
+ [`${GLM_GATEWAYS_COLLECTION}/iso-ada`]: {
142
+ docKind: "runtime", gatewayId: "iso-ada", release: 2, lifecycle: "serving", createdAt: 1, createdByOperationId: null,
143
+ helm: {}, runtime: "gce-vm", lastError: { message: null, at: null },
144
+ },
145
+ };
146
+ export function sourceRecoveryFleet() {
147
+ const seed = {
148
+ "gateways/shared-0": gatewayRoot("shared-0", { desiredStatus: "draining", liveRelease: 1 }),
149
+ ...release("shared-0", 1),
150
+ };
151
+ for (const [index, slug] of ["jdog99", "oct01"].entries()) {
152
+ const uid = `source-user-${index}`;
153
+ const agentId = `octogee-${slug}-coach`;
154
+ seed[`users/${uid}`] = { username: slug, provisioning: { openclaw: { gatewayId: "shared-0", status: "complete" } } };
155
+ seed[`gateways/shared-0/assignments/${uid}`] = {
156
+ uid, slug, gatewayId: "shared-0", source: "onboarding", state: "serving", epoch: index + 1,
157
+ createdAt: 1, updatedAt: 1, updatedByOperationId: null,
158
+ };
159
+ seed[`users/${uid}/agentStores/${agentId}`] = {
160
+ agentId, gatewayId: "shared-0", assignmentEpoch: index + 1,
161
+ storeId: `00000000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`, schema: `source_${index}`, recordedAt: 1,
162
+ };
163
+ }
164
+ return seed;
165
+ }
166
+ export function restoreRecoveryFleet() {
167
+ const receipt = { uid: "u", attemptId: "retained-1", gatewayId: "shared-0", assignmentEpoch: 3, claimStartedAt: 200, dispatchedAt: 100 };
168
+ return {
169
+ "gateways/shared-0": gatewayRoot("shared-0"),
170
+ ...release("shared-0", 1),
171
+ ...operation("return-1", { restoreAttempt: receipt }),
172
+ };
173
+ }
174
+ export function harness(seed = FLEET, install = {}) {
175
+ const records = new Map(Object.entries(structuredClone(seed)));
176
+ const effects = {
177
+ provisionGatewayAuthSecret: vi.fn(async () => ({})),
178
+ suspendAuthUser: vi.fn(async () => undefined),
179
+ revokeConnectorGrantsForUser: vi.fn(async () => undefined),
180
+ requestNativeReturnSourceRecovery: vi.fn(async () => false),
181
+ createAccount: vi.fn(async (account) => ({ kind: "created", userId: account.userId })),
182
+ setChatPassword: vi.fn(async () => undefined),
183
+ setGitPassword: vi.fn(async () => "ws-ada"),
184
+ };
185
+ const releaseAuthority = {
186
+ resolveManifest: vi.fn(async () => MANIFEST),
187
+ aliasesFor: vi.fn(() => []),
188
+ keepTagsFor: vi.fn(() => []),
189
+ ensureAliases: vi.fn(async () => []),
190
+ };
191
+ const router = Router();
192
+ const store = createDocumentFixtureStore(records);
193
+ install.addProductRoutes?.(router, {
194
+ db: {}, store, requestNativeReturnSourceRecovery: effects.requestNativeReturnSourceRecovery,
195
+ });
196
+ addAdminFleetRoutes(router, {
197
+ accounts: noUserAccounts,
198
+ store,
199
+ logger: { info: vi.fn(), warn: vi.fn() },
200
+ computerReplacementEnabled: true,
201
+ listGatewayBuilds: vi.fn(async () => []),
202
+ releaseEnvironment: "test",
203
+ releaseAuthority,
204
+ platformArtifact: { imageRepository: "registry.example/gateway", imageTag: `abc1234@sha256:${"a".repeat(64)}` },
205
+ controllerStartedAt: 0,
206
+ provisionGatewayAuthSecret: effects.provisionGatewayAuthSecret,
207
+ suspendAuthUser: effects.suspendAuthUser,
208
+ revokeConnectorGrantsForUser: effects.revokeConnectorGrantsForUser,
209
+ requestNativeReturnSourceRecovery: effects.requestNativeReturnSourceRecovery,
210
+ userAccounts: { create: effects.createAccount },
211
+ userSignIn: {
212
+ channels: { setUserPassword: effects.setChatPassword },
213
+ git: { setUserPassword: effects.setGitPassword },
214
+ },
215
+ });
216
+ const app = express();
217
+ app.use(express.json());
218
+ app.use((req, _res, next) => {
219
+ Object.assign(req, { uid: "operator", isAdmin: true });
220
+ next();
221
+ });
222
+ app.use(router);
223
+ app.use((error, _req, res, _next) => {
224
+ res.status(500).json({ error: error.message });
225
+ });
226
+ const snapshot = () => JSON.stringify([...records.entries()].sort(([a], [b]) => a.localeCompare(b)));
227
+ return { app, router, records, effects, snapshot };
228
+ }
229
+ export function send(app, call, dryRun) {
230
+ const separator = call.path.includes("?") ? "&" : "?";
231
+ const target = dryRun ? `${call.path}${separator}dryRun=true` : call.path;
232
+ const pending = request(app)[call.method](target);
233
+ return call.body === undefined ? pending : pending.send(call.body);
234
+ }
@@ -0,0 +1,38 @@
1
+ import express from "express";
2
+ import type { Firestore } from "firebase-admin/firestore";
3
+ import { type ReleasePayload } from "@octogee/shared/types/gateway-releases";
4
+ import type { CentralReleaseAuthority } from "@octogee/core/artifact-registry";
5
+ import type { PlatformStateStore } from "@octogee/core/platform-state";
6
+ export declare const PLATFORM_BUILD: ReleasePayload;
7
+ export interface TestRouterOptions {
8
+ addProductRoutes?: (app: express.Express, deps: {
9
+ db: Firestore;
10
+ store: PlatformStateStore;
11
+ }) => void;
12
+ synchronizeFirstTwoReadsOf?: string;
13
+ failTransactions?: boolean;
14
+ beforeFirstTransaction?: (store: Map<string, Record<string, unknown>>) => void;
15
+ failFirstTransactionReadOf?: string;
16
+ releaseEnvironment?: "test" | "prod" | null;
17
+ releaseAuthority?: CentralReleaseAuthority;
18
+ provisionGatewayAuthSecret?: (input: {
19
+ gatewayId: string;
20
+ gatewayServiceAccount: string;
21
+ }) => Promise<unknown>;
22
+ }
23
+ export declare function makeDb(seed?: Record<string, Record<string, unknown>>, opts?: TestRouterOptions): {
24
+ db: Firestore;
25
+ store: Map<string, Record<string, unknown>>;
26
+ };
27
+ export declare function mkApp(seed?: Record<string, Record<string, unknown>>, opts?: TestRouterOptions): {
28
+ app: import("express-serve-static-core").Express;
29
+ store: Map<string, Record<string, unknown>>;
30
+ };
31
+ export declare function opsIn(store: Map<string, Record<string, unknown>>, kind: string): Record<string, unknown>[];
32
+ export declare function auditsIn(store: Map<string, Record<string, unknown>>): Record<string, unknown>[];
33
+ export declare const REPO = "us-central1-docker.pkg.dev/octogee/octogee/octogee-gateway";
34
+ export declare function seedNewSchemaGateway(id: string, payload: ReleasePayload, gatewayOverrides?: Record<string, unknown>): Record<string, Record<string, unknown>>;
35
+ export declare function sharedPayload(overrides?: Partial<ReleasePayload>): ReleasePayload;
36
+ export declare function readyHeartbeat(overrides?: Record<string, unknown>): Record<string, unknown>;
37
+ export declare function seedServingGateway(id: string, payload: ReleasePayload, heartbeat?: Record<string, unknown>, gatewayOverrides?: Record<string, unknown>): Record<string, Record<string, unknown>>;
38
+ export declare function userAuthRecord(gatewayId: string | null): Record<string, unknown>;