TAP Basics

Node-tap is a test framework library that you can use to writetests, and a command line program that can be used to run tests(and manage plugins, watch code for changes, analyze coverage,etc.)

Youcan use any of the parts independently, but they aredesigned to work well together.

Installing Tap#

You know the drill.

npminstall tap --save-dev

"Zero Patience Just Get Going" Guide#

Write a test file like this:

// give this a testy lookin filename, like// test/foo.js or ./lib/foo.test.jsimport tfrom'tap'import{ myThing}from'../src/whatever.js't.test('this is a child test',t=>{  t.pass('this passes')  t.fail('this fails')  t.ok(myThing,'this passes if truthy')  t.equal(myThing,5,'this passes if the values are equal')  t.match( myThing,{property: String,},'this passes if myThing.property is a string')// call this when you're done  t.end()})t.test('async tests work like you would expect',asynct=>{  t.equal(awaitmyThing(),'whatever')// don't have to call t.end(), it'll just end when the// async stuff is all resolved.})

Run it like this:

$ tap run

And you'll get reports like this:

$ tap run PASS docs/foo.test.js2OK427ms🌈   TEST COMPLETE🌈Asserts:2 pass0 fail2 of 2 completeSuites:1 pass0 fail1 of 1 complete# { total: 2, pass: 2 }# time=463.429ms

Tap can do a lot of stuff. Keep reading if you want to know more.

Writing Tests#

Every tap test is a standalone node program that outputsTAP to standard output.

This is a very simple tap test:

console.log(`TAP version 141..1ok`)

Thetap library can be used to output this format, but inmuch more useful and interesting ways.

First, pull in the rootTest object by importing it fromtap:

import tfrom'tap'

We use the namet by convention because it's easy and clean,but you can of course call it whatever you like.

Next, you can make some assertions:

import tfrom'tap't.pass('this is fine')

When run, that outputs:

$ node --loader=ts-node/esm --no-warnings --enable-source-maps t.mtsTAP version 14ok 1 - this is fine1..1# { total: 1, pass: 1 }# time=2.723ms

There are many more assertion methods provided by the@tapjs/assertsplugin.

import tfrom'tap'const myObject={ a:1, b:2}t.match(myObject,{ a: Number},'this passes')t.matchOnly(myObject,{ b:2},'this fails')

With this, we can see that thet.match() assertion passes,because the object has ana member which is anumber.However, thet.matchOnly() doesnot pass, because the objecthas other properties not specified in the comparison pattern.

$ node --loader=ts-node/esm --no-warnings --enable-source-maps t.mtsTAP version 14ok 1 - this passesnot ok 2 - this fails  ---  diff: |    --- expected    +++ actual    @@ -1,2 +1,3 @@     Object {    +  "a": 1,     }  at:    fileName: t.mts    lineNumber: 5    columnNumber: 3    isToplevel: true  stack: t.mts:5:3  source: |    const myObject = { a: 1, b: 2 }    t.match(myObject, { a: Number }, 'this passes')    t.matchOnly(myObject, { b: 2 }, 'this fails')    --^  ...1..2# { total: 2, pass: 1, fail: 1 }# time=13.576ms

When run with the tap cli, it looks like this:

$ tap t.mts FAIL t.mts1 failed of214ms✖ this failst.mts:5:3🌈   TEST COMPLETE🌈 FAIL t.mts1 failed of214ms✖ this failst.mts23const myObject ={ a:1, b:2}4t.match(myObject,{ a: Number},'this passes')5t.matchOnly(myObject,{ b:2},'this fails')━━━━┛--- expected+++ actual@@ -1,2 +1,3 @@ Object {+  "a": 1, }t.mts:5:3Asserts:1 pass1 fail2 of 2 completeSuites:0 pass1 fail1 of 1 complete# No coverage generated# { total: 2, pass: 1, fail: 1 }# time=45.911ms

The tap framework will print the assertion, as well asinformation about where the failure occurred, what was expected,and so on.

Child Tests#

It's usually convenient togroup tests into"suites" of assertions about related functionality.

This can be done in tap using thet.test()method.

import tfrom'tap'const myObject={ a:1, b:2}t.test('test myObject', t=>{  t.equal(myObject.a,1)  t.matchOnly(myObject,{ a: Number, b: Number})  t.end()})

Async Child Test Functions#

If you have asynchronous things to do in your subtest, or if youjust don't prefer having to remember to callt.end() when it'sover, your subtest method can return a promise.

import tfrom'tap'const myObject={ a:1, b:2, p:Promise.resolve('promise')}t.test('test myObject',async t=>{  t.equal(myObject.a,1)  t.matchOnly(myObject,{ a: Number, b: Number, p:Promise})  t.equal(await myObject.p,'promise')})

We don't have to callt.end() if we use async functions,because tap will automatically end the subtest when the returnedpromise resolves.

Planned Assertion Counts#

If you know how many assertions you expect to call, youcan uset.plan(n) to ensure that exactly that many areexecuted.

import tfrom'tap'const myObject={a:1,b:2}t.test('test myObject',asynct=>{  t.plan(2)  t.equal(myObject.a,1)  t.matchOnly(myObject,{a: Number,b: Number})})

We also don't have to callt.end() if we set a plan, becausetap will automatically end the child test when the plan iscompleted.

This is useful when you have a fixed number of assertions to run,but they can occur in any arbitrary order.

Running Tests#

While you can definitely just run your tests with node directly,it has some drawbacks:

If you use typescript or other functionality that depends on aloader, you have to remember to provide the proper argument.
The raw TAP output is very noisy (though sometimes it's good tobe able to look at it, it's usually just a lot).
It doesn't have pretty colors.
You can only run one test at a time.
You don't get coverage information without extra steps.

Thetapcommand line interface will run tests inparallel (as much as your system and configuration allow), withthe correct loaders all assembled in the arguments, and formatthe output so that excessive noise is eliminated, and actionableinformation is clearly highlighted.

$ tap t.mts PASS docs/foo.test.js2OK410ms🌈   TEST COMPLETE🌈Asserts:2 pass0 fail2 of 2 completeSuites:1 pass0 fail1 of 1 complete# No coverage generated# { total: 2, pass: 2 }# time=446.935ms

Code Coverage#

That# No coverage generated warning is telling you that thisdummy example test was kind of pointless, because it didn'tactually test anything.

If your test doesn't provide any code coverage, then it didn'treally test anything, and is not very helpful. That's why tapexits with an error status code when no coverage is generated, orwhen the tests don't fully cover the program you're testing.

See theCode Coverage guide for more informationabout how to get the most out of code coverage with tap.

Other Test Utilities#

Real world tests often have to create fixture files, spy on orintercept properties and methods, or swap out dependency modulesin order to trigger certain code paths and verify that theybehave properly. Check out the docs on these plugins for helpfulinformation as you write your tests:

@tapjs/intercept Spies andproperty/method interception.
@tapjs/mock Dependency injection byoverriding the behavior ofrequire() andimport, providingyour mock modules in place of the actual versions.
@tapjs/fixture Create temporary testdirectories which are automatically cleaned up when the testends.
@tapjs/snapshot Use thet.matchSnapshot method to save values to a file automaticallyby runningtap --snapshot, and then verify them later whenrunning the test.

For much more detail about the behavior ofTest objects in yourprogram, check out thefull generated typedocs for the Testclass

If there's some test functionality you need, and it's not alreadypresent, you can check for an existingpluginthat might provide it, orcreate oneyouself.

Note about "Expected Failures" and "Run Until Good" Testing#

Occasionally people ask for a way to run a test multiple times,and consider it "passing" if it passes at least once. Or even,run a test, and expect it to fail, but don't treat that as afailure.

An "expected failure" should be either marked astodo (meaningthat you'll get to it later), conditionally skipped on platformsthat don't support the feature (eg, doing unixy things onWindows, or vice versa), or deleted from the test suite.

Ignoring test failures is a very bad practice, as it reducesconfidence in your tests, which means that you can't just relaxand focus on your code.

import tfrom'tap'// this is finet.test('unixy thing',{  skip: process.platform==='win32'?'unix only':false,}, t=>{  t.equal(doUnixyThing(),true)  t.end()})// this is also finet.test('froblz is the blortsh',{  todo:'froblz not yet implemented',}, t=>{  t.equal(froblz(),'the blortsh')})

If you have a test thatsometimes passes, but is flaky, thenthat is a problem. Fix the problem! Let the test framework helpyou. Factor your code into more reasonable pieces that can betested independently from one another. There are a lot ofoptions, don't settle for having to remember which failures are"ok" and which are "real". All test failures are worth fixing!Why even have a test if you're ok with it failing?

Tap will never support such a thing. (Actually, it probably ispossible to do somehow with plugins. But don't! It's a horribleidea!)

Movatterモバイル変換

Node TAP21.1.0