From 52d5c30b59af3c3b988d2c008b4310e1b84401df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 9 Oct 2024 16:52:06 +0200 Subject: [PATCH] docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- packages/test-utils/report.api.md | 48 +++-------- .../test-utils/src/testUtils/apis/mockApis.ts | 79 +++++++++++++++++-- 2 files changed, 85 insertions(+), 42 deletions(-) diff --git a/packages/test-utils/report.api.md b/packages/test-utils/report.api.md index cc09727d87..ad5528d507 100644 --- a/packages/test-utils/report.api.md +++ b/packages/test-utils/report.api.md @@ -92,9 +92,7 @@ export class MockAnalyticsApi implements AnalyticsApi { // @public export namespace mockApis { - // (undocumented) export function analytics(): jest.Mocked; - // (undocumented) export namespace analytics { const // (undocumented) factory: () => ApiFactory; @@ -114,11 +112,9 @@ export namespace mockApis { ) => ApiFactory; const mock: (partialImpl?: Partial | undefined) => ApiMock; } - // (undocumented) export function discovery(options?: { baseUrl?: string }): jest.Mocked<{ getBaseUrl(pluginId: string): Promise; }>; - // (undocumented) export namespace discovery { const // (undocumented) factory: ( @@ -133,7 +129,6 @@ export namespace mockApis { partialImpl?: Partial | undefined, ) => ApiMock; } - // (undocumented) export function identity(options?: { userEntityRef?: string; ownershipEntityRefs?: string[]; @@ -142,7 +137,6 @@ export namespace mockApis { displayName?: string; picture?: string; }): jest.Mocked; - // (undocumented) export namespace identity { const // (undocumented) factory: ( @@ -162,7 +156,6 @@ export namespace mockApis { partialImpl?: Partial | undefined, ) => ApiMock; } - // (undocumented) export function permission(options?: { authorize?: | AuthorizeResult.ALLOW @@ -171,7 +164,6 @@ export namespace mockApis { request: EvaluatePermissionRequest, ) => AuthorizeResult.ALLOW | AuthorizeResult.DENY); }): jest.Mocked; - // (undocumented) export namespace permission { const // (undocumented) factory: ( @@ -192,11 +184,9 @@ export namespace mockApis { partialImpl?: Partial | undefined, ) => ApiMock; } - // (undocumented) export function storage(options?: { data?: JsonObject; }): jest.Mocked; - // (undocumented) export namespace storage { const // (undocumented) factory: ( @@ -211,9 +201,7 @@ export namespace mockApis { partialImpl?: Partial | undefined, ) => ApiMock; } - // (undocumented) export function translation(): jest.Mocked; - // (undocumented) export namespace translation { const // (undocumented) factory: () => ApiFactory; @@ -436,28 +424,16 @@ export function wrapInTestApp( // src/testUtils/apis/StorageApi/MockStorageApi.d.ts:24:5 - (ae-undocumented) Missing documentation for "set". // src/testUtils/apis/StorageApi/MockStorageApi.d.ts:25:5 - (ae-undocumented) Missing documentation for "remove". // src/testUtils/apis/StorageApi/MockStorageApi.d.ts:26:5 - (ae-undocumented) Missing documentation for "observe$". -// src/testUtils/apis/mockApis.d.ts:47:5 - (ae-undocumented) Missing documentation for "analytics". -// src/testUtils/apis/mockApis.d.ts:48:5 - (ae-undocumented) Missing documentation for "analytics". -// src/testUtils/apis/mockApis.d.ts:49:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:50:15 - (ae-undocumented) Missing documentation for "mock". -// src/testUtils/apis/mockApis.d.ts:101:5 - (ae-undocumented) Missing documentation for "discovery". -// src/testUtils/apis/mockApis.d.ts:106:5 - (ae-undocumented) Missing documentation for "discovery". -// src/testUtils/apis/mockApis.d.ts:107:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:110:15 - (ae-undocumented) Missing documentation for "mock". -// src/testUtils/apis/mockApis.d.ts:112:5 - (ae-undocumented) Missing documentation for "identity". -// src/testUtils/apis/mockApis.d.ts:120:5 - (ae-undocumented) Missing documentation for "identity". -// src/testUtils/apis/mockApis.d.ts:121:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:129:15 - (ae-undocumented) Missing documentation for "mock". -// src/testUtils/apis/mockApis.d.ts:131:5 - (ae-undocumented) Missing documentation for "permission". -// src/testUtils/apis/mockApis.d.ts:134:5 - (ae-undocumented) Missing documentation for "permission". -// src/testUtils/apis/mockApis.d.ts:135:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:138:15 - (ae-undocumented) Missing documentation for "mock". -// src/testUtils/apis/mockApis.d.ts:140:5 - (ae-undocumented) Missing documentation for "storage". -// src/testUtils/apis/mockApis.d.ts:143:5 - (ae-undocumented) Missing documentation for "storage". -// src/testUtils/apis/mockApis.d.ts:144:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:147:15 - (ae-undocumented) Missing documentation for "mock". -// src/testUtils/apis/mockApis.d.ts:149:5 - (ae-undocumented) Missing documentation for "translation". -// src/testUtils/apis/mockApis.d.ts:150:5 - (ae-undocumented) Missing documentation for "translation". -// src/testUtils/apis/mockApis.d.ts:151:15 - (ae-undocumented) Missing documentation for "factory". -// src/testUtils/apis/mockApis.d.ts:152:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:59:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:60:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:128:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:131:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:153:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:161:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:180:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:183:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:200:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:203:15 - (ae-undocumented) Missing documentation for "mock". +// src/testUtils/apis/mockApis.d.ts:218:15 - (ae-undocumented) Missing documentation for "factory". +// src/testUtils/apis/mockApis.d.ts:219:15 - (ae-undocumented) Missing documentation for "mock". ``` diff --git a/packages/test-utils/src/testUtils/apis/mockApis.ts b/packages/test-utils/src/testUtils/apis/mockApis.ts index 1adf172893..21bf0626ba 100644 --- a/packages/test-utils/src/testUtils/apis/mockApis.ts +++ b/packages/test-utils/src/testUtils/apis/mockApis.ts @@ -129,16 +129,26 @@ export namespace mockApis { const analyticsMockSkeleton = (): jest.Mocked => ({ captureEvent: jest.fn(), }); + /** + * Mock implementation of {@link @backstage/core-plugin-api#AnalyticsApi}. + * + * @public + */ export function analytics() { return analyticsMockSkeleton(); } + /** + * Mock implementations of {@link @backstage/core-plugin-api#AnalyticsApi}. + * + * @public + */ export namespace analytics { export const factory = simpleFactory(analyticsApiRef, analytics); export const mock = simpleMock(analyticsApiRef, analyticsMockSkeleton); } /** - * Fake implementation of {@link @backstage/frontend-plugin-api#ConfigApi} + * Fake implementation of {@link @backstage/core-plugin-api#ConfigApi} * with optional data supplied. * * @public @@ -149,7 +159,7 @@ export namespace mockApis { * data: { app: { baseUrl: 'https://example.com' } }, * }); * - * const rendered = await renderInTestApp( + * await renderInTestApp( * * * , @@ -160,15 +170,15 @@ export namespace mockApis { return new ConfigReader(options?.data, 'mock-config'); } /** - * Mock helpers for {@link @backstage/frontend-plugin-api#ConfigApi}. + * Mock helpers for {@link @backstage/core-plugin-api#ConfigApi}. * - * @see {@link @backstage/frontend-plugin-api#mockApis.config} + * @see {@link @backstage/core-plugin-api#mockApis.config} * @public */ export namespace config { /** * Creates a factory for a fake implementation of - * {@link @backstage/frontend-plugin-api#ConfigApi} with optional + * {@link @backstage/core-plugin-api#ConfigApi} with optional * configuration data supplied. * * @public @@ -176,7 +186,7 @@ export namespace mockApis { export const factory = simpleFactory(configApiRef, config); /** * Creates a mock implementation of - * {@link @backstage/frontend-plugin-api#ConfigApi}. All methods are + * {@link @backstage/core-plugin-api#ConfigApi}. All methods are * replaced with jest mock functions, and you can optionally pass in a * subset of methods with an explicit implementation. * @@ -205,6 +215,12 @@ export namespace mockApis { const discoveryMockSkeleton = (): jest.Mocked => ({ getBaseUrl: jest.fn(), }); + /** + * Fake implementation of {@link @backstage/core-plugin-api#DiscoveryApi}. By + * default returns URLs on the form `http://example.com/api/`. + * + * @public + */ export function discovery(options?: { baseUrl?: string }) { const baseUrl = options?.baseUrl ?? 'http://example.com'; return simpleInstance( @@ -217,6 +233,11 @@ export namespace mockApis { discoveryMockSkeleton, ); } + /** + * Mock implementations of {@link @backstage/core-plugin-api#DiscoveryApi}. + * + * @public + */ export namespace discovery { export const factory = simpleFactory(discoveryApiRef, discovery); export const mock = simpleMock(discoveryApiRef, discoveryMockSkeleton); @@ -228,6 +249,12 @@ export namespace mockApis { getProfileInfo: jest.fn(), signOut: jest.fn(), }); + /** + * Fake implementation of {@link @backstage/core-plugin-api#IdentityApi}. By + * default returns no token or profile info, and the user `user:default/test`. + * + * @public + */ export function identity(options?: { userEntityRef?: string; ownershipEntityRefs?: string[]; @@ -257,6 +284,11 @@ export namespace mockApis { async signOut() {}, }; } + /** + * Mock implementations of {@link @backstage/core-plugin-api#IdentityApi}. + * + * @public + */ export namespace identity { export const factory = simpleFactory(identityApiRef, identity); export const mock = simpleMock(identityApiRef, identityMockSkeleton); @@ -265,6 +297,13 @@ export namespace mockApis { const permissionMockSkeleton = (): jest.Mocked => ({ authorize: jest.fn(), }); + /** + * Fake implementation of + * {@link @backstage/plugin-permission-react#PermissionApi}. By default allows + * all actions. + * + * @public + */ export function permission(options?: { authorize?: | AuthorizeResult.ALLOW @@ -286,6 +325,12 @@ export namespace mockApis { } return new MockPermissionApi(authorize); } + /** + * Mock implementation of + * {@link @backstage/plugin-permission-react#PermissionApi}. + * + * @public + */ export namespace permission { export const factory = simpleFactory(permissionApiRef, permission); export const mock = simpleMock(permissionApiRef, permissionMockSkeleton); @@ -298,9 +343,20 @@ export namespace mockApis { observe$: jest.fn(), snapshot: jest.fn(), }); + /** + * Fake implementation of {@link @backstage/core-plugin-api#StorageApi}. + * Stores data temporarily in memory. + * + * @public + */ export function storage(options?: { data?: JsonObject }) { return MockStorageApi.create(options?.data); } + /** + * Mock implementations of {@link @backstage/core-plugin-api#StorageApi}. + * + * @public + */ export namespace storage { export const factory = simpleFactory(storageApiRef, storage); export const mock = simpleMock(storageApiRef, storageMockSkeleton); @@ -310,9 +366,20 @@ export namespace mockApis { getTranslation: jest.fn(), translation$: jest.fn(), }); + /** + * Fake implementation of {@link @backstage/core-plugin-api/alpha#TranslationApi}. + * By default returns the default translation. + * + * @public + */ export function translation() { return MockTranslationApi.create(); } + /** + * Mock implementations of {@link @backstage/core-plugin-api/alpha#TranslationApi}. + * + * @public + */ export namespace translation { export const factory = simpleFactory(translationApiRef, translation); export const mock = simpleMock(translationApiRef, translationMockSkeleton);