Method that will be called on snapshot strings. This can be used to remove transient run-specific data from snapshots using simple string transforms.
Options that will be used when formatting snapshots and diffing/comparing objects using any assertion methods.
Function that turns an object into a snapshot string.
By default tcompare!format is used. If a string is returned, then that string is the snapshot string. If any other type is returned, then the returned value will be formatted using tcompare!format.
Set whether the fixture should be saved or not
Must be set BEFORE calling @tapjs/fixture!index.TestFixtures#testdir, or it will not have any effect.
The file where snapshots will be written to and read from
In the worker thread, the worker data that was provided to the t.worker method.
In the main thread, this field is undefined.
Change the working directory, for the context of a single test.
Set some mocks that will be used for all subsequent @tapjs/mock!index.TapMock#mockImport and @tapjs/mock!index.TapMock#mockRequire calls made by this test.
Mocks added with mockAll are overridden by any explicit mocks set in the
t.mockRequire or t.mockImport call.
Repeated calls to t.mockAll() will add mocks to the set. If the same
name is used again, it will replace the previous value, not merge.
If a key is set to undefined or null, then it will be removed from
the mockAll set.
Reset by calling t.mockAll(null)
Call with no args to return the current mockAll object.
Optionalmocks: null | Record<string, any>Returns the error object if it throws and that does not fail the test (by virtue of being marked skip or todo). Otherwise returns the passing status, like other assertions.
Asserts that the emitter emits the specified event before the test ends. Returns a promise that resolves when the event is emitted. Note that waiting on the returned promise within a test can deadlock the test, if the event never emits, but the returned promise can be a handy way to pause a test until an event happens, if you are reasonably confident that it will fire.
Verify that the values are equal
Assert that an error object is not provided.
Like with @tapjs/asserts!index.Assertions#doesNotThrow, you can also usually just throw the error, and tap will handle that reasonably.
This is useful in cases where you just want to assert that a callback did not receive an error, without necessarily aborting the callback function entirely. Both the origin of the error and the location of the failed assertion will be printed in the test results.
It is also used internally in @tapjs/asserts!index.Assertions#resolves, @tapjs/asserts!index.Assertions#doesNotThrow, and @tapjs/asserts!index.Assertions#resolveMatch to show both the source of a raised error as well as the callsite where the assertion failed.
Verify that the object has all of the properties and values in the pattern, matching loosely.
Verify that the object has the wanted property, using Object#hasOwnProperty
Verify that the object has all of the properties listed in the
wanted list, using Object#hasOwnProperties()
Verify that the object has all of the properties listed in the
wanted list, using Object#hasOwnProperties(), and no others
Verify that the object has the wanted property, anywhere in its prototype chain.
Verify that the object has all of the properties in the wanted
list, anywhere in its prototype chain.
Verify that the value has all of the properties and values in the pattern, matching strictly.
Verify that the value matches the pattern provided
Verify that the value matches the pattern provided, with no extra properties.
Verify that the value matches the pattern provided, with no extra properties.
In --snapshot mode, takes a snapshot of the object provided, and writes
to the snapshot file.
Otherwise, reads the snapshot file, and verifies that a snapshot of the object provided matches the stored snapshot.
Verify that the value matches the pattern provided, but fail if any fields only match via type coercion.
For example,
t.matchStrict({ a: 1 }, { a: Number }, 'this passes')
t.matchStrict({ a: 1 }, { a: '1' }, 'this fails')
Verify that the values are not equal
Verify that the object does NOT have all of the properties and values in the pattern, matching loosely.
Verify that the value does NOT contain all of the properties and values in the test pattern, comparing strictly.
Note that this will pass if the value has some of the listed properties, or if they do not match the same type.
Verify that the value does NOT match the pattern provided.
Verify that the value does not match the pattern provided, with no extra properties. Ie, it might either not match, or have extra props.
Verify that the value does not match the pattern provided, with no extra properties. Ie, it might either not match, or have extra props.
Verify that the value does not match the pattern provided, without type coercion.
Verify that the value is not truthy
Verify that the value is not loosely equivalent to the supplied pattern
resolves to the error object rejected if it rejects as expected, 'false' if it does not, or 'true' if it fails to reject but is marked as skip/todo.
Test the resolved promise result with t.match()
Resolves to true if it passes, false if the promise rejects or the match fails, or the rejection error value if the promise rejects but the assertion passes by being marked todo/skip.
Resolve a promise, and verify that the resulting value matches the snapshot.
Resolves to 'true' if the promise resolves successfully, 'false' if it rejects and fails, or the rejection error if it rejects but the failure is accepted by by being marked todo or skip
Verify that the value is loosely equivalent to the supplied pattern
Verify that the value is not strictly equivalent to the supplied pattern object
Verify that the value is strictly equivalent to the supplied pattern
Verify that the function throws an error.
Thrown error is tested against the wanted param if provided, using
t.match().
Returns false on failure, or the error object thrown on success
Verify that the value is of the type specified Type can be either a string, or a constructor.
If a string, then it can match either the typeof result
or 'null' for null values, or the name property of the
object's constructor.
The name of the folder that this test will use with @tapjs/fixture!index.TestFixtures#testdir.
By default, it uses a folder name based on the name of the test file
and subtest, within .tap/fixtures in the root of the project.
Intercept calls to a method to track the arguments, call site, and return/throw status, and replace the implementation.
By default, the method is set to a no-op. To retain the method behavior, pass the current value of the method as the third argument. For example:
const results = t.capture(obj, 'foo', obj.foo)
Automatically restores at t.teardown() if the @tapjs/after
plugin is not disabled. Otherwise, it is important to call the
restore() method on the returned function when you are done capturing.
Just wrap the function and return it. Does not have any logic to restore, since it's not actually modifying anything. The results hang off the function as the 'calls' property.
The added fn.args() method will return an array of the arguments
passed to each call since the last time it was inspected.
Convenience method to create a mock from an existing object by overriding some (possibly deeply nested) methods or properties.
Example:
import * as fs from 'node:fs'
const mockedThing = t.mockRequire('./module.js', t.createMock(
{ fs },
{ fs: { statSync: myMockedStatSync }}
)
This can also appear anywhere in the object hierarchy, which may be more convenient in some cases:
import * as blah from '@long-name/blah-api'
const mockedThing = t.mockRequire('./module.js', {
fs: t.createMock(fs, { statSync: myMockedStatSync }),
child_process: t.createMock(child_process, { spawn: mockSpawn }),
'@long-name/blah-api': t.createMock(blah, {
some: {
nested: {
prop: true
}
}
})
})
To remove a property, set it as undefined in the override.
Create a fixture object for use in a @tapjs/fixture!index.TestFixtures#testdir method.
Intercept and track object property sets and gets.
If a PropertyDescriptor is set, then it will be used as the replacement value. Otherwise, the original descriptor will be used.
If the strictMode param is set, then attempts to write to read-only
properties will throw an error.
Deprecated alias for @tapjs/mock!index.TapMock#mockRequire
Prints a warning to stderr the first time it used, otherwise identical.
Optionalmocks: { [k: string]: any }Load the supplied module asynchronously using import(), replacing any of the referenced modules with the mocks provided.
Works with either ESM or CommonJS modules, but as with import() of
CommonJS modules, the module.exports value will be set as the
default property on the resolved object, making
@tapjs/mock!index.TapMock#mockRequire somewhat more intuitive in
those cases.
For type info, cast using as typeof import(...) or use the type
parameter, as TypeScript lacks a way to infer imports dynamically.
For example:
const myThing = await t.mockImport<
typeof import('../my-thing.js')
>('../my-thing.js', {
some: { tricky: 'mocks' },
})
Note: The terms "mock" and "import" are unfortunately very overloaded in the testing space. This is not "mock all imports of this module". It's "load this module, but with its imports mocked". The code of the target module is run normally, but its dependencies are injected with the supplied values, which is useful for triggering hard-to-reach error cases and other situations.
It is also useful for just loading a fresh copy of a module in your tests, if for example your program behaves differently based on environment variables or other system settings. For example:
t.test('windows behavior', async t => {
t.intercept(process, 'platform', { value: 'win32' })
const myThing = t.mockImport('../my-thing.js')
t.equal(myThing.separator, '\\')
})
t.test('posix behavior', async t => {
t.intercept(process, 'platform', { value: 'linux' })
const myThing = t.mockImport('../my-thing.js')
t.equal(myThing.separator, '/')
})
Optionalmocks: Record<string, any>Load the supplied module synchronously using require(),
replacing any of the referenced modules with the mocks provided.
Only works with CommonJS modules.
For type info, cast using as typeof import(...) or use the type
parameter, as TypeScript lacks a way to infer imports dynamically.
For example:
const myThing = t.mockRequire<
typeof import('../my-thing.js')
>('../my-thing.js', {
some: { tricky: 'mocks' },
})
Optionalmocks: Record<string, any>Create a test directory, optionally filling it up with contents
The testdir will be automatically deleted at the end of the test.
To not delete the directory after the test, use the
saveFixture: true option when creating the test, or specify
--save-fixture on the command line or in the tap configuration.
Optionalcontent: FixtureDirContentUnwind the mocks and free up the memory at the end of the test.
Called automatically if the @tapjs/after plugin is not disabled.
Run a child test that will run when the --only config is set,
or { runOnly: true } is set in the parent test options.
Run a child test that will run when the --only config is set,
or { runOnly: true } is set in the parent test options.
Run a child test that will run when the --only config is set,
or { runOnly: true } is set in the parent test options.
Run a child test that will run when the --only config is set,
or { runOnly: true } is set in the parent test options.
Spawn a child process and parse its standard output as a subtest
Spawn a child process and parse its standard output as a subtest
Optionalname: stringSpawn a child process and parse its standard output as a subtest
Optionalname: stringSpawn a child process and parse its standard output as a subtest
Optionalname: stringParse standard input as a child test
Start a Node Worker thread and parse its standard output as a child test
Start a Node Worker thread and parse its standard output as a child test
Optionalname: stringStart a Node Worker thread and parse its standard output as a child test
Optionalname: stringRuns the supplied function after the test is completely finished, and before the next test starts.
Run the supplied function after every child test, and any of those child tests' children, and so on.
The test that has just completed is passed in as an argument to the function. Note that at this point, the test is fully ended, so attempting to call assertion methods on it will raise an error.
Just run the supplied function right away, but do not run any child tests until it has completed.
This is handy when some setup may require asynchronous actions, and tests should wait until after it completes.
Run the supplied function before any child tests, and all of their children, and so on.
The test about to run is an argument to the function. While its test
method has not yet run, it is safe to call test methods on it, but note
that this may potentially be confusing if for example you call t.plan()
and this conflicts with the t.plan() called in the test method.
True if in the main thread. False when running in a worker thread spawned by t.worker
Interface that is the assembled result of every loaded plugin.
This is extended into an interface because otherwise the code hinting is overwhelmingly extravagant.