docs(test-runner-module-mocking): ✏️ test-moduleMocking details on plugin import order

Adding details on the order of plugin import in test config. Module
mocking must be in first position to avoid conflict with modified path
due to other plugins. + refactoring

Author: mservaising

.changeset/sixty-maps-call.md

@@ -0,0 +1,7 @@
+---
+'@web/test-runner-module-mocking': patch
+---
+
+Add docs on plugin import order to avoid conflict with other plugins  
++ refactoring
++ using sinon dependency for new test using stub

package-lock.json

@@ -38,6 +38,8 @@ export default {
 };
 ```
 
+Take care of the plugins order, some plugins can modify path of imported modules and moduleMockingPlugin may be not able to retreive them correctly, so it's advise to use it first in the list.
+
 ### Simple test scenario
 
 ```js

packages/test-runner-module-mocking/README.md

@@ -53,6 +53,7 @@
   },
   "devDependencies": {
     "@web/test-runner-chrome": "^0.15.0",
-    "@web/test-runner-core": "^0.13.0"
+    "@web/test-runner-core": "^0.13.0",
+    "sinon": "^17.0.1"
   }
 }

packages/test-runner-module-mocking/package.json

@@ -15,7 +15,7 @@ export type ResolveImport = (
 ) => ResolveResult | Promise<ResolveResult>;
 
 /**
- * TODO: check if `resolveImport()` can be provied by `@web/dev-server-core`'s API
+ * TODO: check if `resolveImport()` can be provided by `@web/dev-server-core`'s API
  * @param args start param args
  * @param thisPlugin plugin to exclude
  */

packages/test-runner-module-mocking/src/createResolveImport.ts

@@ -37,15 +37,37 @@ export function moduleMockingPlugin(): Plugin {
           const namedExports = exports.map(e => e.n).filter(n => n !== 'default');
           const hasDefaultExport = exports.some(e => e.n === 'default');
 
-          body = `
+          body = generateInterceptedModuleBody(body, url, namedExports, hasDefaultExport);
+        }
+      } catch (error) {
+        // Server side errors might contain ANSI color escape sequences.
+        // These sequences are not readable in a browser's console, so we strip them.
+        const errorMessage = stripColor((error as Error).message).replace(/'/g, "\\'");
+        body = `export const __wtr_error__ = '${errorMessage}';`;
+      }
+
+      return body ? { body, type: 'text/javascript' } : undefined;
+    },
+
+    resolveImport({ source, context }) {
+      if (context.path === '/__intercept-module__') {
+        absolutePaths.push(source);
+      } else if (absolutePaths.includes(source)) {
+        return `${source}?intercept-module`;
+      }
+      return undefined;
+    },
+  };
+
+  function generateInterceptedModuleBody(body: any, url: URL, namedExports: string[], hasDefaultExport: boolean) {
+    body = `
           import * as original from '${url.pathname}';
           const newOriginal = {...original};
 
           ${namedExports.map(x => `export let ${x} = newOriginal['${x}'];`).join('\n')}
 
-          ${
-            hasDefaultExport
-              ? `
+          ${hasDefaultExport
+        ? `
           function computeDefault() {
             if(typeof newOriginal.default === 'function'){
               return (...args) => newOriginal.default.call(undefined, ...args);
@@ -55,8 +77,7 @@ export function moduleMockingPlugin(): Plugin {
 
           export default computeDefault()
           `
-              : ''
-          }
+        : ''}
 
           export const __wtr_intercepted_module__ = new Proxy(newOriginal, {
             set: function(obj, prop, value) {
@@ -69,24 +90,6 @@ export function moduleMockingPlugin(): Plugin {
             },
           });
         `;
-        }
-      } catch (error) {
-        // Server side errors might contain ANSI color escape sequences.
-        // These sequences are not readable in a browser's console, so we strip them.
-        const errorMessage = stripColor((error as Error).message).replace(/'/g, "\\'");
-        body = `export const __wtr_error__ = '${errorMessage}';`;
-      }
-
-      return body ? { body, type: 'text/javascript' } : undefined;
-    },
-
-    resolveImport({ source, context }) {
-      if (context.path === '/__intercept-module__') {
-        absolutePaths.push(source);
-      } else if (absolutePaths.includes(source)) {
-        return `${source}?intercept-module`;
-      }
-      return undefined;
-    },
-  };
+    return body;
+  }
 }

packages/test-runner-module-mocking/src/moduleMockingPlugin.ts

@@ -0,0 +1,3 @@
+export function getCurrentHour() {
+  return 2;
+}

packages/test-runner-module-mocking/test/fixtures/server-relative-with-stub/fixture/src/flow/libs/time-library.js

@@ -0,0 +1,9 @@
+import { getCurrentHour } from '../libs/time-library.js';
+
+export function getTimeOfDay() {
+  const hour = getCurrentHour();
+  if (hour < 6 || hour > 18) {
+    return 'night';
+  }
+  return 'day';
+}

packages/test-runner-module-mocking/test/fixtures/server-relative-with-stub/fixture/src/flow/step/getTimeOfDay.js

@@ -0,0 +1,33 @@
+import { expect } from '../../../chai.js';
+import sinon from 'sinon' 
+import { importMockable } from '../../../../../browser/index.js';
+
+const path = new URL(import.meta.resolve('../../fixture/src/flow/libs/time-library.js')).pathname;
+const timeLibrary = await importMockable(path);
+const { getTimeOfDay } = await import('../../fixture/src/flow/step/getTimeOfDay.js');
+
+let backup;
+it('can run a module normally', () => {
+  backup = timeLibrary.getCurrentHour;
+  const timeOfDay = getTimeOfDay();
+  expect(timeOfDay).to.equal('night');
+});
+
+it('can intercept a module', () => {
+  timeLibrary.getCurrentHour = () => 12;
+  const timeOfDay = getTimeOfDay();
+  expect(timeOfDay).to.equal('day');
+});
+
+it('can restore an intercepted module', () => {
+  timeLibrary.getCurrentHour = backup;
+  const timeOfDay = getTimeOfDay();
+  expect(timeOfDay).to.equal('night');
+});
+
+it('can have stub applied on intercepted module', () => {
+  const stub = sinon.stub(timeLibrary, 'getCurrentHour').returns(15)
+  const timeOfDay = getTimeOfDay();
+  expect(timeOfDay).to.equal('day');
+  expect(stub.calledOnce).to.be.true;
+});