Node-Tap Features

No Fancy DSL to Learn

The API is simple, but powerful.t.test() and a fewassertions are all you really need.Everything is statically typed, so your editor can tellyou what's available. Remember less, just write some tests.

(And there is actualy afancy DSL, ifyou're into that.)

Batteries Included

An easily extensibleTAP test framework, withoutstandingTypeScript support, aCLI,plenty of assertionmethods,snapshots,object/methodspies,modulemocking,file systemfixtures,lifecyclehooks,testfiltering, comprehensivecode coverageanalysis, color-accessibletestreporters, andmore!

Why TAP?

Why should you use this thing!?LET ME TELL YOU!

Just kidding.

Most frameworks spend a lot of their documentation telling youwhy they're the greatest. This isn't that. It's good, but it isopinionated.

tutti i gusti sono gusti

Software testing is a software and user experience designchallenge that balances on the intersection of many conflictingdemands.

Node-tap is based onmy opinions about how atest framework should work, and what it should let you do. I donot have any opinion about whether or not you share thoseopinions. If you do share them, you will probably enjoy this testlibrary.

Here are the design principles that shape this test framework.

Test files are "normal" programs

Any TAP test can be run directly as a plain old JavaScriptprogram. Of course, if it's written in TypeScript, you'llhave to run it with a TypeScript loader, but otherwise, theyshould be just like normal programs that run in a normalenvironment.

Therunner is a good way to run tests, but it's optional.Tests don't execute in a special simulated memory space withinjected globals, and so on. Because each test runs in its ownprocess, there's no chance of tests becoming dependent on oneanother's leaked globals or causing other confusing situations.

Tests should fun and helpful

The goal of tests is to help you write code. They add reliabilityto your program by adding a layer of "yes, this does what I thinkit does". Whether you're doing strict Red-Green-Refactor styleTDD, or just finger-painting until it feels right and thenwriting tests to verify what you did, writing the tests shouldfeel empowering and straightforward,reducing cognitive loadrather than increasing it.

Software tests should be a security blanket and a qualityratchet, giving you the support to undertake massive refactoringand fix bugs without worrying. It shouldn't be a purificationrite or a hazing ritual. It should be fun, because making stuffis fun, and it helps you make better stuff.

Type information must be accurate and complete

This is simply not reasonable to do with a hand-edited typedefinitions in.d.ts files.

TAP's exported types are built up from its set of plugins andinternal classes, assembled into theTest class thatyour test programs interact with. When a plugin is added orremoved, thet in your editor can accurately tell you its newshape.

If you have to look at the docs too often, that's a bug. Leaninto the beautiful power of code completion.

TypeScript, ESM, and CommonJS supported out of the box

Your tests should be written just like your program, with as fewbarriers as possible. If you can do it in CommonJS, you can do itin ESM, and vice versa (at least as far as TAP is concerned).Whatever is in yourtsconfig.json orpackage.json, it shouldJust Work.

Anything thatcan be a pluginis a plugin

The plugin system is leveraged for anything that does notabsolutely need to be included in the core.

BasicTAP generation and flow control, errorhandling, config loading, and process management are all includedin the core. ButTypeScript support,mocking, almost allassertionmethods,method and propertyspying,spawning/forking subtests,creatingfixtures,snapshots, and attachinglifecyclemethods (among others) are all relegated toplugins.

This means that features can be switched on or off or extendedvery easily.

Plugins must be powerful and trivial to write correctly

Theplugin interface is extremely simple. Export aplugin function that returns an object. That's it, that's aplugin.

Pluginscan also export configuration definitions, which arefolded into the set of fields that TAP knows how to parse fromthe command line or from your.taprc file, or export aloaderstring, which will be invoked when spawning test processes,making them an extremely powerful way to make your test frameworkwork for you.

High Signal, Low Noise

It is important to give a lot of information about test failures,throws, and so on, so that you can easily jump straight to theappropriate place in the code to fix the problem. And, it'susually helpful to see which tests are actually running.

However, a screen full of green checkmarks and100% Covered!isn't very useful. It should be just enough to know what happenedand easily diagnose any problems, and otherwise fairly quiet.

TAP tries to show you exactly what you need to see, and nothingelse. Low information output has been trimmed down as much as possible.Coverage information is only shown when it has something relevantto say. Stack traces have noisy internals trimmed out, so it'seasier to see exactly where inyour code the problem happened.Source maps are always enabled, because you need to know wherethe actual code is, not just which built artifact failed.

And if the default reporter isn't terse enough for your liking,trytap -Rterse.

Assertions don't throw (but throws are handled nicely)

I frequently write programs that have many hundreds of assertionsbased on some list of test cases. If the first failure throws,then I don't know if I've failed 100 tests or 1, without wrappingeverything in a try-catch.

Basically, it should be your decision whether you want to throwor not. The test framework shouldn't force that on you, andshould make either case easy.

Test reporting should be useful, extensible, and accessible

Theraw test output is machine-parseable andhuman-intelligible, and the reporter consumes that test outputto turn it into apretty summarized report. Thismeans that test data can be stored and parsed later, dug into foradditional details, and so on.

Red and green are the conventional colors meaning "removed" and"added", but they're also exactly the same color for many people.All of the color choices in the reporter are tested rigorouslyagainst simulators for protanopia, deuteranopia, tritanopia, andmonochromicity.

Test coverage is always on

Running tests with coverage changes the way that you think aboutyour programs, and provides much deeper insight. TAP uses V8'sinternal coverage mechanisms directly, and verifies that testsprovide 100% coverage of all lines, branches, functions, andstatements in the system under test. It usesC8 to analyze the V8 coverage data andgenerate coverage reports.

Missing coverage means that you are relying on untested code, sothis is treated as a test failure. If you have some bit of codewhich is actuallyimpossible to test for some reason, wrap itin the appropriate/* c8 ignore start */ //* c8 ignore end */ comments to exclude those lines from the analysis. But thinkcarefully about whether that's really the case. Usually, if youhave to coverage-ignore something, it's a sign that you need toeither delete that code or refactor it into a more easily testedmodule.

There are many opinions left off of this list! Reasonable peoplecan disagree. But if you find yourself nodding along,maybe tapis for you.