How to create a custom Plugin

[Tarrask]

Hi, I'm trying to migrate from tap 16 to tap 18.

One problem that I'm facing is that I had a custom Assert that was added to the Test.prototype. As I understand, this is not valid anymore and I have to create a plugin to register this custom assertion.

So I create a new file myAssert.ts on the root of my project, copy the code from documentation: very simple "hello, world" plugin and try to register it in the tap engine.

In the REPL, I type plugin add ./myAssert.ts but this didn't work, tap can not found the file, I finally found that plugin add ../../../myAssert.ts works a bit better, but I found that path a bit sketchy, is that the way to do?

But it still not work, I got a first error:

'../../../myAssert.ts' does not appear to be a tap plugin. Could not load module with require(). ⨯ Unable to compile TypeScript:
myAssert.ts:5:14 - error TS2322: Type '(t: TestBase) => { hello: (who?: string) => void; }' is not assignable to type '(t: TestBase) => HelloSayer'.
  Call signature return types '{ hello: (who?: string) => void; }' and 'HelloSayer' are incompatible.
    The types returned by 'hello(...)' are incompatible between these types.
      Type 'void' is not assignable to type 'string'.

5 export const plugin: TapPlugin<HelloSayer> = (t: TestBase) => {
               ~~~~~~

I fix this error by returning a string, I guess this is an error in the doc.

After that I got a second error:

'../../../myAssert.ts' does not appear to be a tap plugin. When loaded with import(), must export at least one of: a plugin function, config object, loader module identifier, or importLoader module identifier. Got: plugin

And here I'm clueless, is it possible to create a custom plugin? Is it mandatory to create it in is own package and publish it to NPM? Is there a better way to create a custom assert?

Here is the content of myAssert.ts:

import { TapPlugin, TestBase } from '@tapjs/core'
export interface HelloSayer {
  hello: (who?: string) => string
}
export const plugin: TapPlugin<HelloSayer> = (t: TestBase) => {
  return {
    hello: (who: string = 'world') => {
      console.error(`${t.name} says "Hello, ${who}!"`)
      return 'hello'
    },
  }
}

[isaacs]

In order to preserve the behavior of tap working with both ESM and CommonJS, all plugins have to be able to be loaded with both require and import.

You don't have to publish it to npm, but it does have to be a thing in node_modules with the exports set up properly. tshy is an easy way to do this, plus if you write it in TS then the plugin type signatures will be preserved in the built Test class.

Whatever is the type provided to the TapPlugin<T> parameter has to be what the plugin function returns. It can be void or string or whatever, but has to match. You can also just let TS infer the parameter and not provide it, so this would work:

import { TapPlugin } from '@tapjs/core'
export const plugin: TapPlugin = (t) => {
  return {
    hello: (who: string = 'world') => {
      console.error(`${t.name} says "Hello, ${who}!"`)
    },
  }
}

To be honest, if you don't need to hook into the test lifecycle stuff or provide an interface to something that's "big" enough to justify being its own package, it may often be a better idea to just define a function that takes a Test as an argument.

// test/fixtures/utils.ts
import { Test } from 'tap'
export const hello = (t: Test, who: string = 'world') =>
  console.error(`${t.name} says "Hello, ${who}!"`)

// test/whatever.ts
import t from 'tap'
import { hello } from './fixtures/utils.js'
t.test('hello sayer', t => {
  hello(t, 'universe')
  t.end()
})

[Tarrask]

HI thank you for your answer.

As you said, a plugin is maybe not the solution to my problem, what I was trying to do is to locate the failed test in the test file instead of the helper function. I used to do that by using addAssert from the Test prototype and at extra parameter.

I finally managed to do that with a simple helper function as you suggest, using the @tapjs/stack package at function, so I guess I've solved my issue. Thank you for you help.

Here is the code of an helper function that I'll use:

const stack = require('@tapjs/stack')

function hello (t, found, wanted) {
  const at = stack.at(hello)
  t.same(found, wanted, 'error here', { at })
}

module.exports = { hello }