c8y-nitro 0.10.3 → 0.11.0

package/dist/testing.d.mts

@@ -0,0 +1,521 @@
+import { a as C8yTestRole, c as C8yTestUser, i as C8yTestOptions, l as C8yUnhandledRequest, n as C8yRequestContext, o as C8yTestState, r as C8yRequestHandler, s as C8yTestSubscription, t as C8yRequest, u as UnhandledRequestStrategy } from "./types-D663gk80.mjs";
+import { serverFetch as serverFetch$1 } from "nitro";
+import { C8YTenantOptionKey } from "c8y-nitro/types";
+/**
+ * Enum values from the spec.
+ */
+declare const C8Y_ENUMS: {
+  readonly alarmSeverity: readonly ["CRITICAL", "MAJOR", "MINOR", "WARNING"];
+  readonly alarmStatus: readonly ["ACTIVE", "ACKNOWLEDGED", "CLEARED"];
+  readonly operationStatus: readonly ["SUCCESSFUL", "FAILED", "EXECUTING", "PENDING"];
+  readonly seriesAggregationType: readonly ["DAILY", "HOURLY", "MINUTELY"];
+  readonly seriesAggregationFunction: readonly ["min", "max", "avg", "sum", "count", "stdDevPop", "stdDevSamp"];
+};
+type C8yAlarmSeverity = typeof C8Y_ENUMS.alarmSeverity[number];
+type C8yAlarmStatus = typeof C8Y_ENUMS.alarmStatus[number];
+type C8yOperationStatus = typeof C8Y_ENUMS.operationStatus[number];
+/**
+ * A managed object created by `c8y.device()` or `c8y.managedObject()`. Its
+ * `id` exists while a test runs (the object is rebuilt before every test).
+ */
+interface C8yRef {
+  readonly id: string;
+}
+/**
+ * A managed object id, a ref from `c8y.device()`, or `{ id }`.
+ */
+type C8yIdInput = string | C8yRef | {
+  id: string;
+};
+/**
+ * Input of `c8y.managedObject()` and `c8y.device()`.
+ */
+interface C8yManagedObjectInput {
+  name?: string;
+  type?: string;
+  /**
+   * Defaults to the current user.
+   */
+  owner?: string;
+  /**
+   * Child devices (references in `childDevices`).
+   */
+  children?: C8yRef[];
+  /**
+   * Child assets (references in `childAssets`).
+   */
+  assets?: C8yRef[];
+  /**
+   * Child additions (references in `childAdditions`).
+   */
+  additions?: C8yRef[];
+  /**
+   * External ids by type, e.g. `{ c8y_Serial: 'SN-1' }`.
+   */
+  externalIds?: Record<string, string>;
+  /**
+   * Tenant to create it in. Defaults to the deployed tenant.
+   */
+  tenant?: string;
+  /**
+   * Any fragments, e.g. `c8y_Hardware: { serialNumber: 'SN-1' }`.
+   */
+  [fragment: string]: unknown;
+}
+interface SourcedInput {
+  source: C8yIdInput;
+  type: string;
+  /**
+   * Defaults to now.
+   */
+  time?: string;
+  [fragment: string]: unknown;
+}
+interface C8yMeasurementInput extends SourcedInput {}
+interface C8yEventInput extends SourcedInput {
+  /**
+   * Defaults to `type`.
+   */
+  text?: string;
+}
+interface C8yAlarmInput extends SourcedInput {
+  /**
+   * Defaults to `type`.
+   */
+  text?: string;
+  /**
+   * Defaults to `MAJOR`.
+   */
+  severity?: C8yAlarmSeverity;
+  /**
+   * Defaults to `ACTIVE`.
+   */
+  status?: C8yAlarmStatus;
+}
+interface C8yOperationInput {
+  deviceId: C8yIdInput;
+  /**
+   * Defaults to `PENDING`.
+   */
+  status?: C8yOperationStatus;
+  failureReason?: string;
+  [fragment: string]: unknown;
+}
+/**
+ * Input of `c8y.seed()`.
+ */
+interface C8ySeed {
+  measurements?: C8yMeasurementInput[];
+  events?: C8yEventInput[];
+  alarms?: C8yAlarmInput[];
+  operations?: C8yOperationInput[];
+  /**
+   * Tenant to seed. Defaults to the deployed tenant.
+   */
+  tenant?: string;
+}
+/**
+ * Input of `c8y.binary()`.
+ */
+interface C8yBinaryInput {
+  /**
+   * File name.
+   */
+  name: string;
+  /**
+   * File content.
+   */
+  content: string | Uint8Array;
+  /**
+   * Content type. Defaults to `text/plain` for strings, `application/octet-stream` otherwise.
+   */
+  contentType?: string;
+  /**
+   * Tenant to create it in. Defaults to the deployed tenant.
+   */
+  tenant?: string;
+  /**
+   * Any other managed object fragments.
+   */
+  [fragment: string]: unknown;
+}
+/**
+ * Stored file content, as read by `c8y.db.binaries.content()`.
+ */
+interface C8yBinaryContent {
+  name: string;
+  contentType: string;
+  bytes: Uint8Array;
+  /**
+   * The content decoded as UTF-8.
+   */
+  text: () => string;
+}
+/**
+ * Filter for `c8y.db.*.find()`: partial match, or a predicate.
+ */
+type C8yDbFilter = Record<string, unknown> | ((document: Record<string, any>) => boolean);
+/**
+ * Read access to one collection of the fake tenant.
+ */
+interface C8yDbCollection<T> {
+  /**
+   * Object by id (or ref).
+   */
+  get: (id: C8yIdInput) => T | undefined;
+  /**
+   * Objects matching a partial object (refs and ids match `source`/`deviceId`) or a predicate, in creation order.
+   */
+  find: (filter?: C8yDbFilter) => T[];
+}
+/**
+ * Read (and limited write) access to the fake tenant's data.
+ */
+interface C8yDb {
+  managedObjects: C8yDbCollection<Record<string, any>>;
+  measurements: C8yDbCollection<Record<string, any>>;
+  events: C8yDbCollection<Record<string, any>> & {
+    /**
+     * Attachment (binary) of an event.
+     */
+    attachment: (id: C8yIdInput) => C8yBinaryContent | undefined;
+  };
+  binaries: C8yDbCollection<Record<string, any>> & {
+    /**
+     * Content of an inventory binary.
+     */
+    content: (id: C8yIdInput) => C8yBinaryContent | undefined;
+  };
+  alarms: C8yDbCollection<Record<string, any>>;
+  operations: C8yDbCollection<Record<string, any>> & {
+    /**
+     * Updates an operation like a device agent would, e.g.
+     * `{ status: 'SUCCESSFUL' }` or `{ status: 'FAILED', failureReason }`.
+     */
+    update: (id: C8yIdInput, update: {
+      status: C8yOperationStatus;
+      failureReason?: string;
+      [fragment: string]: unknown;
+    }) => void;
+  };
+  externalIds: {
+    /**
+     * External ids, optionally of one managed object.
+     */
+    find: (managedObject?: C8yIdInput) => Array<{
+      type: string;
+      externalId: string;
+      managedObjectId: string;
+    }>;
+  };
+  /**
+   * The same views for another tenant's data.
+   */
+  tenant: (tenant: string) => Omit<C8yDb, 'tenant'>;
+}
+/**
+ * Notification 2.0 subscription as stored by the fake.
+ */
+interface FakeSubscription {
+  id: string;
+  tenant: string;
+  context: 'mo' | 'tenant';
+  subscription: string;
+  source?: {
+    id: string;
+  };
+  subscriptionFilter?: {
+    apis?: string[];
+    typeFilter?: string;
+  };
+  fragmentsToCopy?: string[];
+  nonPersistent?: boolean;
+}
+type TenantOptionKeyInput = C8YTenantOptionKey | (string & {});
+/**
+ * Where a tenant option lives. Defaults: own settings category, deployed tenant.
+ */
+export interface C8yTenantOptionScope {
+  category?: string;
+  tenant?: string;
+}
+/**
+ * Options of the `toHaveReceived()` matcher.
+ */
+export interface ToHaveReceivedOptions {
+  /**
+   * Exact number of matching requests. Default: at least one.
+   */
+  times?: number;
+}
+declare module 'vitest' {
+  interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> {
+    /**
+     * Asserts that the microservice sent a matching request to the fake
+     * Cumulocity platform in this test. Use it on `c8y`.
+     *
+     * @example
+     * ```ts
+     * expect(c8y).toHaveReceived('PUT /tenant/options/**')
+     * expect(c8y).toHaveReceived('GET /inventory/managedObjects/42', { times: 1 })
+     * ```
+     */
+    toHaveReceived: (pattern: string, options?: ToHaveReceivedOptions) => R;
+  }
+}
+/**
+ * The fake Cumulocity tenant your microservice talks to in tests. Requires the
+ * `c8yTest()` plugin from `c8y-nitro/testing/vite`.
+ *
+ * Arrange calls are **scope-aware**: at the top of a file they apply to every
+ * test in the file, inside `describe` to the tests of that `describe` (inner
+ * scopes override outer ones), and inside a test only to that test. Before
+ * every test the tenant is rebuilt from the plugin baseline, the call log is
+ * cleared, and c8y-nitro's caches are invalidated, so tests are independent.
+ *
+ * Arrange the platform as data: users, subscriptions, tenant options,
+ * managed objects (`device()`), and measurements, events, alarms, and
+ * operations (`seed()`). Your service reads and writes them through the real
+ * `@c8y/client`; assert on its responses and on `c8y.db`.
+ *
+ * @example
+ * ```ts
+ * import { c8y, definePersona, serverFetch } from 'c8y-nitro/testing'
+ *
+ * const pump = c8y.device({ name: 'Pump', externalIds: { c8y_Serial: 'SN-1' } })  // seed the platform
+ * const visitor = definePersona({ userName: 'visitor', roles: [] })
+ *
+ * it('returns the pump', async () => {
+ *   expect((await serverFetch('/pumps/SN-1')).status).toBe(200)                  // as the default user
+ *   expect((await serverFetch('/pumps/SN-1', { as: visitor })).status).toBe(403) // as another user
+ * })
+ * ```
+ */
+export declare const c8y: {
+  /**
+   * Tenant the microservice is deployed in (the bootstrap tenant).
+   */
+  readonly tenant: string;
+  /**
+   * Every request the microservice sent to the platform in this test, in order.
+   */
+  readonly calls: readonly C8yRequest[];
+  /**
+   * Requests in this test the fake tenant could not answer (not emulated, and
+   * no `override()`). With the default `onUnhandledRequest: 'error'`, the test
+   * fails after it ran if this is not empty.
+   */
+  readonly unhandled: readonly C8yUnhandledRequest[];
+  /**
+   * The fake tenant's data, to assert on what your service wrote (and to
+   * drive operation status like a device would).
+   *
+   * @example
+   * ```ts
+   * expect(c8y.db.alarms.find({ source: pump, type: 'overdue' })).toMatchObject([{ severity: 'MAJOR' }])
+   * c8y.db.operations.update(operationId, { status: 'SUCCESSFUL' })
+   * ```
+   */
+  db: C8yDb;
+  /**
+   * Creates a managed object in the fake tenant (in the current scope).
+   * Returns a ref whose `id` is available while a test runs.
+   *
+   * @example
+   * ```ts
+   * const gateway = c8y.managedObject({ name: 'Gateway', type: 'c8y_Gateway', children: [c8y.device({ name: 'Pump' })] })
+   * ```
+   * @param input - Fragments, plus `children`/`assets`/`additions`, `externalIds`, and `tenant`
+   */
+  managedObject(input?: C8yManagedObjectInput): C8yRef;
+  /**
+   * Creates a device (a managed object with `c8y_IsDevice`) in the fake tenant.
+   *
+   * @example
+   * ```ts
+   * const pump = c8y.device({ name: 'Pump', externalIds: { c8y_Serial: 'SN-1' } })
+   * it('…', async () => {
+   *   await serverFetch(`/devices/${pump.id}`)
+   * })
+   * ```
+   * @param input - Fragments, plus `children`/`assets`/`additions`, `externalIds`, and `tenant`
+   */
+  device(input?: C8yManagedObjectInput): C8yRef;
+  /**
+   * Creates an inventory binary (a file) in the fake tenant (in the current
+   * scope). Returns a ref whose `id` is available while a test runs.
+   *
+   * @example
+   * ```ts
+   * const manual = c8y.binary({ name: 'manual.txt', content: 'Turn it off and on again.' })
+   * ```
+   * @param input - Name, content, optional content type, tenant, and fragments
+   */
+  binary(input: C8yBinaryInput): C8yRef;
+  /**
+   * Seeds measurements, events, alarms, and operations (in the current scope).
+   * They are validated like API writes (required fields, enums, existing
+   * source), and alarms are deduplicated like on the platform.
+   *
+   * @example
+   * ```ts
+   * c8y.seed({
+   *   measurements: [{ source: pump, type: 'c8y_Temperature', c8y_Temperature: { T: { value: 21.5, unit: 'C' } } }],
+   *   alarms: [{ source: pump, type: 'c8y_Overheating', severity: 'CRITICAL' }],
+   * })
+   * ```
+   * @param seed - Data to seed
+   */
+  seed(seed: C8ySeed): void;
+  /**
+   * Tenants subscribed to the microservice and their service users.
+   */
+  subscriptions: {
+    /**
+     * Current subscriptions.
+     */
+    list(): readonly C8yTestSubscription[];
+    /**
+     * Adds a subscription, or replaces the one of the same tenant.
+     * @param subscription - Tenant and service user credentials
+     */
+    add(subscription: C8yTestSubscription): void;
+    /**
+     * Removes the subscription of a tenant.
+     * @param tenant - Tenant id
+     */
+    remove(tenant: string): void;
+    /**
+     * Replaces all subscriptions.
+     * @param subscriptions - The new subscriptions
+     */
+    set(subscriptions: C8yTestSubscription[]): void;
+  };
+  /**
+   * Tenant options stored in the fake platform. These are platform values, not
+   * caches: a cached read keeps its value until it expires or is invalidated.
+   */
+  tenantOptions: {
+    /**
+     * Sets an option value (merged with the outer scope's options).
+     * @param key - Option key
+     * @param value - Option value
+     * @param scope - Category and tenant, default own category in the deployed tenant
+     */
+    set(key: TenantOptionKeyInput, value: string, scope?: C8yTenantOptionScope): void;
+    /**
+     * Deletes an option in this scope.
+     * @param key - Option key
+     * @param scope - Category and tenant
+     */
+    delete(key: TenantOptionKeyInput, scope?: C8yTenantOptionScope): void;
+    /**
+     * Reads an option value from the platform.
+     * @param key - Option key
+     * @param scope - Category and tenant
+     */
+    get(key: TenantOptionKeyInput, scope?: C8yTenantOptionScope): string | undefined;
+  };
+  /**
+   * Overrides the platform's answer for requests matching `pattern`. Use it
+   * for failures (errors, timeouts) and for APIs the fake tenant does not
+   * emulate; arrange normal data with `device()`/`seed()` instead, so tests do
+   * not depend on which endpoints your service calls. Overrides stack: inner
+   * scopes and newer overrides win over everything else.
+   *
+   * Patterns are `"[METHOD ]/path"` with `:param`, `*` (one segment), and `**`
+   * (rest of the path).
+   *
+   * @example
+   * ```ts
+   * c8y.override('GET /inventory/**', () => Response.json({ message: 'Unavailable' }, { status: 503 }))
+   * c8y.override('GET /tenant/statistics/summary', () => ({ deviceCount: 3 }))
+   * ```
+   * @param pattern - Route pattern
+   * @param handler - Returns a `Response`, a JSON value (`200`), or nothing (`204`)
+   * @param options - Handler options
+   * @param options.once - Answer only the first matching request
+   */
+  override(pattern: string, handler: C8yRequestHandler, options?: {
+    once?: boolean;
+  }): void;
+  /**
+   * Applies several arrange settings at once, in the current scope. Callers
+   * are not part of the state: use `serverFetch(path, { as })`.
+   * @param state - Partial tenant state
+   */
+  apply(state: Partial<Omit<C8yTestState, "user">>): void;
+  /**
+   * Notification 2.0 (realtime) in the fake tenant. Writes from your service,
+   * `c8y.seed()`/`c8y.device()` inside a test, and `c8y.db.operations.update()`
+   * are published to the subscriptions your service created.
+   */
+  notifications: {
+    /**
+     * Waits until every notification delivered to your service's realtime
+     * handlers has been processed (acknowledged), including notifications
+     * caused by the handlers' own writes.
+     *
+     * @example
+     * ```ts
+     * c8y.seed({ measurements: [{ source: pump, type: 'c8y_Temperature', c8y_Temperature: { T: { value: 95, unit: 'C' } } }] })
+     * await c8y.notifications.settled()
+     * expect(c8y.db.alarms.find({ source: pump })).toHaveLength(1)
+     * ```
+     * @param options - Options
+     * @param options.timeout - Milliseconds to wait before failing (default 5000)
+     */
+    settled(options?: {
+      timeout?: number;
+    }): Promise<void>;
+    /**
+     * Notification 2.0 subscriptions your service created (all tenants).
+     */
+    subscriptions(): readonly FakeSubscription[];
+  };
+  /**
+   * Recorded requests matching a route pattern (same syntax as `override()`).
+   * @param pattern - Route pattern, e.g. `'GET /tenant/options/**'`
+   */
+  callsTo(pattern: string): C8yRequest[];
+};
+/**
+ * Request options of `serverFetch()`: Nitro's options plus `as`.
+ */
+export type C8yServerFetchInit = NonNullable<Parameters<typeof serverFetch$1>[1]> & {
+  /**
+   * The user calling the route, e.g. a persona from `definePersona()` or an
+   * inline user. `null` is a caller without a valid login. Without `as`, the
+   * default `user` from the `c8yTest()` config calls.
+   */
+  as?: C8yTestUser | null;
+};
+/**
+ * Types a user that calls your service in tests, so it can be defined once
+ * and reused (role names autocomplete). Pass it to `serverFetch(path, { as })`.
+ *
+ * @example
+ * ```ts
+ * const operator = definePersona({ userName: 'operator', roles: ['ROLE_ALARM_ADMIN'] })
+ * const partner = definePersona({ userName: 'eve', roles: [], tenant: 't99999' })
+ * ```
+ * @param user - The user
+ */
+export declare function definePersona(user: C8yTestUser): C8yTestUser;
+/**
+ * Calls a route of your service, like `serverFetch()` from `nitro`. With
+ * `as`, the request is sent as that user: the platform answers
+ * `GET /user/currentUser` with it during the request.
+ *
+ * @example
+ * ```ts
+ * await serverFetch('/pumps/SN-1')                                           // default user
+ * await serverFetch('/pumps/SN-1/check', { method: 'POST', as: operator })   // a persona
+ * await serverFetch('/pumps/SN-1', { as: { userName: 'visitor', roles: [] } }) // inline
+ * await serverFetch('/user', { as: null })                                   // not logged in
+ * ```
+ * @param path - Route path, including the query
+ * @param init - Request options, plus `as`
+ */
+export declare function serverFetch(path: string, init?: C8yServerFetchInit): Promise<Response>;
+export type { C8yAlarmInput, C8yAlarmSeverity, C8yAlarmStatus, C8yBinaryContent, C8yBinaryInput, C8yDb, C8yDbCollection, C8yDbFilter, C8yEventInput, C8yIdInput, C8yManagedObjectInput, C8yMeasurementInput, FakeSubscription as C8yNotificationSubscription, C8yOperationInput, C8yOperationStatus, C8yRef, C8yRequest, C8yRequestContext, C8yRequestHandler, C8ySeed, C8yTestOptions, C8yTestRole, C8yTestState, C8yTestSubscription, C8yTestUser, C8yUnhandledRequest, UnhandledRequestStrategy };