diff --git a/packages/backend-test-utils/api-report.md b/packages/backend-test-utils/api-report.md index 147481f8d8..5831b093c5 100644 --- a/packages/backend-test-utils/api-report.md +++ b/packages/backend-test-utils/api-report.md @@ -183,28 +183,28 @@ export namespace mockServices { } } -// @public (undocumented) +// @public export class ServiceFactoryTester { - // (undocumented) static from( subject: | ServiceFactory | (() => ServiceFactory), - options?: { - dependencies?: Array ServiceFactory)>; - }, + options?: ServiceFactoryTesterOptions, ): ServiceFactoryTester; - // (undocumented) get( ...args: 'root' extends TScope ? [] : [pluginId?: string] ): Promise; - // (undocumented) getService( service: ServiceRef, ...args: 'root' extends TGetScope ? [] : [pluginId?: string] ): Promise; } +// @public +export interface ServiceFactoryTesterOptions { + dependencies?: Array ServiceFactory)>; +} + // @public (undocumented) export type ServiceMock = { factory: ServiceFactory; diff --git a/packages/backend-test-utils/src/next/wiring/ServiceFactoryTester.ts b/packages/backend-test-utils/src/next/wiring/ServiceFactoryTester.ts index 40364756c2..b4a038d001 100644 --- a/packages/backend-test-utils/src/next/wiring/ServiceFactoryTester.ts +++ b/packages/backend-test-utils/src/next/wiring/ServiceFactoryTester.ts @@ -22,16 +22,43 @@ import { defaultServiceFactories } from './TestBackend'; // eslint-disable-next-line @backstage/no-relative-monorepo-imports import { ServiceRegistry } from '../../../../backend-app-api/src/wiring/ServiceRegistry'; -/** @public */ +/** + * Options for {@link ServiceFactoryTester}. + * @public + */ +export interface ServiceFactoryTesterOptions { + /** + * Additional service factories to make available as dependencies. + * + * @remarks + * + * If a service factory is provided for a service that already has a default + * implementation, the provided factory will override the default. + */ + dependencies?: Array ServiceFactory)>; +} + +/** + * A utility to help test service factories in isolation. + * + * @public + */ export class ServiceFactoryTester { readonly #subject: ServiceRef; readonly #registry: ServiceRegistry; + /** + * Creates a new {@link ServiceFactoryTester} used to test the provided subject. + * + * @param subject - The service factory to test. + * @param options - Additional options + * @returns A new tester instance for the provided subject. + */ static from( subject: | ServiceFactory | (() => ServiceFactory), - options?: { dependencies?: Array ServiceFactory)> }, + options?: ServiceFactoryTesterOptions, ) { return new ServiceFactoryTester( typeof subject === 'function' ? subject() : subject, @@ -52,6 +79,16 @@ export class ServiceFactoryTester { ]); } + /** + * Returns the service instance for the subject. + * + * @remarks + * + * If the subject is a plugin scoped service factory a plugin ID + * can be provided to instantiate the service for a specific plugin. + * + * By default the plugin ID 'test' is used. + */ async get( ...args: 'root' extends TScope ? [] : [pluginId?: string] ): Promise { @@ -59,6 +96,13 @@ export class ServiceFactoryTester { return this.#registry.get(this.#subject, pluginId ?? 'test')!; } + /** + * Return the service instance for any of the provided dependencies or built-in services. + * + * @remarks + * + * A plugin ID can optionally be provided for plugin scoped services, otherwise the plugin ID 'test' is used. + */ async getService( service: ServiceRef, ...args: 'root' extends TGetScope ? [] : [pluginId?: string] diff --git a/packages/backend-test-utils/src/next/wiring/index.ts b/packages/backend-test-utils/src/next/wiring/index.ts index 949bd3329e..bd6a61317f 100644 --- a/packages/backend-test-utils/src/next/wiring/index.ts +++ b/packages/backend-test-utils/src/next/wiring/index.ts @@ -14,6 +14,9 @@ * limitations under the License. */ -export { ServiceFactoryTester } from './ServiceFactoryTester'; +export { + ServiceFactoryTester, + type ServiceFactoryTesterOptions, +} from './ServiceFactoryTester'; export { startTestBackend } from './TestBackend'; export type { TestBackend, TestBackendOptions } from './TestBackend';