Well, that's actually the "limitation" this plugin tries to workaround. ES modules don't allow the modification of named imports or members of a namespace import.

When trying to re-assign a named import, the user agent throws with:

import { getCurrentHour } from 'time-library';

getCurrentHour = () => 5; // Uncaught TypeError: Assignment to constant variable.

When trying to re-assign a member of a namespace import:

import *  as timeLibrary from 'time-library';

timeLibrary.getCurrentHour = () => 5; // Uncaught TypeError: Cannot assign to read only property 'getCurrentHour' of object '[object Module]'

More info on this designed "limitation":

• https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/import#imported_values_can_only_be_modified_by_the_exporter
• https://eslint.org/docs/latest/rules/no-import-assign
• Case for module mocking for testing WICG/import-maps#131

interesting, what kind of magic did I have in my recent test setup that allowed me to do this kind of stuff without running into this exception :D

but you are right, good proposal!

Hi Joe,

First off, thanks for reacting! 😃

I agree, import maps would be a great way to intercept modules for mocking. My first trials were actually using import maps (instead of a resolution hook). I was able to intercept modules just fine, and was using scopes to make sure to be able to retrieve the original implementation.

<script type="importmap">
  {
     "scopes": {
       "/src/": {
         "time-library": "./test/time-library.mock.js"
       }
     }
  }
</script>

// ./test/time-library.mock.js
import { getCurrentHour as _getCurrentHour} from 'time-library';

export function getCurrentHour() {
  return (_getCurrentHour() + 12) % 24; // dummy mock that moves time with 12 hours
}

And indeed, in this case, the interception is defined in the config (using a custom plugin, or the importMapsPlugin) in order to have the import map injected in the HTML. So all was going fine.

The problems arise when scaling up this solution in a real life project with many tests. And the main cause for them is the static ./test/time-library.mock.js file. Some of the problems encountered:

• It's not possible to change the implementation of the mocked getCurrentHour() between multiple tests in the same test file. This is a big one. It would mean people need to split all their tests in different test files in order to use a specific mock in their test.
• Having the mocked function in a separate file next to the test file is quite inconvenient. Usually when mocking, mocks are added during the arrange stage of a test (eg. https://medium.com/@pjbgf/title-testing-code-ocd-and-the-aaa-pattern-df453975ab80) Having another way to do this, will throw off a lot of devs, as they are used to doing it within the test (using the AAA pattern or different)
• As the complete module is intercepted, all other used methods of the library need to be mocked or rewired as well. This makes creating these static stubs a lot more cumbersome. There is more boilerplate code that needs to be created and maintained by hand. This seems trivial, but a lot of devs are not looking forward to creating (ormaintaining) tests. So, making it easy to create mocks, is worth it, as it will make the maintenance of tests a lot easier.

Now, this being said, most of these problems can be solved by using import maps in the backend of a plugin (as the module intercepting technology), having the mock files being generated automatically and having syntactic sugar within the test (like in the proposal) to make intercepting modules more straightforward. There is a downside however. Import maps cannot be added/changed on a page during module execution. This means that a user would need to add additional plugin config to define (upfront) what modules need to be intercepted for each test file. This adds complexity in the setup of tests.
This is on top of the additional complexity of using import maps in the plugin backend:

• the plugin needs to transform the html of the test run to add the import map (similar to the importMapsPlugin) to point to dynamic mock files on new (dynamic) urls
• the plugin needs to serve those dynamically created mock files on the new dynamic urls

This is why the proposal is using the resolution hook in order to simplify the implementation of the interception. As an added benefit it solves the need of defining upfront (in an additional config) what modules need to be intercepted: additional resolution hooks can be defined during a test run.
It would be great to switch back to import maps once dynamic import maps get supported (https://github.com/WICG/import-maps#programmatic-api). In the mean time resolution hooks are pretty common in backend JS systems:

• https://nodejs.org/docs/latest-v21.x/api/module.html#resolvespecifier-context-nextresolve
• https://rollupjs.org/plugin-development/#resolveid
• https://webpack.js.org/api/resolvers/

So, porting this to other systems should be pretty straightforward, if needed. 😃

I hope this gives more insight as to the choice of a resolution hook was made.

Ah, I see! Thanks for painting a more detailed picture. That makes sense. I suppose my tests haven't gotten complex enough for me to feel those pain points yet!

Then what you've made looks very nifty from a usage perspective.

Could this be implemented in vanilla ES Modules somehow, with help of a service worker? What I'm wondering is, if Module objects returned from import() are not writable, is it even possible? Does wtr/puppeteer have special abilities to patch modules that we otherwise don't have in a normal browser env?

Could this be implemented in vanilla ES Modules somehow

Yes, the complete proposal is implemented using vanilla ES Modules (the test runner plugin, the code of the module facade, and the test helper that retrieves the mutable object)

with help of a service worker

Briefly looked at it some time ago, but saw a couple of hurdles:

• Only one service worker can be installed per path. With the introduction of @web/mocks (using MSW), a service worker will already be active while testing. It felt complex to start juggling between multiple service workers.
• The interception would work differently. Instead of changing the initial resolution (allowing the original module url to be accessed), the service worker will probably need to add the proxy code as part of the original module (ie. patching it). This could create code conflicts.
• Managing the lifecycle of a service worker would require extra code to make sure it is correctly cleaned up

But as such, just like import maps, if service workers seem to be a better fit, the resolution hook technique could be replaced by a service worker. What do you think, @thepassle?

What I'm wondering is, if Module objects returned from import() are not writable, is it even possible

It's possible by using the same technique as the current proposal: having a special named export that exposes a (proxy) object that can override the exports. The issue is that it will probably need to be added to the original module (as opposed to the proposal where we change the resolution to a new dynamically created module)

Does wtr/puppeteer have special abilities to patch modules that we otherwise don't have in a normal browser env?

Using the resolution hook, it is possible to patch the modules that require the import. So, in the proposal, we actually leave the module to intercept alone. And this is not available in a normal browser afaik, except with import maps.

Im not sure if doing this in a service worker actually benefits anything, so im fine doing it in a plugin.

We can make the mock service worker combined with logic from another service worker, but it would indeed be more complex, because you'd need cross-plugin communication to combine the logic of plugins that use a service worker.

Service worker lifecycle shouldnt be a problem, as evidenced by usage of msw via @web/mocks

A draft PR has been created #2546. You can already check out the code there. Tests and readme still need to be updated.