[heft-jest] (BREAKING CHANGE) Use slash-normalized relative paths for asset URLs (#5175)

* [heft-jest] Use slash-normalized relative paths for asset URLs

* Update doc on transform

* Use `rootDir` instead of `cwd`

---------

Co-authored-by: David Michon <[email protected]>

Author: dmichon-msft

build-tests/heft-webpack5-everything-test/src/chunks/image.d.png.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+declare const path: string;
+
+export default path;

build-tests/heft-webpack5-everything-test/src/test/Image.test.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import image from '../chunks/image.png';
+
+describe('Image Test', () => {
+  it('correctly handles urls for images', () => {
+    expect(image).toBe('lib-commonjs/chunks/image.png');
+  });
+});

build-tests/heft-webpack5-everything-test/tsconfig.json

@@ -5,7 +5,10 @@
     "outDir": "lib",
     "rootDir": "src",
 
+    "allowArbitraryExtensions": true,
     "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
     "jsx": "react",
     "declaration": true,
     "sourceMap": true,

common/changes/@rushstack/heft-jest-plugin/main_2025-03-31-23-18.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-jest-plugin",
+      "comment": "(BREAKING CHANGE) Update `jest-string-mock-transform` to emit slash-normalized relative paths to files, rather than absolute paths, to ensure portability of snapshots.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-jest-plugin"
+}

heft-plugins/heft-jest-plugin/includes/jest-shared.config.json

@@ -60,7 +60,7 @@
   "transformIgnorePatterns": ["\\.c?js$"],
 
   // jest-identity-mock-transform returns a proxy for exported key/value pairs, where Webpack would return a module
-  // jest-string-mock-transform returns the filename, where Webpack would return a URL
+  // jest-string-mock-transform returns the filename, relative to the current working directory, where Webpack would return a URL
   // When using the heft-jest-plugin, these will be replaced with the resolved module location
   "transform": {
     "\\.(css|sass|scss)$": "../lib/exports/jest-identity-mock-transform.js",

heft-plugins/heft-jest-plugin/src/transformers/StringMockTransformer.ts

@@ -1,8 +1,10 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
-
+import { relative } from 'node:path';
 import type { SyncTransformer, TransformedSource, TransformOptions } from '@jest/transform';
 
+const isWindows: boolean = process.platform === 'win32';
+
 /**
  * This Jest transform handles imports of data files (e.g. .png, .jpg) that would normally be
  * processed by a Webpack's file-loader. Instead of actually loading the resource, we return the file's name.
@@ -11,9 +13,13 @@ import type { SyncTransformer, TransformedSource, TransformOptions } from '@jest
  */
 export class StringMockTransformer implements SyncTransformer {
   public process(sourceText: string, sourcePath: string, options: TransformOptions): TransformedSource {
-    // For a file called "myImage.png", this will generate a JS module that exports the literal string "myImage.png"
+    // heft-jest-plugin enforces that config.rootDir will always be the project root folder.
+    const relativePath: string = relative(options.config.rootDir, sourcePath);
+    const normalizedRelativePath: string = isWindows ? relativePath.replace(/\\/g, '/') : relativePath;
+    // For a file called "myImage.png", this will generate a JS module that exports the slash-normalized relative
+    // path from the current working directory to "myImage.png"
     return {
-      code: `module.exports = ${JSON.stringify(sourcePath)};`
+      code: `module.exports = ${JSON.stringify(normalizedRelativePath)};`
     };
   }
 }