Module @tapjs/reporter - v4.0.1

@tapjs/reporter

A set of ink based reporters for tap, and utilities you can use to write your own.

The modern reincarnation of treport.

The following reporters are built into this module, and always available in node-tap.

--reporter=base is the default. It provides a reasonable amount of information about what's going on, without too much noise. If you run tap with --passes, then it'll show all the passing assertions, though that's often excessive, so it's off by default.

As the name suggests, the terse report shows much less information than base. But otherwise, they are very similar. If tests pass, it shows a very brief summary. When tests fail, it shows the same diffs, traces, and so on.

More terse than terse. Shows information about failures and todo items, but no summaries, counts, etc. For successful test runs, this is equivalent to silent.

The silent report prints nothing at all to the terminal, but still exits with an error status code if the tests did not pass.

The --reporter=tap option will output raw the TAP content, similar to just running the test programs directly.

XML output format used by JUnit. The testmoapp/junitxml repo has a good description of the format.

A single JSON object, somewhat similar in shape to the XML produced by the junit reporter.

Suite objects contain metadata about a test, and a list of suites and cases (ie, test point assertions). Suites can contain other suites.

The same data as the json format, but streamed as newline-delimited JSON.

Each line is an array with two members. The first is a string, one of 'start', 'end', 'pass', 'fail', 'skip' or 'todo'. The second is a data object, as follows:

  • start Initial metadata about a suite, before it has loaded any sub-suites or test cases.
  • end Final data about a suite, with counts and summary data.
  • pass, fail, skip, todo A test point of the specified type.

Similar data as shown by the jsonstream report, but formatted in Markdown.

The reporter config option can also be set to:

  • Any executable program - The TAP stream will be written to the program's standard input.
  • A module that exports a Stream class - The class will be instantiated, and the TAP stream piped into it.
  • A module that exports a React component - The component will be rendered using Ink, with the TAP object provided as the test prop, and the LoadedConfig as the config prop.

For streams and command-line reporters written in JavaScript, the tap-parser module is the best way to parse the incoming TAP stream. For other languages, there are many other TAP consumer libraries available.

For React component reporters, the components, hooks, and utilities in this package are likely very useful.

The easiest way to write a custom React reporter is as an ESM-only module that default exports its Reporter function on the main package module. Then, users can do --reporter <package-name> in their configs to use it.

Another way, if a reporter comes along with some other plugin functionality, is to add it to the default set via the API presented here. However, some care must be taken in that case, because @tapjs/reporter is ESM-only, and plugins must be compatible with both CommonJS and ESM. The @tapjs/dummy-plugin package contains an example of this.

The API available at import '@tapjs/reporter'.

The options provided to reports.

interface TapReportOpts {
test: TestBase
config: LoadedConfig
}

Alias for React.FC<TapReportOpts>

A record of all the known reporters, indexed by their config name.

Add a reporter at the name provided, so that it can be used on the --reporter config.

Render the specified reporter with the tap object and loaded config.

The --reporter=base implementation

The --reporter=terse implementation

Alias for the @tapjs/reporter/hooks module

Alias for the @tapjs/reporter/components module

Alias for the @tapjs/reporter/utils module

This provides a collection of useful components for building tap reports.

The relevant tags are listed here, but this module also exports several types and interfaces that they use for their property definitions.


Print a bold red "Bailout!" message if the test bails out.


Create a colorized diff from a patch string.


  Some very long string, which might wrap to multiple lines. Every
  line after the first is indented.

Indent every line after the first, useful when printing long stack frame lines.

Any ink Text properties are allowed.


Creates an ink <Static /> component containing console output, standard output, and (if includeTests is set) tests as they complete.

The component used by <Log /> to show lines for each test as it completes.

The component used by <Log /> to show console output in the runner process.

The component used by <Log /> to show stdio output from child test processes.


    !!t.counts.fail ||
    !!t.counts.skip ||
    !!t.counts.todo ||
    !t.parser.ok
  }
  Banner={
    
      tests complete
    
  }
/>

When the test suite is completed, this prints the Banner if provided, and then the detailed results of all tests that pass the filter.

By default, passing tests are excluded from this report.


Print detailed information about a test point's diagnostics.


Print a line for each test in progress, removing the line when it completes.


Pass in a test result.diag that has a source and callsite, and it'll return a prettied up source line with the callsite highlighted.


Print a stack string nicely.

Long lines are given a hanging indent, and local filenames are highlighted.


The 10 pass 3 fail 2 skip of 18 complete lines at the bottom of the test run.

Also prints Bailout! and Timeout messages.


The PASS, FAIL, etc. badges for a subtest.


Show the list of results for a completed test. (Shows nothing if the test is not yet complete.)

details is set in the display in the final test summary, false when used in the log.


Show the summary for a completed test with its test badge, result details, and so on.

The details flag will cause it to print the full diagnostic output for failing test points. It is set false when printing in the log, true when printing in the final test results report.


Print a bold red Timeout message when the suite times out.

Hook functions that can be used in components providing helpful test information that updates at the appropriate times.

An up to date test.assertTotals

true or the bailout reason if/when the test bails out. false otherwise.

The CleanupEffect type is a function that may take an array of cleanup methods as its first argument, and a doCleanup function as its second, and can optionally return a cleanup function as well.

By pushing onto the array, or returning a cleanup function of its own, the effect will be properly disposed as needed.

Useful in cases where you need to listen to multiple events, and clean them all up at the appropriate time.

Example:

import { useCleanup } from '@tapjs/reporter/hooks'
import { listenCleanup } from '@tapjs/reporter/utils'
const useMyHook = emitter => {
const [firsts, updateFirsts] = useState([])
const [seconds, updateSeconds] = useState([])
useCleanup((list, doCleanup) => {
// these event handlers will be cleaned up properly now
list.push(
listenCleanup(emitter, 'first', f =>
updateFirsts(firsts.concat([f])),
),
)
list.push(
listenCleanup(emitter, 'second', f =>
updateSeconds(seconds.concat([f])),
),
)
}, emitter)

return [firsts, seconds]
}

Returns a list of the comments made by the test.

Up to date t.counts and t.lists properties.

True if the test is done, false otherwise.

Returns an array of LogEntry items describing each entry in the log.

Return an array of all subtests meeting the which criteria.

  • active Tests that have started, but not completed.
  • finished Tests that have completed.
  • all All of the above.

Return a Counts object describing the suites in the test run.

The time this test has taken to complete, updated every interval milliseconds. 247 chosen as a default because it's fast and un-round enough to feel organic, without taxing the system with excessive time checks.

If the test has not timed out, returns undefined.

Otherwise, returns the Extra object describing the timeout failure. (Typically, extra.signal is the thing to care about.)

Some helpful utilities that are useful to have when creating reports.

Returns the appropriate full result name, including the test name, without repeating it.

Add the function as an event listener, returning a function that will remove the listener, for use with useEffect and useLayoutEffect hooks.

A slightly more granular form of the ms module from npm.

Very small float values are printed in µs, and only 3 digits of precision are ever shown.

Index

Modules