refactor(mocking-modules): rename the project

Author: tmsns

.changeset/loud-zebras-joke.md

@@ -1,5 +1,5 @@
 ---
-'@web/test-runner-intercept': patch
+'@web/test-runner-module-mocking': patch
 ---
 
-initial commit of @web/test-runner-intercept
+initial commit of @web/test-runner-module-mocking

package-lock.json

@@ -33,7 +33,7 @@
     "start:build": "node packages/dev-server/dist/bin.js --root-dir _site --open",
     "test": "npm run test:node && npm run test:browser && node scripts/workspaces-scripts-bin.mjs test:ci",
     "test:browser": "npm run test:browser --workspaces --if-present",
-    "test:node": "mocha \"packages/!(*test-runner-selenium|*test-runner-webdriver|*test-runner-intercept)/test/**/*.test.{ts,js,mjs,cjs}\" && TS_NODE_PROJECT='./tsconfig.node-16-base.json' mocha \"packages/test-runner-intercept/test/**/*.test.{ts,js,mjs,cjs}\" --loader=ts-node/esm",
+    "test:node": "mocha \"packages/!(*test-runner-selenium|*test-runner-webdriver|*test-runner-module-mocking)/test/**/*.test.{ts,js,mjs,cjs}\" && TS_NODE_PROJECT='./tsconfig.node-16-base.json' mocha \"packages/test-runner-module-mocking/test/**/*.test.{ts,js,mjs,cjs}\" --loader=ts-node/esm",
     "types": "wireit",
     "update": "npm run update:mjs-dts-entrypoints && npm run update:tsconfigs",
     "update-dependency": "node scripts/update-dependency.js",

package.json

@@ -1,15 +1,19 @@
-# Web Test Runner Intercept
+# Web Test Runner Module Mocking
 
-Web test runner plugin that allows the interception of modules during test runs. Often, while creating tests, there is the need to change the behavior of a dependency of the system under test. This is needed to cover all branches of the system under test, for performance reasons or sometimes because the dependency cannot operate correctly in the test environment. Dependencies that are on the global window object are easy to change with a mock or a stub. ES Modules, however, and specifically their exports cannot be altered. This plugin introduces a hook that enables the interception of modules and allows altering its exports.
+Web Test Runner package that enables mocking of ES Modules during test runs.
 
 ## Concept
 
-Next to a web test runner plugin that enables module interception, this package also exposes a function `interceptModule()` to be used in the test run. This function allows to define what module needs to be intercepted and returns an object with all the exports of the module as its properties. Changing these properties allows to rewire the intercepted module without changing the system under test.
+A typical step when authoring tests is to change the behavior of dependencies of a system under test. This is usually needed to cover all branches of the system under test, for performance reasons or sometimes because a dependency cannot operate correctly in the test environment. Test authors will use mocks, stubs or spies to change or monitor the original implementation.
+
+Dependencies that are on the global window object are easy to change. ES Modules, however, and specifically their exports bindings cannot be reassigned. This package exposes a Web Test Runner plugin that can intercept module imports on the server. When a module is intercepted, the plugins injects extra code that allows reassigning its exports.
+
+Once the plugin is active in the Web Test Runner config, a test author can use the `importMockable()` function to start rewiring modules in test runs. The function imports the intercepted module and returns a mockable object. This objects contains all the exports of the module as its properties. Reassigning these properties allows rewiring the intercepted module, and the system under test will use the updated implementation.
 
 ```js
-import { interceptModule } from '@web/test-runner-intercept';
+import { importMockable } from '@web/test-runner-module-mocking';
 
-const externalLibrary = await interceptModule('external-library');
+const externalLibrary = await importMockable('external-library');
 
 // Return the original function that 'external-library' exposed in the `externalFunction` named export
 externalLibrary.externalFunction; // f externalFunction() { ... }
@@ -21,51 +25,13 @@ const { externalFunction } = await import('external-library');
 externalFunction; // () => console.log('hello world')
 ```
 
-### Caveats
-
-#### Order of imports
-
-In order to intercept a module, the module should not be referenced yet. (Once a module is loaded, the module loader also loads all its dependent modules) This means the module containing the system under test should be loaded _after_ the module interception. As interception is achieved using a function, this also means the system under test should _always_ be loaded using a dynamic import in order to be done after the interception.
-
-```js
-import { interceptModule } from '@web/test-runner-intercept';
-
-// First, intercept
-const externalLibrary = await interceptModule('external-library');
-
-// Second, load the system under test.
-const systemUnderTest = await import('../../src/system-under-test.js');
-
-// Run tests
-...
-```
-
-#### Types of module specifiers
-
-Currently, two types of module specifiers are supported: bare modules and server relative modules.
-
-```javascript
-// bare module, located in `node_modules`
-await interceptModule('external-library');
-
-// server relative module
-await interceptModule('/src/library-to-intercept.js');
-```
-
-In order to use regular relative references, `import.meta.resolve()` and `new URL().pathname` can be used.
-
-```javascript
-// relative module
-await interceptModule(new URL(import.meta.resolve('../src/library-to-intercept.js')).pathname);
-```
-
 ## Usage
 
 ### Setup
 
 ```js
 // web-test-runner.config.mjs
-import { interceptModulePlugin } from '@web/test-runner-intercept/plugin.js';
+import { interceptModulePlugin } from '@web/test-runner-module-mocking/plugin.js';
 
 export default {
   plugins: [interceptModulePlugin()],
@@ -89,9 +55,9 @@ export function getTimeOfDay() {
 
 ```js
 // test/getTimeOfDay.test.js
-import { interceptModule } from '@web/test-runner-intercept';
+import { importMockable } from '@web/test-runner-module-mocking';
 
-const timeLibrary = await interceptModule('time-library');
+const timeLibrary = await importMockable('time-library');
 const { getTimeOfDay } = await import('../src/getTimeOfDay.js');
 
 describe('getTimeOfDay', () => {
@@ -107,15 +73,15 @@ describe('getTimeOfDay', () => {
 
 ### Extended test scenario
 
-This scenario showcases how to use `@web/test-runner-intercept` together with `chai` and `sinon`.
+This scenario showcases how to use `@web/test-runner-module-mocking` together with `chai` and `sinon`.
 
 ```js
 // test/getTimeOfDay.test.js
 import { stub } from 'sinon';
 import { expect } from 'chai';
-import { interceptModule } from '@web/test-runner-intercept';
+import { importMockable } from '@web/test-runner-module-mocking';
 
-const timeLibrary = await interceptModule('time-library');
+const timeLibrary = await importMockable('time-library');
 const { getTimeOfDay } = await import('../src/getTimeOfDay.js');
 
 describe('getTimeOfDay', () => {
@@ -139,3 +105,41 @@ describe('getTimeOfDay', () => {
   });
 });
 ```
+
+## Caveats
+
+### Order of imports
+
+In order to intercept a module, the module should not be referenced yet. (Once a module is loaded, the module loader also loads all its dependent modules) This means the module containing the system under test should be loaded _after_ the module interception. As interception is achieved using a function, this also means the system under test should _always_ be loaded using a dynamic import in order to be done after the interception.
+
+```js
+import { importMockable } from '@web/test-runner-module-mocking';
+
+// First, intercept
+const externalLibrary = await importMockable('external-library');
+
+// Second, load the system under test.
+const systemUnderTest = await import('../../src/system-under-test.js');
+
+// Run tests
+...
+```
+
+### Types of module specifiers
+
+Currently, two types of module specifiers are supported: bare modules and server relative modules.
+
+```javascript
+// bare module, located in `node_modules`
+await importMockable('external-library');
+
+// server relative module
+await importMockable('/src/library-to-intercept.js');
+```
+
+In order to use regular relative references, `import.meta.resolve()` and `new URL().pathname` can be used.
+
+```javascript
+// relative module
+await importMockable(new URL(import.meta.resolve('../src/library-to-intercept.js')).pathname);
+```

packages/test-runner-intercept/browser/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Import a mockable version of a module to change its implementation.
+ * @param {string} moduleSpecifier The specifier of the module. Bare module specifiers and server relative specifiers are supported. Regular relative paths are not supported
+ * @returns {Promise<Record<string, func> | void >} Object with reassignable properties that match every export of the specified module.
+ * If the specified module contains a default export, the export will be available from the `default` property. Only function expressions are supported when rewiring default exports.
+ */
+export function importMockable(moduleSpecifier: string): Promise<Record<string, func> | void>;

packages/test-runner-intercept/browser/index.js

@@ -0,0 +1,26 @@
+/**
+ * Import a mockable version of a module to change its implementation.
+ * @param {string} moduleSpecifier The specifier of the module. Bare module specifiers and server relative specifiers are supported. Regular relative paths are not supported
+ * @returns {Promise<Record<string, func> | void >} Object with reassignable properties that match every export of the specified module.
+ * If the specified module contains a default export, the export will be available from the `default` property. Only function expressions are supported when rewiring default exports.
+ */
+export async function importMockable(moduleSpecifier) {
+  if (moduleSpecifier.includes('./')) {
+    throw new Error(
+      `Parameter \`moduleName\` ('${moduleSpecifier}') contains a relative reference. This is not supported. Convert \`moduleName\` first to a server relative path. (eg. \`new URL(import.meta.resolve(moduleName)).pathname\`)`,
+    );
+  }
+
+  let module;
+  try {
+    module = await import(`/__intercept-module__?${moduleSpecifier}`);
+  } catch (e) {
+    throw new Error(
+      `Module interception is not active. Make sure the \`interceptModulePlugin\` of \`@web/test-runner-module-mocking\` is added to the Test Runner config.`,
+    );
+  }
+  if (module.__wtr_error__) {
+    throw new Error(module.__wtr_error__);
+  }
+  return module.__wtr_intercepted_module__;
+}

packages/test-runner-intercept/test/fixtures/inexistent/browser-test.js

@@ -1,18 +1,18 @@
 {
-  "name": "@web/test-runner-intercept",
+  "name": "@web/test-runner-module-mocking",
   "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Plugin for intercepting modules in @web/test-runner",
+  "description": "Package to enable mocking modules in @web/test-runner",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/modernweb-dev/web.git",
-    "directory": "packages/test-runner-intercept"
+    "directory": "packages/test-runner-module-mocking"
   },
   "author": "modern-web",
-  "homepage": "https://github.com/modernweb-dev/web/tree/master/packages/test-runner-intercept",
+  "homepage": "https://github.com/modernweb-dev/web/tree/master/packages/test-runner-module-mocking",
   "main": "browser/index.js",
   "type": "module",
   "exports": {
@@ -48,8 +48,10 @@
     "runner",
     "testrunner",
     "module",
-    "interception",
-    "intercept"
+    "intercept",
+    "mock",
+    "stub",
+    "spy"
   ],
   "dependencies": {
     "@web/dev-server-core": "^0.7.0",

packages/test-runner-intercept/test/fixtures/relative/browser-test.js

@@ -1,7 +1,7 @@
 import { expect } from '../chai.js';
-import { interceptModule } from '../../../browser/index.js';
+import { importMockable } from '../../../browser/index.js';
 
-const timeLibrary = await interceptModule('time-library/hour');
+const timeLibrary = await importMockable('time-library/hour');
 const { getTimeOfDay } = await import('./fixture/getTimeOfDay.js');
 
 let backup;

packages/test-runner-intercept/README.md renamed to packages/test-runner-module-mocking/README.md

@@ -0,0 +1,3 @@
+import { importMockable } from '../../../browser/index.js';
+
+await importMockable('/inexistent-module.js');

packages/test-runner-module-mocking/browser/index.d.ts

@@ -0,0 +1,3 @@
+import { importMockable } from '../../../browser/index.js';
+
+await importMockable('./file.js');

packages/test-runner-module-mocking/browser/index.js

@@ -1,8 +1,8 @@
 import { expect } from '../chai.js';
-import { interceptModule } from '../../../browser/index.js';
+import { importMockable } from '../../../browser/index.js';
 
 const path = new URL(import.meta.resolve('./fixture/time-library.js')).pathname;
-const timeLibrary = await interceptModule(path);
+const timeLibrary = await importMockable(path);
 const { getTimeOfDay } = await import('./fixture/getTimeOfDay.js');
 
 let backup;

packages/test-runner-intercept/index.d.ts renamed to packages/test-runner-module-mocking/index.d.ts

@@ -101,7 +101,7 @@
       "path": "./packages/test-runner-browserstack/tsconfig.json"
     },
     {
-      "path": "./packages/test-runner-intercept/tsconfig.json"
+      "path": "./packages/test-runner-module-mocking/tsconfig.json"
     },
     {
       "path": "./packages/test-runner-junit-reporter/tsconfig.json"