From 289c22464038538773d3856bd3742b3114fef69a Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 5 Oct 2023 13:19:57 +0200
Subject: [PATCH] backend-common: tweak package path resolution mock API

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 packages/backend-common/src/testUtils.ts      | 34 +++++++++++--------
 .../backend-common/testUtils-api-report.md    | 26 ++++++++++++++
 .../app-backend/src/service/appPlugin.test.ts | 18 +++-------
 .../src/stages/publish/local.test.ts          |  6 ++--
 4 files changed, 53 insertions(+), 31 deletions(-)
 create mode 100644 packages/backend-common/testUtils-api-report.md

diff --git a/packages/backend-common/src/testUtils.ts b/packages/backend-common/src/testUtils.ts
index 0b23333434..8be6010010 100644
--- a/packages/backend-common/src/testUtils.ts
+++ b/packages/backend-common/src/testUtils.ts
@@ -18,38 +18,44 @@ import { packagePathMocks } from './paths';
 import { posix as posixPath, resolve as resolvePath } from 'path';
 
 /** @public */
-export interface PackagePathMock {
+export interface PackagePathResolutionOverride {
   /** Restored the normal behavior of resolvePackagePath */
   restore(): void;
 }
 
 /** @public */
-export interface PackagePathMockOptions {
+export interface OverridePackagePathResolutionOptions {
   /** The name of the package to mock the resolved path of */
-  name: string;
+  packageName: string;
+
   /** A replacement for the root package path */
   path?: string;
+
   /**
    * Replacements for package sub-paths, each key must be an exact match of the posix-style path
    * that is being resolved within the package.
    *
    * For example, code calling `resolvePackagePath('x', 'foo', 'bar')` would match only the following
-   * configuration: `createPackagePathMock({name: 'x', paths: {'foo/bar': baz}})`
+   * configuration: `overridePackagePathResolution({ packageNAme: 'x', paths: { 'foo/bar': baz } })`
    */
   paths?: { [path in string]: string | (() => string) };
 }
 
-/** @public */
-export function createPackagePathMock(
-  options: PackagePathMockOptions,
-): PackagePathMock {
-  if (packagePathMocks.has(options.name)) {
-    throw new Error(
-      `Duplicate package path mock for package '${options.name}'`,
-    );
+/**
+ * This utility helps you override the paths returned by `resolvePackagePath` for a given package.
+ *
+ * @public
+ */
+export function overridePackagePathResolution(
+  options: OverridePackagePathResolutionOptions,
+): PackagePathResolutionOverride {
+  const name = options.packageName;
+
+  if (packagePathMocks.has(name)) {
+    throw new Error(`Duplicate package path mock for package '${name}'`);
   }
 
-  packagePathMocks.set(options.name, paths => {
+  packagePathMocks.set(name, paths => {
     const joinedPath = posixPath.join(...paths);
     const localResolver = options.paths?.[joinedPath];
     if (localResolver) {
@@ -65,7 +71,7 @@ export function createPackagePathMock(
 
   return {
     restore() {
-      packagePathMocks.delete(options.name);
+      packagePathMocks.delete(name);
     },
   };
 }
diff --git a/packages/backend-common/testUtils-api-report.md b/packages/backend-common/testUtils-api-report.md
new file mode 100644
index 0000000000..9dbdade10e
--- /dev/null
+++ b/packages/backend-common/testUtils-api-report.md
@@ -0,0 +1,26 @@
+## API Report File for "@backstage/backend-common"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+// @public
+export function overridePackagePathResolution(
+  options: OverridePackagePathResolutionOptions,
+): PackagePathResolutionOverride;
+
+// @public (undocumented)
+export interface OverridePackagePathResolutionOptions {
+  packageName: string;
+  path?: string;
+  paths?: {
+    [path in string]: string | (() => string);
+  };
+}
+
+// @public (undocumented)
+export interface PackagePathResolutionOverride {
+  restore(): void;
+}
+
+// (No @packageDocumentation comment for this package)
+```
diff --git a/plugins/app-backend/src/service/appPlugin.test.ts b/plugins/app-backend/src/service/appPlugin.test.ts
index 7bffdd00f6..647697c204 100644
--- a/plugins/app-backend/src/service/appPlugin.test.ts
+++ b/plugins/app-backend/src/service/appPlugin.test.ts
@@ -22,22 +22,12 @@ import {
 } from '@backstage/backend-test-utils';
 import { appPlugin } from './appPlugin';
 import { createRootLogger } from '@backstage/backend-common';
+import { overridePackagePathResolution } from '@backstage/backend-common/testUtils';
 
 const mockDir = createMockDirectory();
-
-jest.mock('../../../../packages/backend-common/src/paths', () => {
-  const actual = jest.requireActual(
-    '../../../../packages/backend-common/src/paths',
-  );
-  return {
-    ...actual,
-    resolvePackagePath: (pkg: string, ...args: string[]) => {
-      if (pkg === 'app') {
-        return mockDir.resolve(...args);
-      }
-      return actual.resolvePackagePath(pkg, ...args);
-    },
-  };
+overridePackagePathResolution({
+  packageName: 'app',
+  path: mockDir.path,
 });
 
 // Make sure root logger is initialized ahead of FS mock
diff --git a/plugins/techdocs-node/src/stages/publish/local.test.ts b/plugins/techdocs-node/src/stages/publish/local.test.ts
index 7a1832d0b3..4019f80d11 100644
--- a/plugins/techdocs-node/src/stages/publish/local.test.ts
+++ b/plugins/techdocs-node/src/stages/publish/local.test.ts
@@ -17,7 +17,7 @@ import {
   getVoidLogger,
   PluginEndpointDiscovery,
 } from '@backstage/backend-common';
-import { createPackagePathMock } from '@backstage/backend-common/testUtils';
+import { overridePackagePathResolution } from '@backstage/backend-common/testUtils';
 import { ConfigReader } from '@backstage/config';
 import express from 'express';
 import request from 'supertest';
@@ -46,8 +46,8 @@ const testDiscovery: jest.Mocked<PluginEndpointDiscovery> = {
 
 const mockPublishDir = createMockDirectory();
 
-createPackagePathMock({
-  name: '@backstage/plugin-techdocs-backend',
+overridePackagePathResolution({
+  packageName: '@backstage/plugin-techdocs-backend',
   paths: {
     'static/docs': mockPublishDir.path,
   },