changeset

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

.changeset/weak-monkeys-occur.md

@@ -0,0 +1,6 @@
+---
+'@backstage/catalog-client': minor
+'@backstage/plugin-catalog-node': minor
+---
+
+Add catalog service mocks under the `/testUtils` subpath export.

packages/catalog-client/api-report-testUtils.md

@@ -21,7 +21,7 @@ import { QueryEntitiesRequest } from '@backstage/catalog-client';
 import { QueryEntitiesResponse } from '@backstage/catalog-client';
 import { ValidateEntityResponse } from '@backstage/catalog-client';
 
-// @public (undocumented)
+// @public
 export class InMemoryCatalogClient implements CatalogApi {
   constructor(options?: { entities?: Entity[] });
   // (undocumented)

packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts

@@ -38,7 +38,13 @@ import {
 } from '@backstage/catalog-model';
 import { NotFoundError, NotImplementedError } from '@backstage/errors';
 
-/** @public */
+/**
+ * Implements a VERY basic fake catalog client that stores entities in memory.
+ * It has severely limited functionality, and is only useful under certain
+ * circumstances in tests.
+ *
+ * @public
+ */
 export class InMemoryCatalogClient implements CatalogApi {
   #entities: Entity[];
 

plugins/catalog-node/api-report-testUtils.md

@@ -9,21 +9,19 @@ import { InMemoryCatalogClient } from '@backstage/catalog-client/testUtils';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceMock } from '@backstage/backend-test-utils';
 
-// @public (undocumented)
+// @public
 export function catalogServiceMock(options?: {
   entities?: Entity[];
 }): InMemoryCatalogClient;
 
-// @public (undocumented)
+// @public
 export namespace catalogServiceMock {
-  const // (undocumented)
-    factory: (options?: {
-      entities?: Entity[];
-    }) => ServiceFactory<CatalogApi, 'plugin', 'singleton'>;
-  const // (undocumented)
-    mock: (
-      partialImpl?: Partial<CatalogApi> | undefined,
-    ) => ServiceMock<CatalogApi>;
+  const factory: (options?: {
+    entities?: Entity[];
+  }) => ServiceFactory<CatalogApi, 'plugin', 'singleton'>;
+  const mock: (
+    partialImpl?: Partial<CatalogApi> | undefined,
+  ) => ServiceMock<CatalogApi>;
 }
 
 // (No @packageDocumentation comment for this package)

plugins/catalog-node/src/testUtils/catalogServiceMock.ts

@@ -50,19 +50,38 @@ function simpleMock<TService>(
   };
 }
 
-/** @public */
+/**
+ * Creates a fake catalog client that handles entities in memory storage. Note
+ * that this client may be severely limited in functionality, and advanced
+ * functions may not be available at all.
+ *
+ * @public
+ */
 export function catalogServiceMock(options?: { entities?: Entity[] }) {
   return new InMemoryCatalogClient(options);
 }
 
-/** @public */
+/**
+ * A collection of mock functionality for the catalog service.
+ *
+ * @public
+ */
 export namespace catalogServiceMock {
+  /**
+   * Creates a fake catalog client that handles entities in memory storage. Note
+   * that this client may be severely limited in functionality, and advanced
+   * functions may not be available at all.
+   */
   export const factory = (options?: { entities?: Entity[] }) =>
     createServiceFactory({
       service: catalogServiceRef,
       deps: {},
       factory: () => new InMemoryCatalogClient(options),
     });
+  /**
+   * Creates a catalog client whose methods are mock functions, possibly with
+   * some of them overloaded by the caller.
+   */
   export const mock = simpleMock(catalogServiceRef, () => ({
     getEntities: jest.fn(),
     getEntitiesByRefs: jest.fn(),