Allow definition of mock requestMIDIAccess function as a WebMidi.enable() option

[jjeff]

It looks like Jazz's web-midi-test package would be a great way to mock MIDI sources and destinations for E2E testing. It appears to mock the navigator.requestMIDIAccess() function and allows the definition of virtual MIDI sources and destinations. I'm guessing that it works similar to the JZZ package, emulating the browser's Web MIDI API and routing it to virtual devices rather than JZZ's node implementation.

WebMidi.js currently contains this code:

if (Utilities.isNode) {

  // Some environments may have both Node.js and browser runtimes (Electron, NW.js, React Native,
  // etc.) so we also check for the presence of the window.navigator property.
  try {
    window.navigator;
  } catch (err) {
    let jzz;
    eval('jzz = require("jzz")');
    global["navigator"] = jzz;
  }

}

...which might lead us to belive that we could just do something similar to web-midi-test's example of:

var WMT = require('web-midi-test');
var navigator = { requestMIDIAccess: WMT.requestMIDIAccess };

// maybe something like this:
global['navigator'] = navigator
// or maybe...
if (window && window.navigator) {
  window.navigator.requestMIDIAccess = WMT.requestMIDIAccess
}

However, in the case of E2E test, the navigator global is there. We just want to use a DIFFERENT requestMIDIAccess() function. I don't believe that we can overwrite the requestMIDIAccess function. So what if there was a property of requestMIDIAccessFunction as a property of WebMidi.enable(options). So the code would look something like this:

const WMT = require('web-midi-test');
const {WebMidi} = require('webmidi');

const input = new WMT.MidiSrc('My Mock Source');
input.connect()
const output = new WMT.MidiDst('My Mock Destination');
output.connect()

WebMidi.enable({ sysex: true, requestMIDIAccessFunction: WMT.requestMIDIAccess }).then(() => {
  // 👨‍🎤🎸🥁
})

I intentionally picked the name requestMIDIAccessFunction because it's big and awkward and scary looking... and hopefully people will avoid it if they don't know what it is. 🙂

Internally, you'd do something like this in WebMidi.js:

   // Request MIDI access (this iw where the prompt will appear)
    try {
      const requestMIDIAccessFunction = options.requestMIDIAccessFunction | navigator.requestMIDIAccess
      this.interface = await requestMIDIAccessFunction(
        {sysex: options.sysex, software: options.software}
      );
    } catch(err) {
   ...

Thoughts?

[djipco]

This makes sense. However, we would need to check whether web-midi-test creates a whole bunch of objects in the global.navigator namespace just like jzz does. The jzz module adds a lot more than requestMIDIAccess inside the navigator object. It's a bit messy in that regard. If it does create all those objects, we will have to figure out which ones need to be overwritten as well. Also, we need to think about Node.js developers who use "type": "modules" in their config (hence relying on the ESM version).

A bit of back story: unit tests for the library use a module called midi. It is a wrapper for the full fledged RtMidi C++ library. When it was chosen, web-midi-test (which is made by the same people who make jzz) did not exist yet.

[jjeff]

web-midi-test has other properties such as sysex and midi booleans to configure how its requestMIDIAccess() function will react (when asking for permission for those things). It also has classes to add a new MidiSrc or MidiDst to create new MIDI inputs and outputs. But the library does not appear to be altering the navigator object... or any other globals on its own.

With the e2e testing scenario, there will be an existing navigator object... with its own requestMidiAccess() function. We don't want to break the existing window.navigator. But for testing, we want to mock some virtual MIDI input/output devices to send data from/to. So instead of replacing the navigator object, we just need to re-route to a different requestMIDIAccess() function... which will deliver a different MidiAccess object, with mocked (and controllable) MIDIAccess.inputs and MIDIAccess.outputs.

I see that you're using JZZ's .close() method during WebMIDI.disable(). That shouldn't present any problems with my method. If the navigator object hasn't been altered, JZZ's close() method won't be there... so it won't get called. Of course, I haven't actually tried this yet. 🙂

I suppose this would/could also be a great way to run the unit tests for WebMidi.js. Native libraries such as RtMidi can be such a pain to manage in a cross-platform testing environment.

[djipco]

I suppose this would/could also be a great way to run the unit tests for WebMidi.js. Native libraries such as RtMidi can be such a pain to manage in a cross-platform testing environment.

I only tried running the tests on macOS but the midi module is said to run fine on Windows and GNU/Linux also. However, like you said, we probably would have less chances of running into issues using web-midi-test. Having said that, I don't really have the bandwidth right now to convert the unit tests to web-midi-test. I did jot it down in the Ideas & Suggestions to Evaluate page of the website.