docs: clarify that mockImport is "load with a mocked import" and not "mock the inported thing" about tapjs

[onosendi]

Ah, roger that.

[isaacs]

Actually, you know, "mock the imported thing" is a reasonable guess as to what a method named mockInport() does. Maybe the docs need to clarify this a bit better.

Reopening as a doc issue.

[isaacs]

it was especially confusing because I was coming from jest's jest.mock.

It's a matter of taste, so there's really no right or wrong answer per se, and the word "mock" is super overloaded in the testing space so it's a reasonable approach I guess, but personally I find jest's import mocking pretty confusing to reason about. It's sort of global, but not exactly, and feels very magical. Tap's import mocking is just a specific function that loads the actual module code, but with its dependencies injected with known values, so you can do the mocked import behavior in a clearer and more isolated scope.

It's also handy when you want to have a single test file that mocks things in a bunch of different ways, so eg you can load a module with { path: path.posix } and then a second time with { path: path.win32 } to test different branches, or just load the module fresh with different globals/env values, etc.

[isaacs]

I'd thought about naming it t.import(), probably would have made it more clear that it's "import this module (with some tweaked deps)". But the concern there was import { import } from 'tap' wouldn't work, you'd have this special keyword making footguns etc.

[isaacs]

That's not what mock import does.

It's for mocking the things that that module imports.

Example, if a.js imported b.js, you could do this:

// a.js
import { foo } from './b.js'
export { foo }

// b.js
export const foo = 'bar'

// a.spec.js
import t from 'tap'
const a = await t.mockImport('./a.js', {
  './b.js': {
    foo: 'baz'
  }
})
console.log(a.foo) // 'baz'

In other words, it's not "a thing that you import and then mock", it's "load this module, but with a mocked import() method".

If you just want to import something and then swap out some fields, check out t.capture and t.intercept.

For example:

import t from 'tap'

const a = await import('./a.js')
t.equal(a.foo, 'bar')
const fooAccesses = t.intercept(a, 'foo', { value: 'baz' })
t.equal(a.foo, 'baz')
console.error(fooAccesses) // [ { type: 'get', value: 'baz', ... } ]

[onosendi]

@isaacs it was especially confusing because I was coming from jest's jest.mock.

[onosendi]

Hmm, using your example gives me:

const fooAccesses = t.intercept(a, 'foo', { value: 'baz' });

Error: Cannot intercept property 'foo', defined {configurable:false}

import t from 'tap';

const a = await import('./a.js');
t.equal(a.foo, 'bar');
const fooAccesses = t.intercept(a, 'foo', { value: 'baz' });
t.equal(a.foo, 'baz');
console.error(fooAccesses);

[isaacs]

Oh, yeah, if a thing is {configurable:false} then there'd be no way to intercept it.

But you could always put it on a different object, and intercept that.

import t from 'tap';

const a = { ...(await import('./a.js')) };
t.equal(a.foo, 'bar');
const fooAccesses = t.intercept(a, 'foo', { value: 'baz' });
t.equal(a.foo, 'baz');
console.error(fooAccesses);