simplify catalog testing

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

.changeset/honest-hornets-double.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-node': minor
+---
+
+Updated the `catalogServiceMock` return type to match both `CatalogService` and `CatalogApi`

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

@@ -3,23 +3,116 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import { AddLocationRequest } from '@backstage/catalog-client';
+import { AddLocationResponse } from '@backstage/catalog-client';
 import { CatalogApi } from '@backstage/catalog-client';
+import { CatalogRequestOptions } from '@backstage/catalog-client';
+import { CatalogService } from '@backstage/plugin-catalog-node';
+import { CatalogServiceRequestOptions } from '@backstage/plugin-catalog-node';
+import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
+import { GetEntitiesByRefsRequest } from '@backstage/catalog-client';
+import { GetEntitiesByRefsResponse } from '@backstage/catalog-client';
+import { GetEntitiesRequest } from '@backstage/catalog-client';
+import { GetEntitiesResponse } from '@backstage/catalog-client';
+import { GetEntityAncestorsRequest } from '@backstage/catalog-client';
+import { GetEntityAncestorsResponse } from '@backstage/catalog-client';
+import { GetEntityFacetsRequest } from '@backstage/catalog-client';
+import { GetEntityFacetsResponse } from '@backstage/catalog-client';
+import { Location as Location_2 } from '@backstage/catalog-client';
+import { QueryEntitiesRequest } from '@backstage/catalog-client';
+import { QueryEntitiesResponse } from '@backstage/catalog-client';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceMock } from '@backstage/backend-test-utils';
+import { ValidateEntityResponse } from '@backstage/catalog-client';
+
+// @public
+export interface CatalogServiceMock extends CatalogService, CatalogApi {
+  // (undocumented)
+  addLocation(
+    location: AddLocationRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<AddLocationResponse>;
+  // (undocumented)
+  getEntities(
+    request?: GetEntitiesRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntitiesResponse>;
+  // (undocumented)
+  getEntitiesByRefs(
+    request: GetEntitiesByRefsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntitiesByRefsResponse>;
+  // (undocumented)
+  getEntityAncestors(
+    request: GetEntityAncestorsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntityAncestorsResponse>;
+  // (undocumented)
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Entity | undefined>;
+  // (undocumented)
+  getEntityFacets(
+    request: GetEntityFacetsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntityFacetsResponse>;
+  // (undocumented)
+  getLocationByEntity(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  getLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  getLocationByRef(
+    locationRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location_2 | undefined>;
+  // (undocumented)
+  queryEntities(
+    request?: QueryEntitiesRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<QueryEntitiesResponse>;
+  // (undocumented)
+  refreshEntity(
+    entityRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  removeEntityByUid(
+    uid: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  removeLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+  // (undocumented)
+  validateEntity(
+    entity: Entity,
+    locationRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<ValidateEntityResponse>;
+}
 
 // @public
 export function catalogServiceMock(options?: {
   entities?: Entity[];
-}): CatalogApi;
+}): CatalogServiceMock;
 
 // @public
 export namespace catalogServiceMock {
   const factory: (options?: {
     entities?: Entity[];
-  }) => ServiceFactory<CatalogApi, 'plugin', 'singleton'>;
+  }) => ServiceFactory<CatalogServiceMock, 'plugin', 'singleton'>;
   const mock: (
-    partialImpl?: Partial<CatalogApi> | undefined,
-  ) => ServiceMock<CatalogApi>;
+    partialImpl?: Partial<CatalogServiceMock> | undefined,
+  ) => ServiceMock<CatalogServiceMock>;
 }
 ```

plugins/catalog-node/src/testUtils.ts

@@ -21,3 +21,4 @@
  */
 
 export { catalogServiceMock } from './testUtils/catalogServiceMock';
+export type { CatalogServiceMock } from './testUtils/types';

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

@@ -15,15 +15,16 @@
  */
 
 import {
+  ServiceFactory,
   ServiceRef,
   createServiceFactory,
 } from '@backstage/backend-plugin-api';
 import { InMemoryCatalogClient } from '@backstage/catalog-client/testUtils';
 import { Entity } from '@backstage/catalog-model';
-import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
+import { catalogServiceRef } from '@backstage/plugin-catalog-node';
 // eslint-disable-next-line @backstage/no-undeclared-imports
 import { ServiceMock } from '@backstage/backend-test-utils';
-import { CatalogApi } from '@backstage/catalog-client';
+import { CatalogServiceMock } from './types';
 
 /** @internal */
 function simpleMock<TService>(
@@ -60,7 +61,7 @@ function simpleMock<TService>(
  */
 export function catalogServiceMock(options?: {
   entities?: Entity[];
-}): CatalogApi {
+}): CatalogServiceMock {
   return new InMemoryCatalogClient(options);
 }
 
@@ -80,12 +81,12 @@ export namespace catalogServiceMock {
       service: catalogServiceRef,
       deps: {},
       factory: () => new InMemoryCatalogClient(options),
-    });
+    }) as ServiceFactory<CatalogServiceMock, 'plugin', 'singleton'>;
   /**
    * Creates a catalog client whose methods are mock functions, possibly with
    * some of them overloaded by the caller.
    */
-  export const mock = simpleMock(catalogServiceRef, () => ({
+  export const mock = simpleMock<CatalogServiceMock>(catalogServiceRef, () => ({
     getEntities: jest.fn(),
     getEntitiesByRefs: jest.fn(),
     queryEntities: jest.fn(),

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

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  AddLocationRequest,
+  AddLocationResponse,
+  CatalogApi,
+  CatalogRequestOptions,
+  GetEntitiesByRefsRequest,
+  GetEntitiesByRefsResponse,
+  GetEntitiesRequest,
+  GetEntitiesResponse,
+  GetEntityAncestorsRequest,
+  GetEntityAncestorsResponse,
+  GetEntityFacetsRequest,
+  GetEntityFacetsResponse,
+  Location,
+  QueryEntitiesRequest,
+  QueryEntitiesResponse,
+  ValidateEntityResponse,
+} from '@backstage/catalog-client';
+import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
+import {
+  CatalogService,
+  CatalogServiceRequestOptions,
+} from '@backstage/plugin-catalog-node';
+
+/**
+ * A mock friendly version of `CatalogService` /
+ * {@link @backstage/catalog-client#CatalogApi | CatalogApi}.
+ *
+ * @public
+ * @remarks
+ *
+ * This interface supports both API types at the same time, and has an optional
+ * second argument to simplify testing since the mock implementation does not
+ * care about credentials.
+ */
+export interface CatalogServiceMock extends CatalogService, CatalogApi {
+  getEntities(
+    request?: GetEntitiesRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntitiesResponse>;
+
+  getEntitiesByRefs(
+    request: GetEntitiesByRefsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntitiesByRefsResponse>;
+
+  queryEntities(
+    request?: QueryEntitiesRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<QueryEntitiesResponse>;
+
+  getEntityAncestors(
+    request: GetEntityAncestorsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntityAncestorsResponse>;
+
+  getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Entity | undefined>;
+
+  removeEntityByUid(
+    uid: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+
+  refreshEntity(
+    entityRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+
+  getEntityFacets(
+    request: GetEntityFacetsRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<GetEntityFacetsResponse>;
+
+  getLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location | undefined>;
+
+  getLocationByRef(
+    locationRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location | undefined>;
+
+  addLocation(
+    location: AddLocationRequest,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<AddLocationResponse>;
+
+  removeLocationById(
+    id: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<void>;
+
+  getLocationByEntity(
+    entityRef: string | CompoundEntityRef,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<Location | undefined>;
+
+  validateEntity(
+    entity: Entity,
+    locationRef: string,
+    options?: CatalogServiceRequestOptions | CatalogRequestOptions,
+  ): Promise<ValidateEntityResponse>;
+}