This is the pluggable core of node-tap.
The TestBase
class has the basic flow-control and child-test
aspects of a tap Test
object, but only the t.pass()
and
t.fail()
assertions.
All other assertions and features are added via plugins.
Tap plugins are a function that takes a Test
object and an
options
object, and returns an object that is used as the
extension.
For example, to add a isString
method to all tests, you could
define a plugin like this:
import { TestBase, TapPlugin, AssertionOpts } from '@tapjs/core'
const plugin: TapPlugin = t => {
return {
isString: (
s: any,
msg: string = 'expect string',
extra: AssertionOpts = {}
) => {
// note: 'this' here is the plugin object
if (typeof s === 'string') {
return t.pass(msg)
} else {
return t.fail(msg, {
...extra,
expect: 'string',
actual: typeof s,
})
}
}
}
export default plugin
The object returned by a plugin can be any sort of thing. If you
want to use a class with private properties, that's totally fine
as well. Whatever type is expected as the second argument will
be combined with the built-in TestBaseOpts
interface, and
required when tests are instantiated.
import { TestBase, TapPlugin, AssertionOpts } from '@tapjs/core'
import { cleanup, render } from '@testing-library/react'
import { ReactElement } from 'react'
import { RenderResult } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
class ReactTest {
#result: RenderResult
constructor (node: ReactElement) {
this.#result = render(node)
}
findByText(text: string) {
return this.#result.findByText(text)
}
// add other helpful methods here...
}
const plugin: TapPlugin = (t, { node: ReactElement }) => {
return new ReactTest(node)
}
export default plugin
When loaded, this plugin would make it so that every test must
supply a { node: ReactElement }
option, and would have a
t.findByText()
method.
The easiest way to load plugins is by running:
tap plugin add <package or local module>
This will also regenerate the Test class, so types are kept in sync.
Remove plugins with tap plugin remove <plugin>
.
Plugins are specified in the plugins
array of the root tap
config. That is, either .taprc
in the project directory, or
the "tap"
stanza in the package.json
file.
Whenever the plugins
option is changed, you must run tap generate
to generate the Test
class properly. This is done
automatically on demand when running tap
or tap run [...files]
, but its often a good idea to do so before writing
tests so that editor hinting is accurate.
Out of the box, tap comes with the following plugins loaded:
@tapjs/assertions
All other assertions, liket.match()
,t.type()
,t.has()
, and so on.@tapjs/snapshot
Providing thet.matchSnapshot()
method.@tapjs/mock
Providing thet.mock()
method.@tapjs/fixture
Providing thet.testdir()
method.
To prevent loading any of these plugins, you can include them
in the plugins
config, prefixed with a !
. For example, if
you wanted to replace t.mock()
with a different mocking plugin,
you could do this:
{
"tap": {
"plugins": [
"!@tapjs/mock",
"my-mock-plugin
]
}
}