chore: implement experimental ESM stub/spy for Vite

[lmiller1990]

• Closes https://github.com/cypress-io/cypress-internal/issues/564

Additional details

First release of our Vite plugin to facilitate spy/mock on ES modules.

I made this chore since

1. It's still a POC and has known issues
2. I want it to say below v1 until we've tested it more with some of the pilot users

Not sure the best way to handle this, but chore should only increment the patch number.

Steps to test

This is based on the PROPOSAL section from the tech brief: https://github.com/cypress-io/engineering-documentation/tree/main/tech-briefs/ct-esm-mocks#proposal. That explains what's going on here in detail.

It's complicated, don't feel you like need 100% understand it all when you review it.

Testing: Run the test suite! Or make a new Vite project that uses ES Modules and write some tests using cy.spy and cy.stub. The things in our documentation for cy.stub() and cy.spy() should work correctly with ES modules. There's a bunch of tests in this PR demonstrating it works (mostly, sans the caveats in the README).

There are some caveats, I wrote those in the README.

How has the user experience changed?

You can spy/mock ES modules (both static and dynamic imports).

PR Tasks

• Have tests been added/updated?
• [na] Has a PR for user-facing changes been opened in cypress-documentation?
• [na] Have API changes been updated in the type definitions?

[lmiller1990]

I found a bug. Comment: muratkeremozcan/tour-of-heroes-react-vite-cypress-ts#103 (comment)

Something in our logic is preventing prototype based inheritance working correctly, I think... I reproduced it and added a test using the react-query library. Details below, but before that, I tried side stepping the one module (react-query) that was giving me issues:

  // Check if it is the offending module - don't proxify
  if ('useQueryErrorResetBoundary' in module) {
    return module
  }

This works - test runs fine. Instead of proxifying every module, we could do a pre-scan of the spec and only apply the proxy logic to things matching cy.stub() or cy.spy(), maybe using a regexp like cy\.(spy|stub)\((.+?). This would not work if the user wants to stub/spy a library that doesn't work with our Proxy logic - we don't really know how common those libraries are yet.

Onto my debugging:

I tracked the code down. The error is on the line this.options = this.client.defaultMutationOptions(options) , which is called here. It says defaultMutationOptions is not a function. This is supposed to be inherited from the clientQuery class, it is defined here.

I added a minimal test using class and basic inheritance - works great. Eg:

class Animal {
  voice : string = 'Hello'
  greet() {
    return this.voice
  }
}

export class Dog extends Animal {
  constructor(voice: string) {
    super()
    this.voice = voice
  }
}

new Dog('bark').greet() // works great

The issue is, I think the type of code generated when react-query is compiled. It spits out:

import _inheritsLoose from "@babel/runtime/helpers/esm/inheritsLoose";
import { Subscribable } from './subscribable';

export var MutationObserver = /*#__PURE__*/function (_Subscribable) {
  _inheritsLoose(MutationObserver, _Subscribable);

  function MutationObserver(client, options) {
    var _this;

    _this = _Subscribable.call(this) || this;
    _this.client = client;

    _this.setOptions(options);

    return _this;
  }

  var _proto = MutationObserver.prototype;

  _proto.setOptions = function setOptions(options) {
    this.options = this.client.defaultMutationOptions(options);
  };

  return MutationObserver;
}(Subscribable);

Which seems to not play nicely with our proxy code. After some debugging, the MutationObserver is supposed to have a Subscribable prototype, but after the proxy code runs, it does not have the correct prototype, it has Object.

I need to debug more, but it's not clear if 1) we've hit an actual limitation of what proxy can do or 2) if we can fix this. I suspect we should not be using Object but Reflect in general, which has more powerful introspection APIs.

[marktnoonan]

This worked well for me in testing, I've left a few minor, non blocking comments in the review and some suggestions for the readme.

[marktnoonan]

Plot twist 😆

[marktnoonan]

Nit: Always a bit odd to me when there's a nested describe at the top, since Cypress runs this at the bottom, after the it blocks below this. We could move this to the bottom, or wrap the tests below in their own describe block. Purely so it's easier to open the file and have the order in the command log be similar to the source order.

[marktnoonan]

I find it hard to follow Foo/Bar/Bax examples, they don't give much context for what I should expect the classes to do and I lose track of them quite quickly. Not a blocker ofc.

[marktnoonan]

Is there a reason we ignore this rule here? We say Synchronous fs calls should not be used in Cypress. Use an async API instead. so might worth commenting using readFileSync because x.

[astone123]

Nice, hopefully we can move this into vite-dev-server once we get more feedback from users 👍🏻